Upgrade to the Firebase 3.0.0 SDK

.gitignore

@@ -1,6 +1,8 @@
 .DS_Store
 npm-debug.log
 
+tests/key.json
+
 dist/
 coverage/
 node_modules/

.travis.yml

@@ -4,12 +4,17 @@ node_js:
 - '0.12'
 # - stable
 sudo: false
+env:
+  REACTFIRE_TEST_DB_URL=https://reactfire-bbede.firebaseio.com
 install:
 - npm install
 before_script:
 - export DISPLAY=:99.0
 - sh -e /etc/init.d/xvfb start
 script:
-- npm run travis
+- "[ -e tests/key.json ] && npm run travis || false"
 after_script:
 - cat ./tests/coverage/lcov.info | ./node_modules/coveralls/bin/coveralls.js
+before_install:
+- openssl aes-256-cbc -K $encrypted_f7671fde2e57_key -iv $encrypted_f7671fde2e57_iv
+  -in tests/key.json.enc -out tests/key.json -d

README.md

@@ -1,18 +1,28 @@
-# ReactFire
+# ReactFire [![Build Status](https://travis-ci.org/firebase/reactfire.svg?branch=master)](https://travis-ci.org/firebase/reactfire) [![Coverage Status](https://coveralls.io/repos/firebase/reactfire/badge.svg?branch=master&service=github)](https://coveralls.io/github/firebase/reactfire?branch=master) [![GitHub version](https://badge.fury.io/gh/firebase%2Freactfire.svg)](http://badge.fury.io/gh/firebase%2Freactfire)
 
