mirror of
https://github.com/zhigang1992/reactfire.git
synced 2026-06-11 16:30:12 +08:00
model after rxfire docs
This commit is contained in:
jhuleatt
448
README.md
448
README.md
@@ -1,389 +1,89 @@
|
||||
# Reactfire
|
||||
|
||||
```bash
|
||||
npm install reactfire
|
||||
# or
|
||||
yarn add reactfire
|
||||
```
|
||||
|
||||
[Hooks](https://reactjs.org/docs/hooks-intro.html), Context Providers, and Components that make it easy
|
||||
to interact with Firebase.
|
||||
|
||||
By default, every `reactfire` hook _throws a Promise_ until it has
|
||||
connected to Firebase, allowing you to use [Suspense](https://reactjs.org/docs/code-splitting.html#suspense) to render a fallback component. If you don't want `reactfire` to throw a promise, pass an initial value to a `reactfire` hook. It will emit the initial value right away instead of throwing a promise.
|
||||
> _!!!_ If you're looking for docs for the deprecated ReactFire v1 (the one that uses mixins), click [here](https://github.com/FirebaseExtended/reactfire/tree/v1.0.0)
|
||||
|
||||
- [**Quickstart**](#Quickstart)
|
||||
- [**Docs**](#Docs)
|
||||
- [**Contributing**](#Contributing)
|
||||
## What is ReactFire?
|
||||
|
||||
## Quickstart
|
||||
- **Easy realtime updates for your function components** - Reactfire's hooks, like `useFirestoreCollection` and `useUser`, let you easily subscribe to events, and automatically unsubscribe when your component unmounts.
|
||||
- **Loading states handled by `<Suspense>`** - Reactfire's hooks throw promises that Suspense can catch. No more `isLoaded ?...` - let React [handle it for you](https://reactjs.org/blog/2018/11/27/react-16-roadmap.html#react-166-shipped-the-one-with-suspense-for-code-splitting).
|
||||
- **Dead-simple Real User Monitoring (RUM)** - Easily enable Firebase Performance Monitoring's [automatic traces](https://firebase.google.com/docs/perf-mon/automatic-web), and instrument your Suspenseful loads with Reactfire's `<SuspenseWithPerf>` component
|
||||
|
||||
⚛ + 🔥 = 🌯
|
||||
Status: Beta
|
||||
|
||||
We'll build a web app that displays, in _real time_, the tastiness of a burrito. It will listen to **Cloud Firestore** for its data, and we'll configure **Firebase Performance Monitoring** so we can get some perf stats.
|
||||
## Install
|
||||
|
||||
> Prerequisite: make sure you have [Node.js](https://nodejs.org/en/) installed.
|
||||
|
||||
1. In a terminal, create a fresh React app and `cd` into its directory.
|
||||
|
||||
```shell
|
||||
npx create-react-app myapp
|
||||
cd myapp
|
||||
```
|
||||
|
||||
1. Install reactfire and the Firebase SDK
|
||||
|
||||
```bash
|
||||
yarn add firebase reactfire@canary
|
||||
# or
|
||||
npm install firebase reactfire@canary
|
||||
```
|
||||
|
||||
1. Create a document in Cloud Firestore.
|
||||
|
||||
1. Go to the _Database_ tab in the Firebase console. If your project doesn't have a Cloud Firestore instance yet, initialize it in locked mode
|
||||
1. Add a document
|
||||
|
||||
1. In the _Data_ tab of the console, click _Add Collection_
|
||||
|
||||
1. Name the collection **_tryreactfire_**
|
||||
1. Add a document with ID **_burrito_** and boolean field `yummy: true`
|
||||
|
||||
|
||||
|
||||
1. Add the following to your security rules and click _Publish_
|
||||
|
||||
```text
|
||||
match /tryreactfire/burrito {
|
||||
allow read: if true;
|
||||
allow write: if request.auth.uid != null;
|
||||
}
|
||||
```
|
||||
|
||||
1. Modify `src/index.js`
|
||||
|
||||
1. Import firebase and reactfire
|
||||
|
||||
```js
|
||||
//...
|
||||
import { FirebaseAppProvider } from 'reactfire';
|
||||
import 'firebase/performance';
|
||||
//...
|
||||
```
|
||||
|
||||
1. Wrap your app in a `FirebaseAppProvider` and provide the config object from the Firebase console
|
||||
|
||||
```jsx
|
||||
//...
|
||||
const firebaseConfig = {
|
||||
/* add your config object from Firebase console */
|
||||
};
|
||||
ReactDOM.render(
|
||||
<FirebaseAppProvider firebaseConfig={firebaseConfig} initPerformance>
|
||||
<App />
|
||||
</FirebaseAppProvider>,
|
||||
document.getElementById('root')
|
||||
);
|
||||
//...
|
||||
```
|
||||
|
||||
1. Modify `src/App.js`
|
||||
|
||||
1. Import `firebase/firestore` as well as the `useFirestoreDoc` and `useFirebaseApp` hooks
|
||||
|
||||
```js
|
||||
//...
|
||||
import 'firebase/firestore';
|
||||
import {
|
||||
useFirestoreDoc,
|
||||
useFirebaseApp,
|
||||
SuspenseWithPerf
|
||||
} from 'reactfire';
|
||||
//...
|
||||
```
|
||||
|
||||
1. Add a function component
|
||||
|
||||
```jsx
|
||||
//...
|
||||
function Burrito() {
|
||||
// create a ref
|
||||
const firebaseApp = useFirebaseApp();
|
||||
const burritoRef = firebaseApp
|
||||
.firestore()
|
||||
.collection('tryreactfire')
|
||||
.doc('burrito');
|
||||
|
||||
// get the doc. just one line!
|
||||
const burritoDoc = useFirestoreDoc(burritoRef);
|
||||
|
||||
// get the value from the doc
|
||||
const isYummy = burritoDoc.data().yummy;
|
||||
|
||||
return <p>The burrito is {isYummy ? 'good' : 'bad'}</p>;
|
||||
}
|
||||
//...
|
||||
```
|
||||
|
||||
1. Render your component inside of a `Suspense` tag
|
||||
|
||||
> We need to do this because `useFirestoreDoc` throws a Promise while it is waiting for a response from Firestore. Suspense will catch the Promise and render `fallback` until the Promise is resolved.
|
||||
|
||||
Replace the `App` function with the following:
|
||||
|
||||
```jsx
|
||||
//...
|
||||
function App() {
|
||||
return (
|
||||
<div className="App">
|
||||
<SuspenseWithPerf
|
||||
fallback={'loading burrito status...'}
|
||||
traceId={'load-burrito-status'}
|
||||
>
|
||||
<Burrito />
|
||||
</SuspenseWithPerf>
|
||||
</div>
|
||||
);
|
||||
}
|
||||
//...
|
||||
```
|
||||
|
||||
1. Run your app!
|
||||
|
||||
```bash
|
||||
yarn start
|
||||
# or
|
||||
npm run start
|
||||
```
|
||||
|
||||
1. Edit the value of `yummy` in the Firebase console, and watch it update in real time in your app! 🔥🔥🔥
|
||||
|
||||
1. _But what about Firebase Performance Monitoring?_
|
||||
|
||||
By passing the `initPerformance` prop to `FirebaseAppProvider`, our app will automatically measure [common performance stats](https://firebase.google.com/docs/perf-mon/automatic-web), as well as report on our custom trace, `load-burrito-status`, that we set in the `traceId` prop of `SuspenseWithPerf`.
|
||||
|
||||
However, Firebase Performance Monitoring can take about 12 hours to crunch your data and show it in the _Performance_ tab of the Firebase console.
|
||||
|
||||
This is an example of some of the stats in the Firebase Performance Monitoring console after 12 hours:
|
||||
|
||||
|
||||
|
||||
## Docs
|
||||
|
||||
### ToC
|
||||
|
||||
- Providers
|
||||
- [`FirebaseAppProvider`](#FirebaseAppProvider)
|
||||
- Hooks
|
||||
- [`useFirebaseApp`](#useFirebaseApp)
|
||||
- Authentication
|
||||
- [`useUser`](#useUser)
|
||||
- Database
|
||||
- Cloud Firestore
|
||||
- [`useFirestoreDoc`](#useFirestoreDoc)
|
||||
- [`useFirestoreCollection`](#useFirestoreCollection)
|
||||
- Realtime Database
|
||||
- [`useDatabaseObject`](#useDatabaseObject)
|
||||
- [`useDatabaseList`](#useDatabaseList)
|
||||
- Cloud Storage
|
||||
- [`useStorageTask`](#useStorageTask)
|
||||
- [`useStorageDownloadURL`](#useStorageDownloadURL)
|
||||
- Components
|
||||
- Performance Monitoring
|
||||
- [`SuspenseWithPerf`](#SuspenseWithPerf)
|
||||
- Authentication
|
||||
- [`AuthCheck`](#AuthCheck)
|
||||
|
||||
### Providers
|
||||
|
||||
#### `FirebaseAppProvider`
|
||||
|
||||
A React [Context Provider](https://reactjs.org/docs/context.html#contextprovider) that allows the `useFirebaseApp` hook to pick up the `firebase` object.
|
||||
|
||||
##### Sample usage
|
||||
|
||||
```jsx
|
||||
const firebaseConfig = {
|
||||
/* web app config from Firebase console */
|
||||
};
|
||||
|
||||
<FirebaseAppProvider firebaseConfig={firebaseConfig} initPerformance>
|
||||
<App />
|
||||
</FirebaseAppProvider>;
|
||||
```bash
|
||||
# npm
|
||||
npm install reactfire
|
||||
# yarn
|
||||
yarn add reactfire
|
||||
```
|
||||
|
||||
##### Props
|
||||
|
||||
| Prop | Type | Description |
|
||||
| --------------- | ------ | ---------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| config | Object | the web app config object usually passed to [`initializeApp`](https://firebase.google.com/docs/reference/js/firebase.html#initializeapp) |
|
||||
| initPerformance | bool | Whether or not to initialize Firebase Performance Monitoring |
|
||||
|
||||
### Hooks
|
||||
|
||||
#### `useFirebaseApp`
|
||||
|
||||
When called from a component nested inside a `FirebaseAppProvider`, `useFirebaseApp` returns the root Firebase object.
|
||||
|
||||
> IMPORTANT: By default, `useFirebaseApp` returns a firebase object without any products attached to it (e.g. you can't call `firebase.firestore()`. To do that, you need to `import 'firebase/firestore'` or any other Firebase feature as needed)
|
||||
|
||||
##### Returns
|
||||
|
||||
[`firebase`](https://firebase.google.com/docs/reference/js/firebase)
|
||||
|
||||
#### `useUser`
|
||||
|
||||
Get the user that is currently signed in.
|
||||
|
||||
_Throws a Promise by default_
|
||||
|
||||
##### Parameters
|
||||
|
||||
| Parameter | Type | Description |
|
||||
| ----------- | ------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------- |
|
||||
| auth _?_ | [`Auth`](https://firebase.google.com/docs/reference/js/firebase.auth.Auth.html) | [optional] auth object. If not provided, useUser will use `useFirebaseApp` to find the Auth object. |
|
||||
| options _?_ | ReactFireOptions | Options. This hook will not throw a Promise if you provide `startWithValue`. |
|
||||
|
||||
##### Returns
|
||||
|
||||
[`User`](https://firebase.google.com/docs/reference/js/firebase.User)
|
||||
|
||||
#### `useFirestoreDoc`
|
||||
|
||||
Listen to a Firestore Document.
|
||||
|
||||
_Throws a Promise by default_
|
||||
|
||||
##### Parameters
|
||||
|
||||
| Parameter | Type | Description |
|
||||
| ----------- | --------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------- |
|
||||
| ref | [`DocumentReference`](https://firebase.google.com/docs/reference/js/firebase.firestore.DocumentReference) | A reference to the document you want to listen to |
|
||||
| options _?_ | ReactFireOptions | Options. This hook will not throw a Promise if you provide `startWithValue`. |
|
||||
|
||||
##### Returns
|
||||
|
||||
[`DocumentSnapshot`](https://firebase.google.com/docs/reference/js/firebase.firestore.DocumentSnapshot)
|
||||
|
||||
#### `useFirestoreCollection`
|
||||
|
||||
Listen to a Firestore Collection.
|
||||
|
||||
_Throws a Promise by default_
|
||||
|
||||
##### Parameters
|
||||
|
||||
| Parameter | Type | Description |
|
||||
| ----------- | ------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------- |
|
||||
| ref | [`CollectionReference`](https://firebase.google.com/docs/reference/js/firebase.firestore.CollectionReference) | A reference to the collection you want to listen to |
|
||||
| options _?_ | ReactFireOptions | Options. This hook will not throw a Promise if you provide `startWithValue`. |
|
||||
|
||||
##### Returns
|
||||
|
||||
[`QuerySnapshot`](https://firebase.google.com/docs/reference/js/firebase.firestore.QuerySnapshot)
|
||||
|
||||
#### `useDatabaseObject`
|
||||
|
||||
Listen to a Realtime Database Object.
|
||||
|
||||
_Throws a Promise by default_
|
||||
|
||||
##### Parameters
|
||||
|
||||
| Parameter | Type | Description |
|
||||
| ----------- | ---------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------- |
|
||||
| ref | [`Reference`](https://firebase.google.com/docs/reference/js/firebase.database.Reference) | A reference to the object you want to listen to |
|
||||
| options _?_ | ReactFireOptions | Options. This hook will not throw a Promise if you provide `startWithValue`. |
|
||||
|
||||
##### Returns
|
||||
|
||||
[`QueryChange`](https://github.com/firebase/firebase-js-sdk/blob/6b53e0058483c9002d2fe56119f86fc9fb96b56c/packages/rxfire/database/interfaces.ts#L28)
|
||||
|
||||
#### `useDatabaseList`
|
||||
|
||||
Listen to a Realtime Database list.
|
||||
|
||||
_Throws a Promise by default_
|
||||
|
||||
##### Parameters
|
||||
|
||||
| Parameter | Type | Description |
|
||||
| ----------- | ---------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------- |
|
||||
| ref | [`Reference`](https://firebase.google.com/docs/reference/js/firebase.database.Reference) | A reference to the list you want to listen to |
|
||||
| options _?_ | ReactFireOptions | Options. This hook will not throw a Promise if you provide `startWithValue`. |
|
||||
|
||||
##### Returns
|
||||
|
||||
[`QueryChange[]`](https://github.com/firebase/firebase-js-sdk/blob/6b53e0058483c9002d2fe56119f86fc9fb96b56c/packages/rxfire/database/interfaces.ts#L28)
|
||||
|
||||
#### `useStorageTask`
|
||||
|
||||
Listen to a Storage UploadTask
|
||||
|
||||
_Throws a Promise by default_
|
||||
|
||||
##### Parameters
|
||||
|
||||
| Parameter | Type | Description |
|
||||
| ----------- | ----------------------------------------------------------------------------------------- | ----------- |
|
||||
| task | [`UploadTask`](https://firebase.google.com/docs/reference/js/firebase.storage.UploadTask) | |
|
||||
| ref | [`Reference`](https://firebase.google.com/docs/reference/js/firebase.storage.Reference) | |
|
||||
| options _?_ | ReactFireOptions | |
|
||||
|
||||
##### Returns
|
||||
|
||||
[`UploadTaskSnapshot`](https://firebase.google.com/docs/reference/js/firebase.storage.UploadTaskSnapshot)
|
||||
|
||||
#### `useStorageDownloadURL`
|
||||
|
||||
Subscribe to a storage blob's download URL
|
||||
|
||||
_Throws a Promise by default_
|
||||
|
||||
#### Parameters
|
||||
|
||||
| Parameter | Type | Description |
|
||||
| ----------- | --------------------------------------------------------------------------------------- | ----------- |
|
||||
| ref | [`Reference`](https://firebase.google.com/docs/reference/js/firebase.storage.Reference) | |
|
||||
| options _?_ | ReactFireOptions | |
|
||||
|
||||
##### Returns
|
||||
|
||||
`string`
|
||||
|
||||
### Components
|
||||
|
||||
#### `AuthCheck`
|
||||
|
||||
Renders `children` if a user is signed in and meets the required claims. Renders `fallback` otherwise.
|
||||
|
||||
##### Props
|
||||
|
||||
| Property | Type |
|
||||
| -------------- | --------------- |
|
||||
| auth | Auth |
|
||||
| children | React.Component |
|
||||
| fallback | React.Component |
|
||||
| requiredClaims | Object |
|
||||
|
||||
#### `SuspenseWithPerf`
|
||||
|
||||
Starts a Firebase Performance Monitoring [trace](https://firebase.google.com/docs/reference/js/firebase.performance.Trace) and ends it when suspense stops suspending.
|
||||
|
||||
##### Props
|
||||
|
||||
| Property | Type |
|
||||
| ------------ | --------------- |
|
||||
| children | React.Component |
|
||||
| fallback | React.Component |
|
||||
| firePerf _?_ | any |
|
||||
| traceId | string |
|
||||
|
||||
### ReactFireOptions
|
||||
|
||||
| Property | Type |
|
||||
| -------------- | ---- |
|
||||
| startWithValue | any |
|
||||
## Example use
|
||||
|
||||
Check out the [live version on StackBlitz](https://stackblitz.com/edit/reactfire-sample)!
|
||||
|
||||
```jsx
|
||||
import React, { Component } from 'react';
|
||||
import { render } from 'react-dom';
|
||||
import './style.css';
|
||||
import {
|
||||
FirebaseAppProvider,
|
||||
useFirestoreDoc,
|
||||
useFirebaseApp,
|
||||
SuspenseWithPerf
|
||||
} from 'reactfire';
|
||||
|
||||
import 'firebase/performance';
|
||||
import 'firebase/firestore';
|
||||
|
||||
const firebaseConfig = {
|
||||
/* add your config object from the Firebase console */
|
||||
};
|
||||
|
||||
function Burrito() {
|
||||
// create a ref
|
||||
const firebaseApp = useFirebaseApp();
|
||||
const burritoRef = firebaseApp
|
||||
.firestore()
|
||||
.collection('tryreactfire')
|
||||
.doc('burrito');
|
||||
|
||||
// subscribe to the doc. just one line!
|
||||
// throws a Promise for Suspense to catch,
|
||||
// and then streams live updates
|
||||
const burritoDoc = useFirestoreDoc(burritoRef);
|
||||
|
||||
// get the value from the doc
|
||||
const isYummy = burritoDoc.data().yummy;
|
||||
|
||||
return <p>The burrito is {isYummy ? 'good' : 'bad'}!</p>;
|
||||
}
|
||||
|
||||
function App() {
|
||||
return (
|
||||
<FirebaseAppProvider firebaseConfig={firebaseConfig} initPerformance>
|
||||
<h1>🌯</h1>
|
||||
<SuspenseWithPerf
|
||||
fallback={'loading burrito status...'}
|
||||
traceId={'load-burrito-status'}
|
||||
>
|
||||
<Burrito />
|
||||
</SuspenseWithPerf>
|
||||
</FirebaseAppProvider>
|
||||
);
|
||||
}
|
||||
|
||||
render(<App />, document.getElementById('root'));
|
||||
```
|
||||
|
||||
## Learn More
|
||||
|
||||
- [**Quickstart**](./docs/quickstart.md)
|
||||
- [**Docs**](./docs/reference.md)
|
||||
|
||||
## Contributing
|
||||
|
||||
|
||||
157
docs/quickstart.md
Normal file
157
docs/quickstart.md
Normal file
@@ -0,0 +1,157 @@
|
||||
# Reactfire Quickstart
|
||||
|
||||
⚛ + 🔥 = 🌯
|
||||
|
||||
We'll build a web app that displays, in _real time_, the tastiness of a burrito. It will listen to **Cloud Firestore** for its data, and we'll configure **Firebase Performance Monitoring** so we can get some perf stats.
|
||||
|
||||
To see the completed app, check out [this StackBlitz workspace](https://stackblitz.com/edit/reactfire-sample).
|
||||
|
||||
## 1. In a terminal, create a fresh React app and `cd` into its directory.
|
||||
|
||||
> Prerequisite: make sure you have [Node.js](https://nodejs.org/en/) installed.
|
||||
|
||||
```shell
|
||||
npx create-react-app myapp
|
||||
cd myapp
|
||||
```
|
||||
|
||||
## 2. Install reactfire and the Firebase SDK
|
||||
|
||||
```bash
|
||||
# yarn
|
||||
yarn add firebase reactfire@canary
|
||||
|
||||
# or
|
||||
|
||||
# npm
|
||||
npm install firebase reactfire@canary
|
||||
```
|
||||
|
||||
## 3. Create a document in Cloud Firestore
|
||||
|
||||
1. Go to the _Database_ tab in the Firebase console. If your project doesn't have a Cloud Firestore instance yet, initialize it in locked mode
|
||||
1. Add a document
|
||||
|
||||
1. In the _Data_ tab of the console, click _Add Collection_
|
||||
|
||||
1. Name the collection **_tryreactfire_**
|
||||
1. Add a document with ID **_burrito_** and boolean field `yummy: true`
|
||||
|
||||
|
||||
|
||||
1. Add the following to your security rules and click _Publish_
|
||||
|
||||
```text
|
||||
match /tryreactfire/burrito {
|
||||
allow read: if true;
|
||||
allow write: if request.auth.uid != null;
|
||||
}
|
||||
```
|
||||
|
||||
## 4. Modify `src/index.js`
|
||||
|
||||
1. Import firebase and reactfire
|
||||
|
||||
```js
|
||||
//...
|
||||
import { FirebaseAppProvider } from 'reactfire';
|
||||
import 'firebase/performance';
|
||||
//...
|
||||
```
|
||||
|
||||
1. Wrap your app in a `FirebaseAppProvider` and provide the config object from the Firebase console
|
||||
|
||||
```jsx
|
||||
//...
|
||||
const firebaseConfig = {
|
||||
/* add your config object from Firebase console */
|
||||
};
|
||||
ReactDOM.render(
|
||||
<FirebaseAppProvider firebaseConfig={firebaseConfig} initPerformance>
|
||||
<App />
|
||||
</FirebaseAppProvider>,
|
||||
document.getElementById('root')
|
||||
);
|
||||
//...
|
||||
```
|
||||
|
||||
## 5. Modify `src/App.js`
|
||||
|
||||
1. Import `firebase/firestore` as well as the `useFirestoreDoc` and `useFirebaseApp` hooks
|
||||
|
||||
```js
|
||||
//...
|
||||
import 'firebase/firestore';
|
||||
import {
|
||||
useFirestoreDoc,
|
||||
useFirebaseApp,
|
||||
SuspenseWithPerf
|
||||
} from 'reactfire';
|
||||
//...
|
||||
```
|
||||
|
||||
1. Add a function component
|
||||
|
||||
```jsx
|
||||
//...
|
||||
function Burrito() {
|
||||
// create a ref
|
||||
const firebaseApp = useFirebaseApp();
|
||||
const burritoRef = firebaseApp
|
||||
.firestore()
|
||||
.collection('tryreactfire')
|
||||
.doc('burrito');
|
||||
|
||||
// subscribe to the doc. just one line!
|
||||
const burritoDoc = useFirestoreDoc(burritoRef);
|
||||
|
||||
// get the value from the doc
|
||||
const isYummy = burritoDoc.data().yummy;
|
||||
|
||||
return <p>The burrito is {isYummy ? 'good' : 'bad'}</p>;
|
||||
}
|
||||
//...
|
||||
```
|
||||
|
||||
1. Render your component inside of a `Suspense` tag
|
||||
|
||||
> We need to do this because `useFirestoreDoc` throws a Promise while it is waiting for a response from Firestore. Suspense will catch the Promise and render `fallback` until the Promise is resolved.
|
||||
|
||||
Replace the `App` function with the following:
|
||||
|
||||
```jsx
|
||||
//...
|
||||
function App() {
|
||||
return (
|
||||
<div className="App">
|
||||
<SuspenseWithPerf
|
||||
fallback={'loading burrito status...'}
|
||||
traceId={'load-burrito-status'}
|
||||
>
|
||||
<Burrito />
|
||||
</SuspenseWithPerf>
|
||||
</div>
|
||||
);
|
||||
}
|
||||
//...
|
||||
```
|
||||
|
||||
## 6. Run your app!
|
||||
|
||||
```bash
|
||||
yarn start
|
||||
# or
|
||||
npm run start
|
||||
```
|
||||
|
||||
1. Edit the value of `yummy` in the Firebase console, and watch it update in real time in your app! 🔥🔥🔥
|
||||
|
||||
## _But what about Firebase Performance Monitoring?_
|
||||
|
||||
By passing the `initPerformance` prop to `FirebaseAppProvider`, our app will automatically measure [common performance stats](https://firebase.google.com/docs/perf-mon/automatic-web), as well as report on our custom trace, `load-burrito-status`, that we set in the `traceId` prop of `SuspenseWithPerf`.
|
||||
|
||||
However, Firebase Performance Monitoring can take about 12 hours to crunch your data and show it in the _Performance_ tab of the Firebase console.
|
||||
|
||||
This is an example of some of the stats in the Firebase Performance Monitoring console after 12 hours:
|
||||
|
||||
|
||||
217
docs/reference.md
Normal file
217
docs/reference.md
Normal file
@@ -0,0 +1,217 @@
|
||||
# Reference Docs
|
||||
|
||||
## Table of Contents
|
||||
|
||||
- [Providers](#Providers)
|
||||
- [`FirebaseAppProvider`](#FirebaseAppProvider)
|
||||
- [Hooks](#Hooks)
|
||||
- [`useFirebaseApp`](#useFirebaseApp)
|
||||
- Authentication
|
||||
- [`useUser`](#useUser)
|
||||
- Database
|
||||
- Cloud Firestore
|
||||
- [`useFirestoreDoc`](#useFirestoreDoc)
|
||||
- [`useFirestoreCollection`](#useFirestoreCollection)
|
||||
- Realtime Database
|
||||
- [`useDatabaseObject`](#useDatabaseObject)
|
||||
- [`useDatabaseList`](#useDatabaseList)
|
||||
- Cloud Storage
|
||||
- [`useStorageTask`](#useStorageTask)
|
||||
- [`useStorageDownloadURL`](#useStorageDownloadURL)
|
||||
- [Components](#Components)
|
||||
- Performance Monitoring
|
||||
- [`SuspenseWithPerf`](#SuspenseWithPerf)
|
||||
- Authentication
|
||||
- [`AuthCheck`](#AuthCheck)
|
||||
- [ReactFireOptions](#ReactFireOptions)
|
||||
|
||||
## Providers
|
||||
|
||||
### `FirebaseAppProvider`
|
||||
|
||||
A React [Context Provider](https://reactjs.org/docs/context.html#contextprovider) that allows the `useFirebaseApp` hook to pick up the `firebase` object.
|
||||
|
||||
#### Sample usage
|
||||
|
||||
```jsx
|
||||
const firebaseConfig = {
|
||||
/* web app config from Firebase console */
|
||||
};
|
||||
|
||||
<FirebaseAppProvider firebaseConfig={firebaseConfig} initPerformance>
|
||||
<App />
|
||||
</FirebaseAppProvider>;
|
||||
```
|
||||
|
||||
#### Props
|
||||
|
||||
| Prop | Type | Description |
|
||||
| --------------- | ------ | ---------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| config | Object | the web app config object usually passed to [`initializeApp`](https://firebase.google.com/docs/reference/js/firebase.html#initializeapp) |
|
||||
| initPerformance | bool | Whether or not to initialize Firebase Performance Monitoring |
|
||||
|
||||
## Hooks
|
||||
|
||||
### `useFirebaseApp`
|
||||
|
||||
When called from a component nested inside a `FirebaseAppProvider`, `useFirebaseApp` returns the root Firebase object.
|
||||
|
||||
> IMPORTANT: By default, `useFirebaseApp` returns a firebase object without any products attached to it (e.g. you can't call `firebase.firestore()`. To do that, you need to `import 'firebase/firestore'` or any other Firebase feature as needed)
|
||||
|
||||
#### Returns
|
||||
|
||||
[`firebase`](https://firebase.google.com/docs/reference/js/firebase)
|
||||
|
||||
### `useUser`
|
||||
|
||||
Get the user that is currently signed in.
|
||||
|
||||
_Throws a Promise by default_
|
||||
|
||||
#### Parameters
|
||||
|
||||
| Parameter | Type | Description |
|
||||
| ----------- | ------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------- |
|
||||
| auth _?_ | [`Auth`](https://firebase.google.com/docs/reference/js/firebase.auth.Auth.html) | [optional] auth object. If not provided, useUser will use `useFirebaseApp` to find the Auth object. |
|
||||
| options _?_ | ReactFireOptions | Options. This hook will not throw a Promise if you provide `startWithValue`. |
|
||||
|
||||
#### Returns
|
||||
|
||||
[`User`](https://firebase.google.com/docs/reference/js/firebase.User)
|
||||
|
||||
### `useFirestoreDoc`
|
||||
|
||||
Listen to a Firestore Document.
|
||||
|
||||
_Throws a Promise by default_
|
||||
|
||||
#### Parameters
|
||||
|
||||
| Parameter | Type | Description |
|
||||
| ----------- | --------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------- |
|
||||
| ref | [`DocumentReference`](https://firebase.google.com/docs/reference/js/firebase.firestore.DocumentReference) | A reference to the document you want to listen to |
|
||||
| options _?_ | ReactFireOptions | Options. This hook will not throw a Promise if you provide `startWithValue`. |
|
||||
|
||||
#### Returns
|
||||
|
||||
[`DocumentSnapshot`](https://firebase.google.com/docs/reference/js/firebase.firestore.DocumentSnapshot)
|
||||
|
||||
### `useFirestoreCollection`
|
||||
|
||||
Listen to a Firestore Collection.
|
||||
|
||||
_Throws a Promise by default_
|
||||
|
||||
#### Parameters
|
||||
|
||||
| Parameter | Type | Description |
|
||||
| ----------- | ------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------- |
|
||||
| ref | [`CollectionReference`](https://firebase.google.com/docs/reference/js/firebase.firestore.CollectionReference) | A reference to the collection you want to listen to |
|
||||
| options _?_ | ReactFireOptions | Options. This hook will not throw a Promise if you provide `startWithValue`. |
|
||||
|
||||
#### Returns
|
||||
|
||||
[`QuerySnapshot`](https://firebase.google.com/docs/reference/js/firebase.firestore.QuerySnapshot)
|
||||
|
||||
### `useDatabaseObject`
|
||||
|
||||
Listen to a Realtime Database Object.
|
||||
|
||||
_Throws a Promise by default_
|
||||
|
||||
#### Parameters
|
||||
|
||||
| Parameter | Type | Description |
|
||||
| ----------- | ---------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------- |
|
||||
| ref | [`Reference`](https://firebase.google.com/docs/reference/js/firebase.database.Reference) | A reference to the object you want to listen to |
|
||||
| options _?_ | ReactFireOptions | Options. This hook will not throw a Promise if you provide `startWithValue`. |
|
||||
|
||||
#### Returns
|
||||
|
||||
[`QueryChange`](https://github.com/firebase/firebase-js-sdk/blob/6b53e0058483c9002d2fe56119f86fc9fb96b56c/packages/rxfire/database/interfaces.ts#L28)
|
||||
|
||||
### `useDatabaseList`
|
||||
|
||||
Listen to a Realtime Database list.
|
||||
|
||||
_Throws a Promise by default_
|
||||
|
||||
#### Parameters
|
||||
|
||||
| Parameter | Type | Description |
|
||||
| ----------- | ---------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------- |
|
||||
| ref | [`Reference`](https://firebase.google.com/docs/reference/js/firebase.database.Reference) | A reference to the list you want to listen to |
|
||||
| options _?_ | ReactFireOptions | Options. This hook will not throw a Promise if you provide `startWithValue`. |
|
||||
|
||||
#### Returns
|
||||
|
||||
[`QueryChange[]`](https://github.com/firebase/firebase-js-sdk/blob/6b53e0058483c9002d2fe56119f86fc9fb96b56c/packages/rxfire/database/interfaces.ts#L28)
|
||||
|
||||
### `useStorageTask`
|
||||
|
||||
Listen to a Storage UploadTask
|
||||
|
||||
_Throws a Promise by default_
|
||||
|
||||
#### Parameters
|
||||
|
||||
| Parameter | Type | Description |
|
||||
| ----------- | ----------------------------------------------------------------------------------------- | ----------- |
|
||||
| task | [`UploadTask`](https://firebase.google.com/docs/reference/js/firebase.storage.UploadTask) | |
|
||||
| ref | [`Reference`](https://firebase.google.com/docs/reference/js/firebase.storage.Reference) | |
|
||||
| options _?_ | ReactFireOptions | |
|
||||
|
||||
#### Returns
|
||||
|
||||
[`UploadTaskSnapshot`](https://firebase.google.com/docs/reference/js/firebase.storage.UploadTaskSnapshot)
|
||||
|
||||
### `useStorageDownloadURL`
|
||||
|
||||
Subscribe to a storage blob's download URL
|
||||
|
||||
_Throws a Promise by default_
|
||||
|
||||
### Parameters
|
||||
|
||||
| Parameter | Type | Description |
|
||||
| ----------- | --------------------------------------------------------------------------------------- | ----------- |
|
||||
| ref | [`Reference`](https://firebase.google.com/docs/reference/js/firebase.storage.Reference) | |
|
||||
| options _?_ | ReactFireOptions | |
|
||||
|
||||
#### Returns
|
||||
|
||||
`string`
|
||||
|
||||
## Components
|
||||
|
||||
### `AuthCheck`
|
||||
|
||||
Renders `children` if a user is signed in and meets the required claims. Renders `fallback` otherwise.
|
||||
|
||||
#### Props
|
||||
|
||||
| Property | Type |
|
||||
| -------------- | --------------- |
|
||||
| auth | Auth |
|
||||
| children | React.Component |
|
||||
| fallback | React.Component |
|
||||
| requiredClaims | Object |
|
||||
|
||||
### `SuspenseWithPerf`
|
||||
|
||||
Starts a Firebase Performance Monitoring [trace](https://firebase.google.com/docs/reference/js/firebase.performance.Trace) and ends it when suspense stops suspending.
|
||||
|
||||
#### Props
|
||||
|
||||
| Property | Type |
|
||||
| ------------ | --------------- |
|
||||
| children | React.Component |
|
||||
| fallback | React.Component |
|
||||
| firePerf _?_ | any |
|
||||
| traceId | string |
|
||||
|
||||
## ReactFireOptions
|
||||
|
||||
| Property | Type |
|
||||
| -------------- | ---- |
|
||||
| startWithValue | any |
|
||||
Reference in New Issue
Block a user