Skip to content

Commit 3540fc3

Browse files
andipaetzoldandipaetzold
committed
docs: update readmes
1 parent abfc463 commit 3540fc3

File tree

5 files changed

+146
-118
lines changed

5 files changed

+146
-118
lines changed

‎README.md‎

Lines changed: 10 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,15 +1,19 @@
1+
Temporary package to migrate `react-firebase-hooks` to Firebase v9.
2+
13
# React Firebase Hooks
24

35
A set of reusable [React Hooks](https://reactjs.org/docs/hooks-intro.html) for [Firebase](https://firebase.google.com/).
46

57
[![npm version](https://img.shields.io/npm/v/react-firebase-hooks.svg?style=flat-square)](https://www.npmjs.com/package/react-firebase-hooks)
68
[![npm downloads](https://img.shields.io/npm/dm/react-firebase-hooks.svg?style=flat-square)](https://www.npmjs.com/package/react-firebase-hooks)
79

8-
**This documentation is for v3 of React Firebase Hooks which involved a number of breaking changes, including adding support for Firebase v8.0.0 - more details [here](https://github.com/CSFrequency/react-firebase-hooks/releases/tag/v3.0.0). For v2 documentation, see [here](https://github.com/CSFrequency/react-firebase-hooks/tree/v2.2.0).**
10+
This documentation is for v4 of React Firebase Hooks which involved a number of breaking changes, including adding support for Firebase v9 - more details [here](https://github.com/CSFrequency/react-firebase-hooks/releases/tag/v4.0.0).
11+
- For v3 documentation (Firebase v8), see [here](https://github.com/CSFrequency/react-firebase-hooks/tree/v3.0.0).
12+
- For v2 documentation, see [here](https://github.com/CSFrequency/react-firebase-hooks/tree/v2.2.0).
913

1014
## Installation
1115

12-
React Firebase Hooks v3 requires **React 16.8.0 or later** and **Firebase v8.0.0 or later**.
16+
React Firebase Hooks v4 requires **React 16.8.0 or later** and **Firebase v9.0.0 or later**.
1317

1418
> Official support for Hooks was added to React Native in v0.59.0. React Firebase Hooks works with both the Firebase JS SDK and React Native Firebase, although some of the typings may be incorrect.
1519
@@ -29,6 +33,10 @@ There has been a **lot** of hype around React Hooks, but this hype merely reflec
2933

3034
This library explores how React Hooks can work to make integration with Firebase even more straightforward than it already is. It takes inspiration for naming from RxFire and is based on an internal library that we had been using in a number of apps prior to the release of React Hooks. The implementation with hooks is 10x simpler than our previous implementation.
3135

36+
## Upgrading from v3 to v4
37+
38+
To upgrade your project from v3 to v4 check out the [Release Notes](https://github.com/CSFrequency/react-firebase-hooks/releases/tag/v4.0.0) which have full details of everything that needs to be changed.
39+
3240
## Upgrading from v2 to v3
3341

3442
To upgrade your project from v2 to v3 check out the [Release Notes](https://github.com/CSFrequency/react-firebase-hooks/releases/tag/v3.0.1) which have full details of everything that needs to be changed.

‎auth/README.md‎

Lines changed: 18 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
# React Firebase Hooks - Auth
22

3-
React Firebase Hooks provides a convenience listener for Firebase Auth's auth state. The hook wraps around the `firebase.auth().onAuthStateChange()` method to ensure that it is always up to date.
3+
React Firebase Hooks provides a convenience listener for Firebase Auth's auth state. The hook wraps around the `auth.onAuthStateChange(auth.getAuth(firebaseApp))` method to ensure that it is always up to date.
44

55
All hooks can be imported from `react-firebase-hooks/auth`, e.g.
66

@@ -24,30 +24,33 @@ Retrieve and monitor the authentication state from Firebase.
2424

2525
The `useAuthState` hook takes the following parameters:
2626

27-
- `auth`: `firebase.auth.Auth` instance for the app you would like to monitor
27+
- `auth`: `auth.Auth` instance for the app you would like to monitor
2828

2929
Returns:
3030

31-
- `user`: The `firebase.User` if logged in, or `undefined` if not
31+
- `user`: The `auth.User` if logged in, or `undefined` if not
3232
- `loading`: A `boolean` to indicate whether the the authentication state is still being loaded
33-
- `error`: Any `firebase.auth.Error` returned by Firebase when trying to load the user, or `undefined` if there is no error
33+
- `error`: Any `AuthError` returned by Firebase when trying to load the user, or `undefined` if there is no error
3434

3535
#### If you are registering or signing in the user for the first time consider using [useCreateUserWithEmailAndPassword](#usecreateuserwithemailandpassword), [useSignInWithEmailAndPassword](#usesigninwithemailandpassword)
3636

3737
#### Full Example
3838

3939
```js
40+
import { getAuth, signInWithEmailAndPassword, signOut } from 'firebase/auth';
4041
import { useAuthState } from 'react-firebase-hooks/auth';
4142

43+
const auth = getAuth(firebaseApp)
44+
4245
const login = () => {
43-
firebase.auth().signInWithEmailAndPassword('test@test.com', 'password');
46+
signInWithEmailAndPassword(auth, 'test@test.com', 'password');
4447
};
4548
const logout = () => {
46-
firebase.auth().signOut();
49+
signOut(auth)
4750
};
4851

4952
const CurrentUser = () => {
50-
const [user, loading, error] = useAuthState(firebase.auth());
53+
const [user, loading, error] = useAuthState(auth);
5154

5255
if (loading) {
5356
return (
@@ -90,17 +93,17 @@ Create a user with email and password. Wraps the underlying `firebase.auth().cre
9093

9194
The `useCreateUserWithEmailAndPassword` hook takes the following parameters:
9295

93-
- `auth`: `firebase.auth.Auth` instance for the app you would like to monitor
96+
- `auth`: `auth.Auth` instance for the app you would like to monitor
9497
- `options`: (optional) `Object` with the following parameters:
95-
- `emailVerificationOptions`: (optional) `firebase.auth.ActionCodeSettings` to customise the email verification
98+
- `emailVerificationOptions`: (optional) `auth.ActionCodeSettings` to customise the email verification
9699
- `sendEmailVerification`: (optional) `boolean` to trigger sending of an email verification after the user has been created
97100

98101
Returns:
99102

100103
- `createUserWithEmailAndPassword(email: string, password: string)`: a function you can call to start the registration
101-
- `user`: The `firebase.User` if the user was created or `undefined` if not
104+
- `user`: The `User` if the user was created or `undefined` if not
102105
- `loading`: A `boolean` to indicate whether the the user creation is processing
103-
- `error`: Any `firebase.auth.Error` returned by Firebase when trying to create the user, or `undefined` if there is no error
106+
- `error`: Any `Error` returned by Firebase when trying to create the user, or `undefined` if there is no error
104107

105108
#### Full Example
106109

@@ -165,18 +168,18 @@ const [
165168
] = useSignInWithEmailAndPassword(auth, email, password);
166169
```
167170

168-
Login a user with email and password. Wraps the underlying `firebase.auth().signInWithEmailAndPassword` method and provides additional `loading` and `error` information.
171+
Login a user with email and password. Wraps the underlying `auth.signInWithEmailAndPassword` method and provides additional `loading` and `error` information.
169172

170173
The `useSignInWithEmailAndPassword` hook takes the following parameters:
171174

172-
- `auth`: `firebase.auth.Auth` instance for the app you would like to monitor
175+
- `auth`: `Auth` instance for the app you would like to monitor
173176

174177
Returns:
175178

176179
- `signInWithEmailAndPassword(email: string, password: string)`: a function you can call to start the login
177-
- `user`: The `firebase.User` if the user was logged in or `undefined` if not
180+
- `user`: The `auth.User` if the user was logged in or `undefined` if not
178181
- `loading`: A `boolean` to indicate whether the the user login is processing
179-
- `error`: Any `firebase.auth.Error` returned by Firebase when trying to login the user, or `undefined` if there is no error
182+
- `error`: Any `Error` returned by Firebase when trying to login the user, or `undefined` if there is no error
180183

181184
#### Full Example
182185

‎database/README.md‎

Lines changed: 44 additions & 33 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
# React Firebase Hooks - Realtime Database
22

33
React Firebase Hooks provides convenience listeners for lists and values stored within the
4-
Firebase Realtime Database. The hooks wrap around the `firebase.database().ref().on()` method.
4+
Firebase Realtime Database. The hooks wrap around the `onX(ref(firebase, 'path'), ...)` method.
55

66
In addition to returning the list or value, the hooks provide an `error` and `loading` property
77
to give a complete lifecycle for loading and listening to the Realtime Database.
@@ -14,11 +14,16 @@ import { useList } from 'react-firebase-hooks/database';
1414

1515
List of Realtime Database hooks:
1616

17-
- [useList](#uselist)
18-
- [useListKeys](#uselistkeys)
19-
- [useListVals](#uselistvals)
20-
- [useObject](#useobject)
21-
- [useObjectVal](#useobjectval)
17+
- [React Firebase Hooks - Realtime Database](#react-firebase-hooks---realtime-database)
18+
- [useList](#uselist)
19+
- [Full Example](#full-example)
20+
- [useListKeys](#uselistkeys)
21+
- [useListVals](#uselistvals)
22+
- [useObject](#useobject)
23+
- [Full Example](#full-example-1)
24+
- [useObjectVal](#useobjectval)
25+
- [Transforming data](#transforming-data)
26+
- [Full Example](#full-example-2)
2227

2328
Additional functionality:
2429

@@ -34,21 +39,24 @@ Retrieve and monitor a list value in the Firebase Realtime Database.
3439

3540
The `useList` hook takes the following parameters:
3641

37-
- `reference`: (optional) `firebase.database.Reference` for the data you would like to load
42+
- `reference`: (optional) `database.Reference` for the data you would like to load
3843

3944
Returns:
4045

41-
- `snapshots`: an array of `firebase.database.DataSnapshot`, or `undefined` if no reference is supplied
46+
- `snapshots`: an array of `database.DataSnapshot`, or `undefined` if no reference is supplied
4247
- `loading`: a `boolean` to indicate if the data is still being loaded
43-
- `error`: Any `firebase.FirebaseError` returned by Firebase when trying to load the data, or `undefined` if there is no error
48+
- `error`: Any `Error` returned by Firebase when trying to load the data, or `undefined` if there is no error
4449

4550
#### Full Example
4651

4752
```js
53+
import { ref, getDatabase } from 'firebase/database';
4854
import { useList } from 'react-firebase-hooks/database';
4955

56+
const database = getDatabase(firebaseApp);
57+
5058
const DatabaseList = () => {
51-
const [snapshots, loading, error] = useList(firebase.database().ref('list'));
59+
const [snapshots, loading, error] = useList(ref(database, 'list'));
5260

5361
return (
5462
<div>
@@ -77,40 +85,40 @@ const DatabaseList = () => {
7785
const [keys, loading, error] = useListKeys(reference);
7886
```
7987

80-
As `useList`, but this hooks extracts the `firebase.database.DataSnapshot.key` values, rather than the the `firebase.database.DataSnapshot`s themselves.
88+
As `useList`, but this hooks extracts the `database.DataSnapshot.key` values, rather than the the `database.DataSnapshot`s themselves.
8189

8290
The `useListKeys` hook takes the following parameters:
8391

84-
- `reference`: (optional) `firebase.database.Reference` for the data you would like to load
92+
- `reference`: (optional) `database.Reference` for the data you would like to load
8593

8694
Returns:
8795

8896
- `keys`: an array of `string`, or `undefined` if no reference is supplied
8997
- `loading`: a `boolean` to indicate if the data is still being loaded
90-
- `error`: Any `firebase.FirebaseError` returned by Firebase when trying to load the data, or `undefined` if there is no error
98+
- `error`: Any `Error` returned by Firebase when trying to load the data, or `undefined` if there is no error
9199

92100
### useListVals
93101

94102
```js
95-
const [values, loading, error] = useListVals < T > (reference, options);
103+
const [values, loading, error] = useListVals<T> (reference, options);
96104
```
97105

98-
As `useList`, but this hook extracts a typed list of the `firebase.database.DataSnapshot.val()` values, rather than the the
99-
`firebase.database.DataSnapshot`s themselves.
106+
As `useList`, but this hook extracts a typed list of the `database.DataSnapshot.val()` values, rather than the the
107+
`database.DataSnapshot`s themselves.
100108

101109
The `useListVals` hook takes the following parameters:
102110

103-
- `reference`: (optional) `firebase.database.Reference` for the data you would like to load
111+
- `reference`: (optional) `database.Reference` for the data you would like to load
104112
- `options`: (optional) `Object` with the following parameters:
105-
- `keyField`: (optional) `string` field name that should be populated with the `firebase.database.DataSnapshot.id` property in the returned values.
106-
- `refField`: (optional) `string` field name that should be populated with the `firebase.database.DataSnapshot.ref` property.
107-
- `transform`: (optional) a function that receives the raw `firebase.database.DataSnapshot.val()` for each item in the list to allow manual transformation of the data where required by the application. See [`Transforming data`](#transforming-data) below.
113+
- `keyField`: (optional) `string` field name that should be populated with the `database.DataSnapshot.id` property in the returned values.
114+
- `refField`: (optional) `string` field name that should be populated with the `database.DataSnapshot.ref` property.
115+
- `transform`: (optional) a function that receives the raw `database.DataSnapshot.val()` for each item in the list to allow manual transformation of the data where required by the application. See [`Transforming data`](#transforming-data) below.
108116

109117
Returns:
110118

111119
- `values`: an array of `T`, or `undefined` if no reference is supplied
112120
- `loading`: a `boolean` to indicate if the data is still being loaded
113-
- `error`: Any `firebase.FirebaseError` returned by Firebase when trying to load the data, or `undefined` if there is no error
121+
- `error`: Any `Error` returned by Firebase when trying to load the data, or `undefined` if there is no error
114122

115123
### useObject
116124

@@ -122,21 +130,24 @@ Retrieve and monitor an object or primitive value in the Firebase Realtime Datab
122130

123131
The `useObject` hook takes the following parameters:
124132

125-
- `reference`: (optional) `firebase.database.Reference` for the data you would like to load
133+
- `reference`: (optional) `database.Reference` for the data you would like to load
126134

127135
Returns:
128136

129-
- `snapshot`: a `firebase.database.DataSnapshot`, or `undefined` if no reference is supplied
137+
- `snapshot`: a `database.DataSnapshot`, or `undefined` if no reference is supplied
130138
- `loading`: a `boolean` to indicate if the data is still being loaded
131-
- `error`: Any `firebase.FirebaseError` returned by Firebase when trying to load the data, or `undefined` if there is no error
139+
- `error`: Any `Error` returned by Firebase when trying to load the data, or `undefined` if there is no error
132140

133141
#### Full Example
134142

135143
```js
144+
import { ref, getDatabase } from 'firebase/database';
136145
import { useObject } from 'react-firebase-hooks/database';
137146

147+
const database = getDatabase(firebaseApp);
148+
138149
const DatabaseValue = () => {
139-
const [snapshot, loading, error] = useObject(firebase.database().ref('value'));
150+
const [snapshot, loading, error] = useObject(ref(database, 'value'));
140151

141152
return (
142153
<div>
@@ -153,25 +164,25 @@ const DatabaseValue = () => {
153164
### useObjectVal
154165

155166
```js
156-
const [value, loading, error] = useObjectVal < T > (reference, options);
167+
const [value, loading, error] = useObjectVal<T> (reference, options);
157168
```
158169

159-
As `useObject`, but this hook returns the typed contents of `firebase.database.DataSnapshot.val()`, rather than the the
160-
`firebase.database.DataSnapshot` itself.
170+
As `useObject`, but this hook returns the typed contents of `database.DataSnapshot.val()`, rather than the the
171+
`database.DataSnapshot` itself.
161172

162173
The `useObjectVal` hook takes the following parameters:
163174

164-
- `reference`: (optional) `firebase.database.Reference` for the data you would like to load
175+
- `reference`: (optional) `database.Reference` for the data you would like to load
165176
- `options`: (optional) `Object` with the following parameters:
166-
- `keyField`: (optional) `string` field name that should be populated with the `firebase.database.DataSnapshot.key` property in the returned value.
167-
- `refField`: (optional) `string` field name that should be populated with the `firebase.database.DataSnapshot.ref` property.
168-
- `transform`: (optional) a function that receives the raw `firebase.database.DataSnapshot.val()` to allow manual transformation of the data where required by the application. See [`Transforming data`](#transforming-data) below.
177+
- `keyField`: (optional) `string` field name that should be populated with the `database.DataSnapshot.key` property in the returned value.
178+
- `refField`: (optional) `string` field name that should be populated with the `database.DataSnapshot.ref` property.
179+
- `transform`: (optional) a function that receives the raw `database.DataSnapshot.val()` to allow manual transformation of the data where required by the application. See [`Transforming data`](#transforming-data) below.
169180

170181
Returns:
171182

172183
- `value`: a `T`, or `undefined` if no reference is supplied
173184
- `loading`: a `boolean` to indicate if the data is still being loaded
174-
- `error`: Any `firebase.FirebaseError` returned by Firebase when trying to load the data, or `undefined` if there is no error
185+
- `error`: Any `FirebaseError` returned by Firebase when trying to load the data, or `undefined` if there is no error
175186

176187
## Transforming data
177188

0 commit comments

Comments
 (0)