-[![Build Status](https://travis-ci.org/firebase/reactfire.svg?branch=master)](https://travis-ci.org/firebase/reactfire)
-[![Coverage Status](https://coveralls.io/repos/firebase/reactfire/badge.svg?branch=master&service=github)](https://coveralls.io/github/firebase/reactfire?branch=master)
-[![GitHub version](https://badge.fury.io/gh/firebase%2Freactfire.svg)](http://badge.fury.io/gh/firebase%2Freactfire)
 
-[ReactJS](http://facebook.github.io/react/) is a framework for building large, complex user
-interfaces. [Firebase](http://www.firebase.com/?utm_source=reactfire) complements it perfectly
-by providing an easy-to-use, realtime data source for populating the `state` of React components.
-With [ReactFire](https://www.firebase.com/docs/web/libraries/react/?utm_source=reactfire), it only
-takes a few lines of JavaScript to integrate Firebase data into React apps via the `ReactFireMixin`.
+[ReactJS](https://facebook.github.io/react/) is a framework for building large, complex user
+interfaces. [Firebase](https://firebase.google.com/) complements it perfectly by providing an
+easy-to-use, realtime data source for populating the `state` of React components. With ReactFire, it
+only takes a few lines of JavaScript to integrate Firebase data into React apps via the
+`ReactFireMixin`.
 
-[Read through our documentation](https://www.firebase.com/docs/web/libraries/react/?utm_source=reactfire)
-on using Firebase with React and [check out our live Todo app demo](https://reactfiretodoapp.firebaseapp.com/)
-to get started!
+
+## Table of Contents
+
+ * [Getting Started With Firebase](#getting-started-with-firebase)
+ * [Downloading ReactFire](#downloading-reactfire)
+ * [Documentation](#documentation)
+ * [Examples](#examples)
+ * [Migration Guides](#migration-guides)
+ * [Contributing](#contributing)
+
+
+## Getting Started With Firebase
+
+ReactFire requires [Firebase](https://firebase.google.com/) in order to sync and store data.
+Firebase is a suite of integrated products designed to help you develop your app, grow your user
+base, and earn money. You can [sign up here for a free account](https://console.firebase.google.com/).
 
 
 ## Downloading ReactFire
@@ -25,62 +35,42 @@ In order to use ReactFire in your project, you need to include the following fil
 <script src="https://fb.me/react-dom-15.0.1.min.js"></script>
 
 <!-- Firebase -->
-<script src="https://cdn.firebase.com/js/client/2.4.0/firebase.js"></script>
+<script src="https://www.gstatic.com/firebasejs/3.0.3/firebase.js"></script>
 
 <!-- ReactFire -->
-<script src="https://cdn.firebase.com/libs/reactfire/0.7.0/reactfire.min.js"></script>
+<script src="https://cdn.firebase.com/libs/reactfire/1.0.0/reactfire.min.js"></script>
 ```
 
-Use the URL above to download both the minified and non-minified versions of ReactFire from the
-Firebase CDN. You can also download them from the
-[releases page of this GitHub repository](https://github.com/firebase/reactfire/releases).
-[Firebase](https://www.firebase.com/docs/web/quickstart.html?utm_source=reactfire) and
-[React](http://facebook.github.io/react/downloads.html) can be downloaded directly from their
-respective websites.
-
 You can also install ReactFire via npm or Bower. If downloading via npm, you will have to install
 React and Firebase separately (that is, they are `peerDependencies`):
 
 ```bash
 $ npm install reactfire react firebase --save
 ```
 
-On Bower, the React and Firebase dependencies will be downloaded automatically:
+On Bower, the React and Firebase dependencies will be downloaded automatically alongside ReactFire:
 
 
 ```bash
 $ bower install reactfire --save
 ```
 
+## Documentation
 
-## Getting Started with Firebase
-
-ReactFire requires Firebase in order to store data. You can
-[sign up here for a free account](https://www.firebase.com/signup/?utm_source=reactfire).
-
+* [Quickstart](docs/quickstart.md)
+* [Guide](docs/guide.md)
+* [API Reference](docs/reference.md)
 
-## Usage
 
-To use the `ReactFireMixin` in a React component, add it to the component's `mixins` property:
-
-```javascript
-var ExampleComponent = React.createClass({
-  mixins: [ReactFireMixin],
-  ...
-});
-```
+## Examples
 
-The ReactFire APIs will then be available from the `this` object inside of `ExampleComponent`.
+* [Todo App](examples/todoApp)
+* [Comments Box](examples/commentsBox)
 
 
-## Documentation and API Reference
+## Migration Guides
 
-The [ReactFire quickstart](https://www.firebase.com/docs/web/libraries/react/quickstart.html?utm_source=reactfire)
-is a great place to get started. There is a walkthrough on how to create the
-[Todo app demo](https://reactfiretodoapp.firebaseapp.com/) in the
-[ReactFire guide](https://www.firebase.com/docs/web/libraries/react/guide.html?utm_source=reactfire).
-Finally, there is a [full API reference](https://www.firebase.com/docs/web/libraries/react/api.html?utm_source=reactfire)
-as well.
+* [Migrating from ReactFire `0.7.0` to `1.x.x`](docs/migration/070-to-1XX.md)
 
 
 ## Contributing

bower.json

@@ -33,6 +33,6 @@
   ],
   "dependencies": {
     "react": "0.13.x || 0.14.x || 15.x.x",
-    "firebase": "2.x.x"
+    "firebase": "2.x.x || 3.x.x"
   }
 }

docs/guide.md

@@ -0,0 +1,216 @@
+# Guide | ReactFire
+
+
+## Table of Contents
+
+ * [What Is ReactJS?](#what-is-reactjs)
+ * [Adding Firebase to Your React App](#adding-firebase-to-your-react-app)
+ * [`ReactFireMixin`](#reactfiremixin)
+ * [Next Steps](#next-steps)
+
+
+## What Is ReactJS?
+
+[ReactJS](http://facebook.github.io/react/) is a JavaScript library built by Facebook and Instagram
+which makes it easy to build large, complex user interfaces. The creators of React describe it as
+the “V[iew] in MVC.” It is not meant to be a replacement for Angular or Ember; instead, it is meant
+to extend their functionality by providing a high-performance way to keep a view up-to-date with
+JavaScript. Its special sauce is that it renders HTML using an incredibly fast virtual DOM diff
+algorithm, providing much better performance than competing platforms. It has a “one-way reactive
+data flow” which is much simpler to understand than traditional data-binding.
+
+Components - the basic building blocks of React apps - are organized in a tree hierarchy in which
+parent components send data down to their children through the props variable. Each component also
+has a `state` variable which determines the current data for its view. Whenever `state` is changed,
+the component’s render() method is called and React figures out the most efficient way to update the
+DOM.
+
+Since React’s main focus is on the user interface, React apps need something else to act as their
+backend. That is where Firebase comes in. It adds the “M[odel] and C[ontroller] in MVC” to React
+apps, making them fully functioning apps. **Using React’s straightforward binding system, it is easy
+to integrate Firebase in a native way with only a small amount of code.**
+
+
+## Adding Firebase to Your React App
+
+Let's look at the Todo app on the [React homepage](http://facebook.github.io/react/). Within the
+`TodoApp` component, `this.state` is used to keep track of the input text and the list of Todo
+items. While React ensures that the DOM stays in sync with any changes to `this.state`, the changes
+do not persist beyond the life of the page. If you add a few items and then refresh the page, all of
+the items disappear! This is because **React has no mechanism for storing data beyond the scope of
+the current page session**. It relies on being used with another framework to do that.
+
+**Firebase is a natural complement to React as it provides React apps with a persistent, realtime
+backend**. The first thing we need to do is add Firebase to your project:
+
+```js
+<!-- React JS -->
+<script src="https://fb.me/react-15.1.0.js"></script>
+<script src="https://fb.me/react-dom-15.1.0.js"></script>
+
+<!-- Firebase -->
+<script src="https://www.gstatic.com/firebasejs/3.0.3/firebase.js"></script>
+```
+
+We'll need to initialize the Firebase SDK before we can use it. This should happen one time, outside
+of your React component. You can find more details on the [web](https://firebase.google.com/docs/web/setup)
+or [Node.js](https://firebase.google.com/docs/server/setup) setup guides.
+
+```js
+<script>
+  var config = {
+    apiKey: "<YOUR-API-KEY>",
+
+    // Only needed if using Firebase Realtime Database (which we will be in this example)
+    databaseURL: "https://<YOUR-DATABASE-NAME>.firebaseio.com",
+
+    // Only needed if using Firebase Authentication
+    authDomain: "<YOUR-AUTH-DOMAIN>",
+
+    // Only needed if using Firebase Storage
+    storageBucket: "<YOUR-STORAGE-BUCKET>.appspot.com"
+  };
+
+  firebase.initializeApp(config);
+</script>
+```
+
+Now that we have included Firebase, we can populate the list of Todo items by reading them from the
+database. We do this by hooking into the `componentWillMount()` method of the `TodoApp` component
+which is run once, immediately before the initial rendering of the component:
+
+```js
+componentWillMount: function() {
+  this.firebaseRef = firebase.database.ref("items");
+  this.firebaseRef.on("child_added", function(dataSnapshot) {
+    this.items.push(dataSnapshot.val());
+    this.setState({
+      items: this.items
+    });
+  }.bind(this));
+}
+```
+
+This code first gets a reference to the `items` node at the root of the database. The call to `on()`
+will be run every time a node is added under the `items` node. It is important to realize that a
+`child_added` event will be fired for every item under the `items` node, not just new ones that are
+added to it. Therefore, when the page is loaded, every existing child under the `items` node will
+fire a `child_added` event, meaning they can easily be iterated over and added to `this.state.items`.
+Note that the call at the end to `bind()` just sets the scope of callback function to this.
+
+What about adding new Todo items to the database? That code is just as easy:
+
+```js
+handleSubmit: function(e) {
+  e.preventDefault();
+  this.firebaseRef.push({
+    text: this.state.text
+  });
+  this.setState({text: ""});
+}
+```
+
+Within `handleSubmit()` a new item is pushed onto the database reference which appends it to the end
+of the `items` node. The call to `setState()` updates `this.state.text` but does not need to update
+`this.state.items` as it did in the original React code. This is because the `child_added` event
+handler from `componentWillMount()` will be fired when a new child is pushed onto the `items` node
+and that code will update `this.state.items`.
+
+The last thing that needs to happen is cleaning up the database event handler:
+
+```js
+componentWillUnmount: function() {
+  this.firebaseRef.off();
+}
+```
+
+With just the few changes above, items added to the Todo list are updated in realtime. Best of all,
+the items stick around if the page is refreshed! You can even open multiple tabs pointed at the same
+page and see them all update simultaneously, with Firebase doing all the heavy lifting. Take some
+time to [view the code for this example](https://github.com/firebase/ReactFire/blob/master/examples/todoApp/js/todoAppFirebaseExplicit.js)
+and [play around with a live demo](https://reactfiretodoapp.firebaseapp.com/).
+
+
+## `ReactFireMixin`
+
+Although integrating Firebase into a React app only takes a few lines of code out of the box, we
+wanted to make it even easier. We also want to be able to handle when array items are removed or
+updated from Firebase. **We built the `ReactFireMixin` to make it simple to keep `this.state` in
+sync with a database node.**
+
+To get started with ReactFire, include it in your project by loading the library directly from our
+CDN and placing it right after the React and Firebase libraries in the `<head>` tag:
+
+```js
+<!-- React JS -->
+<script src="https://fb.me/react-15.1.0.js"></script>
+<script src="https://fb.me/react-dom-15.1.0.js"></script>
+
+<!-- Firebase -->
+<script src="https://www.gstatic.com/firebasejs/3.0.3/firebase.js"></script>
+
+<!-- ReactFire -->
+<script src="https://cdn.firebase.com/libs/reactfire/1.0.0/reactfire.min.js"></script>
+```
+
+ReactFire and its dependencies are also available from npm via `npm install reactfire` and Bower
+via `bower install reactfire`.
+
+After making sure to initialize the Firebase SDK again, we can then use the `ReactFireMixin` in the
+`TodoApp` component, add it to the component's `mixins` property:
+
+```js
+var TodoApp = React.createClass({
+  mixins: [ReactFireMixin],
+  ...
+});
+```
+
+The `ReactFireMixin` extends the functionality of the `TodoApp` component, adding additional
+Firebase-specific methods to it. To keep `this.state.items` in sync with any changes to the `items`
+node, make the following change in `componentWillMount()`:
+
+```js
+componentWillMount: function() {
+  var ref = firebase.database().ref("items");
+  this.bindAsArray(ref, "items");
+}
+```
+
+We simply specify that we want to bind a particular Firebase Database reference to `this.state.items`
+of the React component. The `ReactFireMixin` allows binding to a node as an array or as a regular
+JavaScript object. This creates a one-way binding from the `Firebase` reference to `this.state.items`,
+meaning that if the data in the database changes, so will `this.state.items`. However, if we update
+`this.state.items`, the database data will not change. Therefore, changes should be made directly to
+the database and not by calling `setState()`:
+
+```js
+handleSubmit: function(e) {
+  e.preventDefault();
+  this.firebaseRefs.items.push({
+    text: this.state.text
+  });
+  this.setState({ text: "" });
+}
+```
+
+**ReactFire allows for binding to multiple things at once.** Firebase ensures that this is all done
+in an efficient manner. To access the `Firebase` reference which is bound to `this.state.items`, we
+can reference `this.firebaseRefs["items"]` which is provided by ReactFire. Finally, calling
+`this.firebaseRef.off()` is no longer needed in `componentWillUnmount()` as the mixin handles this
+behind the scenes.
+
+You can [view the code for this example](https://github.com/firebase/ReactFire/blob/master/examples/todoApp/js/todoAppFirebaseImplicit.js)
+and [play around with a live demo](https://reactfiretodoapp.firebaseapp.com/). The code and demo add
+the ability to delete items in the array and have them automatically synced back to `this.state.items`.
+
+
+## Next Steps
+
+ReactJS is a wonderful framework for creating user interfaces. When picking a complementary tool to
+use alongside it as a backend, Firebase is the easiest and most powerful solution. In just a few
+lines of code you can get a React app syncing data across hundreds of clients at once. ReactFire
+makes this that much easier, getting rid of even more boilerplate code.
+
+Head on over to the [ReactFire API reference](reference.md) and then get started building an app
+with ReactFire!

docs/migration/070-to-1XX.md

@@ -0,0 +1,11 @@
+# Migrating from ReactFire `0.7.0` to `1.x.x`
+
+This migration document covers all the major breaking changes mentioned in the [ReactFire `1.0.0`
+change log](https://github.com/firebase/reactfire/releases/tag/v1.0.0).
+
+
+## Upgrade your Firebase SDK
+
+While ReactFire `1.0.0` continues to support all `2.x.x` versions of the Firebase SDK, we encourage
+you to upgrade to version `3.x.x`. See the [Firebase `3.x.x` migration
+guide](https://firebase.google.com/support/guides/firebase-web) for more details.