react-stateful-firestore v0.5.3

React Stateful Firestore

Provides bindings for authentication, Firestore, messaging, and storage data in React. Caches Firestore and authentication with Redux to prevent lag on data that has already been queried. Updates in real-time by default.

Key Goals

• No new query language: uses Firestore queries, collections, etc.
• Minimal setup
• Speed
• Stateful cache with real-time updating
• Secure

Quick Start

npm install react-stateful-firestore
# or
yarn add react-stateful-firestore

Set up Firebase

Install the Firebase dependencies:

yarn add @firebase/app \
  @firebase/auth \
  @firebase/firestore \
  @firebase/messaging \
  @firebase/storage
# or
npm install --save @firebase/app \
  @firebase/auth \
  @firebase/firestore \
  @firebase/messaging \
  @firebase/storage

Note: We install these packages independently instead of firebase to substantially reduce your final bundle size. You can still use firebase if you want, but it's not recommended.

Next, initialize your Firebase app.

import app from '@firebase/app';

const myApp = app.initializeApp({
  apiKey: '<API_KEY>',
  authDomain: '<DOMAIN>',
  databaseURL: '<DB_URL>',
  projectId: '<PROJECT_ID>',
  storageBucket: '<STORAGE_BUCKET>',
  messagingSenderId: '<MESSAGE_ID>'
});

Provide the store

Once your firebase application is initialized, create the React-Stateful-Firestore instance and render it in the Provider component.

import initReactFirestore, { Provider } from 'react-stateful-firestore';

initReactFirestore(myApp).then((store) => {
  ReactDOM.render(
    <Provider store={store}>
      <App />
    </Provider>,
    document.getElementById('#root')
  );
});

API

Default Export: initReactFirestore Other Exports:

• connect
• connectAuth
• FetchStatus
  • resolveFetchStatus
  • resolveInitialFetchStatus
• Provider
• Types

import initReactFirestore, {
  connect,
  connectAuth,
  FetchStatus,
  Provider,
  resolveFetchStatus,
  resolveInitialFetchStatus
} from 'react-stateful-firestore';

initReactFirestore(app, userCollection?)

This method initializes the backing store and authentication handling for your firebase/firestore application.

Example:

import initReactFirestore, { Provider } from 'react-stateful-firestore';

initReactFirestore(app).then((store) => {
  ReactDOM.render(
    <Provider store={store}>
      <App />
    </Provider>,
    document.getElementById('#root')
  );
});

<Provider store={store}>

This component is necessary to use connect and connectAuth within your application. It provides your Firebase app's instance and special data selectors used internally. It must be provided the store prop, as returned in the promise from initReactFirestore.

connect(getSelectors)

This is a higher order component creator function used to connect your components to data from your Firestore. It accepts a single argument, getSelectors.

Aside from your defined props in getSelectors, connect will also provide the following props to your component:

Example:

import { connect } from 'react-stateful-firestore';

class Article extends Component {
  static propTypes = {
    article: shape({
      error: any,
      fetchStatus: oneOf(['none', 'loading', 'loaded', 'failed']).isRequired, // $Values<typeof FetchStatus>
      doc: object // NOTE: `select(firestore.doc(...))` will provide `doc` (singular)
    }).isRequired,
    articleId: string.isRequired,
    comments: shape({
      error: any,
      fetchStatus: oneOf(['none', 'loading', 'loaded', 'failed']).isRequired, // $Values<typeof FetchStatus>
      docs: arrayOf(object) // NOTE: `select(firestore.collection(...))` will provide `docs` (plural)
    }).isRequired,
    promoImage: shape({
      error: any,
      fetchStatus: oneOf(['none', 'loading', 'loaded', 'failed']).isRequired, // $Values<typeof FetchStatus>,
      downloadUrl: string
    }),
    // Automatically provided by `connect()`
    auth: object.isRequired,
    firestore: object.isRequired,
    messaging: object.isRequired,
    storage: object.isRequired
  };

  render() { ... }
}

export default connect((select, { firestore, storage }, props) => ({
  article: select(firestore.doc(`articles/${props.articleId}`)),
  comments: select(firestore.collection('comments').where('articleId', '==', props.articleId)),
  promoImage: select(storage.ref('promoimage.jpg'))
}))(Article);

// render(<ConnectedArticle articleId="123" />);

getSelectors(select, apis, props)

A function that returns a map of props to data selectors supplied to your final rendered component.

Select

SelectApis

SelectOptions

connectAuth(handleAuthState)

This is a higher order component creator function used to connect your components to authentication state from your Firestore. It accepts a single argument, handleAuthState.

connectAuth can be used as a gating function to require an authentication status to determine what should be rendered and how to handle authentication state changes.

import { connectAuth } from 'react-stateful-firestore';

class LoginPage extends Component {
  static propTypes = {
    authUserDoc: object,
    authFetchStatus: oneOf(['none', 'loading', 'loaded', 'failed']).isRequired,
    // Also provided by `connectAuth()`
    auth: object.isRequired, // Use this to access the auth user, `auth.currentUser`
    firestore: object.isRequired,
    messaging: object.isRequired,
    storage: object.isRequired
  };

  render() { ... }
}

class Loading extends Component {
  render() {
    return 'Loading…';
  }
}

export default connectAuth(({ action, doc, fetchStatus }, auth, props) => {
  if (action === 'signin') {
    // If the user becomes signed in, push them to the home page.
    props.history.push('/');
  }
}, Loading)(LoginPage);

// render(<ConnectedLoginPage history={history} />);

handleAuthState(state, auth, props)

A custom function that you create, passed to connectAuth to handle the state of authentication within your React application.

AuthState

FetchStatus

A string representing the status of the query for a document. One of the following:

resolveFetchStatus(...items)

Returns a single FetchStatus value given the state of multiple Collections or Documents. This method requires that all items are loaded before returning FetchStatus.LOADED.

resolveInitialFetchStatus(...items)

Returns a single FetchStatus value given the initial state of multiple Collections or Documents. This method will return FetchStatus.LOADED if any item is loaded.

Types

React Stateful Firestore also exposes a few flow types.

$FetchStatus

A FetchStatus value.

Document

Creates a type for documents provided as props on your connected components.

type MyDocument = Document<{ name: string }>

const doc: MyDocument;
console.log(doc.fetchStatus); // -> A $FetchStatus
console.log(doc.id); // -> The Firestore document id
console.log(doc.doc); // -> The data in the document on Firestore

Collection

Creates a type for collections provided as props on your connected components

type MyCollection = Collection<{ name: string }>

const collection: MyCollection;
console.log(collection.fetchStatus); // -> A $FetchStatus
console.log(collection.docs); // -> Array of Documents