Skip to content

Commit bd8642d

Browse files
nicolasgarniernicolasgarnier
authored
Merge pull request #133 from firebase/deprecation
Marking ReactFire as deprecated.
2 parents 420e7e5 + 14c4f9f commit bd8642d

File tree

1 file changed

+230
-56
lines changed

1 file changed

+230
-56
lines changed

‎README.md

Lines changed: 230 additions & 56 deletions
Original file line numberDiff line numberDiff line change
@@ -1,80 +1,254 @@
1-
# 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)
2-
1+
# ReactFire is deprecated
2+
3+
ReactFire is deprecated. To use Firebase on React application you can use either:
4+
- The [Firebase JS SDK](https://www.npmjs.com/package/firebase) directly. See below for [Firebase + React samples](#using-the-firebase-js-sdk-in-react)) and [migration guides](#migrating-from-reactfire).
5+
- The [Re-base](https://www.npmjs.com/package/re-base) library which is close to reactfire in design.
6+
- The [react-redux-firebase](https://github.com/prescottprue/react-redux-firebase) library if you are using Redux in your React app.
7+
8+
> To access the former README you can check out the [v1.0.0 tag](https://github.com/firebase/reactfire/tree/v1.0.0)
9+
10+
## Using the Firebase JS SDK in React
11+
12+
To use the Firebase JS SDK in React, you can follow these guidelines:
13+
- Initialize Firebase in your app once, for instance outside the React components or in a separate module and export the firebase App.
14+
- Create your Firebase data observers in `componentDidMount` lifecycle methods.
15+
- Map your Firebase data to the local state in the data observers.
16+
- Un-subscribe your Firebase data observers in `componentWillUnmount` lifecycle methods to avoid memory leaks and unintended behaviors.
17+
- When updating data: update the data on Firebase directly. Do not update the local state because it won't update the data on Firebase but updating Firebase will trigger your local observers instantly.
18+
19+
20+
### Initialize Firebase
21+
22+
Initialize Firebase once, for example in a separate module (e.g. `firebase.js`) and export the Firebase app. You can find more details on the [web](https://firebase.google.com/docs/web/setup) setup guides:
23+
24+
**firebase.js**
25+
```js
26+
// Import the Firebase modules that you need in your app.
27+
import firebase from 'firebase/app';
28+
import 'firebase/auth';
29+
import 'firebase/database';
30+
import 'firebase/datastore';
31+
32+
// Initalize and export Firebase.
33+
const config = {
34+
apiKey: '<YOUR-API-KEY>',
35+
authDomain: '<YOUR-AUTH-DOMAIN>',
36+
databaseURL: 'https://<YOUR-DATABASE-NAME>.firebaseio.com',
37+
projectId: '<YOUR-PROJECT-ID>',
38+
storageBucket: '<YOUR-STORAGE-BUCKET>.appspot.com',
39+
messagingSenderId: '<YOUR-MESSAGING-SENDER-ID>'
40+
};
41+
export default firebase.initializeApp(config);
42+
```
343

4-
[ReactJS](https://facebook.github.io/react/) is a framework for building large, complex user
5-
interfaces. [Firebase](https://firebase.google.com/) complements it perfectly by providing an
6-
easy-to-use, realtime data source for populating the `state` of React components. With ReactFire, it
7-
only takes a few lines of JavaScript to integrate Firebase data into React apps via the
8-
`ReactFireMixin`.
944

45+
### Firebase Auth
46+
47+
Here is an example of how you can map the Firebase authentication state to your React component's local state:
48+
49+
```js
50+
import firebase from './firebase.js';
51+
52+
class MyComponent extends React.Component {
53+
state = {
54+
isSignedIn: false,
55+
userProfile: null
56+
};
57+
58+
componentDidMount() {
59+
this.deregisterAuthObservable = firebase.auth().onAuthStateChanged((user) => {
60+
this.setState({ isSignedIn: !!user, userProfile: user });
61+
});
62+
}
63+
64+
componentWillUnmount() {
65+
this.deregisterAuthObservable();
66+
}
67+
68+
// ...
69+
}
70+
```
1071

11-
## Table of Contents
1272

13-
* [Getting Started With Firebase](#getting-started-with-firebase)
14-
* [Downloading ReactFire](#downloading-reactfire)
15-
* [Documentation](#documentation)
16-
* [Examples](#examples)
17-
* [Release Notes](https://github.com/firebase/reactfire/releases)
18-
* [Migration Guides](#migration-guides)
19-
* [Contributing](#contributing)
73+
### Firebase Realtime Database
74+
75+
Here is an example of how you can map data from the Realtime Databaseto your React component's local state:
76+
77+
```js
78+
import firebase from './firebase.js';
79+
80+
class MyComponent extends React.Component {
81+
state = {
82+
someData: {}
83+
};
84+
85+
componentDidMount() {
86+
// Updating the `someData` local state attribute when the Firebase Realtime Database data
87+
// under the '/someData' path changes.
88+
this.firebaseRef = firebase.database().ref('/someData');
89+
this.firebaseCallback = this.firebaseRef.on('value', (snap) => {
90+
this.setState({ someData: snap.val() });
91+
});
92+
}
93+
94+
componentWillUnmount() {
95+
// Un-register the listener on '/someData'.
96+
this.firebaseRef.off('value', this.firebaseCallback);
97+
}
98+
99+
// ...
100+
}
101+
```
20102

21103

22-
## Getting Started With Firebase
104+
### Firebase Cloud Datastore
105+
106+
Here is an example of how you can map data from the Cloud Datastore in a React component:
107+
108+
```js
109+
import firebase from './firebase.js';
110+
111+
class MyComponent extends React.Component {
112+
state = {
113+
someCollection: {},
114+
someDocument: null
115+
};
116+
117+
componentDidMount() {
118+
// Updating the `someCollection` local state attribute when the Cloud Firestore 'someCollection' collection changes.
119+
this.unsubscribeCollectionObserver = firebase.firestore().collection('someCollection').onSnapshot((snap) => {
120+
const someCollection = {};
121+
snap.forEach((docSnapshot) => {
122+
someCollection[docSnapshot.id] = docSnapshot.data();
123+
});
124+
this.setState({ someCollection: someCollection });
125+
});
126+
127+
// Updating the `someDocument` local state attribute when the Cloud Firestore 'someDocument' document changes.
128+
this.unsubscribeDocumentObserver = firebase.firestore().doc('/collection/someDocument').onSnapshot((snap) => {
129+
this.setState({ someDocument: snap.data() });
130+
});
131+
}
132+
133+
componentWillUnmount() {
134+
// Un-register the listeners.
135+
this.unsubscribeCollectionObserver();
136+
this.unsubscribeDocumentObserver();
137+
}
138+
139+
// ...
140+
}
141+
```
23142

24-
ReactFire requires [Firebase](https://firebase.google.com/) in order to sync and store data.
25-
Firebase is a suite of integrated products designed to help you develop your app, grow your user
26-
base, and earn money. You can [sign up here for a free account](https://console.firebase.google.com/).
143+
### Updating data
144+
145+
When updating data, do not set the local state. Setting the local state will not update Firebase. Instead you should update your data on Firebase directly, this will trigger any observers that you have setup locally instantly from cache.
146+
147+
For instance, let's take an app that has a list of todo items stored on Firebase. It also has a text field and a button to add new todos:
148+
149+
```js
150+
import firebase from './firebase.js';
151+
152+
class MyComponent extends React.Component {
153+
state = {
154+
todoList: {},
155+
newTodoText: ''
156+
};
157+
158+
componentDidMount() {
159+
// Updating the `todoList` local state attribute when the Firebase Realtime Database data
160+
// under the '/todoList' path changes.
161+
this.firebaseRef = firebase.database().ref('/todoList');
162+
this.firebaseCallback = this.firebaseRef.on('value', (snap) => {
163+
this.setState({ todoList: snap.val() });
164+
});
165+
}
166+
167+
componentWillUnmount() {
168+
// Un-register the listener on '/todoList'.
169+
this.firebaseRef.off('value', this.firebaseCallback);
170+
}
171+
172+
onSubmit(e) {
173+
e.preventDefault();
174+
// Add the new todo to Firebase.
175+
this.firebaseRef.push({
176+
text: this.state.newTodoText
177+
});
178+
// Clearing the text field.
179+
this.setState({text: ''});
180+
}
181+
182+
// ...
183+
}
184+
```
27185

186+
Note how we are not updating the `todoList` in the local state. You only need to update Firebase and the Firebase observer that was set up will take care of propagating the changes and updating the local state.
28187

29-
## Downloading ReactFire
30188

31-
In order to use ReactFire in your project, you need to include the following files in your HTML:
189+
## Migrating from ReactFire
32190

33-
```html
34-
<!-- React -->
35-
<script src="https://fb.me/react-15.3.0.min.js"></script>
36-
<script src="https://fb.me/react-dom-15.3.0.min.js"></script>
191+
To migrate from ReactFire to using the Firebase JS SDK first remove the `ReactFireMixin` that was applied to any of your React components.
37192

38-
<!-- Firebase -->
39-
<script src="https://www.gstatic.com/firebasejs/3.3.0/firebase.js"></script>
193+
### Migrate `bindAsObject` calls
40194

41-
<!-- ReactFire -->
42-
<script src="https://cdn.firebase.com/libs/reactfire/1.0.0/reactfire.min.js"></script>
43-
```
195+
In all component that are using [bindAsObject(firebaseRef, bindVar, cancelCallback)](https://github.com/firebase/reactfire/blob/master/docs/reference.md#bindasobjectfirebaseref-bindvar-cancelcallback) change from:
44196

45-
You can also install ReactFire via npm or Bower. If downloading via npm, you will have to install
46-
React and Firebase separately (that is, they are `peerDependencies`):
197+
```js
198+
componentWillMount: function() {
199+
var ref = firebase.database().ref().child("users/fred");
200+
this.bindAsObject(ref, "user");
201+
}
47202

48-
```bash
49-
$ npm install reactfire react firebase --save
203+
componentWillUnmount: function() {
204+
this.unbind("user");
205+
}
50206
```
51207

52-
On Bower, the React and Firebase dependencies will be downloaded automatically alongside ReactFire:
53-
54-
55-
```bash
56-
$ bower install reactfire --save
208+
to:
209+
210+
```js
211+
componentDidMount: function() {
212+
this.firebaseCallback = firebase.database().ref('/users/fred').on('value', function(snap) {
213+
this.setState({ user: snap.val() });
214+
});
215+
}
216+
217+
componentWillUnmount: function() {
218+
firebase.database().ref('/users/fred').off('value', this.firebaseCallback);
219+
}
57220
```
58221

59-
## Documentation
60-
61-
* [Quickstart](docs/quickstart.md)
62-
* [Guide](docs/guide.md)
63-
* [API Reference](docs/reference.md)
64-
65-
66-
## Examples
67222

68-
* [Todo App](examples/todoApp)
69-
* [Comments Box](examples/commentsBox)
223+
### Migrate `bindAsObject` calls
70224

225+
In all component that are using [bindAsArray(firebaseRef, bindVar, cancelCallback)](https://github.com/firebase/reactfire/blob/master/docs/reference.md#bindasarrayfirebaseref-bindvar-cancelcallback) change from:
71226

72-
## Migration Guides
227+
```js
228+
componentWillMount: function() {
229+
var ref = firebase.database().ref("items");
230+
this.bindAsArray(ref, "items");
231+
}
73232

74-
* [Migrating from ReactFire `0.7.0` to `1.x.x`](docs/migration/070-to-1XX.md)
75-
76-
77-
## Contributing
233+
componentWillUnmount: function() {
234+
this.unbind("items");
235+
}
236+
```
78237

79-
If you'd like to contribute to ReactFire, please first read through our [contribution
80-
guidelines](.github/CONTRIBUTING.md). Local setup instructions are available [here](.github/CONTRIBUTING.md#local-setup).
238+
to:
239+
240+
```js
241+
componentDidMount: function() {
242+
this.firebaseCallback = firebase.database().ref('/items').on('value', function(snap) {
243+
var items = [];
244+
snap.forEach(function(itemSnap) {
245+
items.push(itemSnap.val());
246+
});
247+
this.setState({ items: items });
248+
});
249+
}
250+
251+
componentWillUnmount: function() {
252+
firebase.database().ref('/items').off('value', this.firebaseCallback);
253+
}
254+
```

0 commit comments

Comments
 (0)