fiery 🔥

fiery 🔥 is the quickest and easiest way to use Firebase Authentication and Firebase Realtime Database in a React app. It uses latest React features and patterns such as render props, hooks, and suspense.

Jump to: Installation · Demo · API Usage · Development · License

Not production-ready: Although I tested it in my projects and small real-world scenarios, they are only small apps and quick prototypes. Contributions are welcome to make this more suitable for production usage.

Installation

You can install fiery 🔥 from npm:

npm install --save fiery

If you’re using Create React App or a module bundler such as webpack or parcel, you can import fiery using the import statement:

import fiery from 'fiery'

If you’re using React with no build tooling, a UMD version is also available (make sure to include react, react-dom, and firebase before including fiery):

<script src="https://unpkg.com/fiery@0.5.0/umd/fiery.js">
</script>

Important: Make sure you are using a version of React that supports the Hooks API.

Demo

Try it out!

View source (32 SLOC)
// Demo: DistributedCounter
// This demo app uses only Functional Components!

// Normal Firebase stuff...
//
const counterRef = firebase.database().ref('demos/counter')
const counterDecrement = () => counterRef.transaction(c => c - 1)
const counterIncrement = () => counterRef.transaction(c => c + 1)

function DistributedCounter() {
  // The `useFirebaseDatabase` hook makes this component automatically
  // subscribe to Firebase Realtime Database. When the data change,
  // this component is automatically re-rendered.
  //
  // This is possible thanks to the Hooks API, introduced in React 16.7.0-alpha.0.
  //
  const counterState = fiery.useFirebaseDatabase(counterRef)
  return (
    <div style={{ display: 'flex', alignItems: 'center' }}>
      <div>
        <UI.Button onClick={counterDecrement}>-</UI.Button>
      </div>
      <div style={{ textAlign: 'center', margin: '0 auto' }}>
        {counterState.loading ? (
          <UI.Loading message="Loading counter value" />
        ) : counterState.failed ? (
          <UI.ErrorMessage
            error={counterState.error}
            retry={counterState.retry}
          />
        ) : (
          <strong>{counterState.data}</strong>
        )}
      </div>
      <div>
        <UI.Button onClick={counterIncrement}>+</UI.Button>
      </div>
    </div>
  )
}

ReactDOM.render(
  <DistributedCounter />,
  document.getElementById('DistributedCounter')
)
View source (97 SLOC)
// Demo: GuestbookApp
// This demo app uses only Functional Components!
function GuestbookApp() {
  return (
    <section>
      <Nav />
      <GuestbookList />
      <GuestbookForm />
    </section>
  )
}

/**
 * The navigation bar
 */
function Nav() {
  return (
    <UI.NavBar title="My Guestbook">
      <UI.NavBar.Item label="Contact" />
      {/* Subscribe to the authentication state.
          NOTE: We use the Render Props technique here to localize updates
          to a single <UI.NavBar.Item /> component without requiring a new
          React component. */}
      <fiery.Auth>
        {/* `authState` contains `loading`, `failed`, and `data` properties. */}
        {authState =>
          authState.loading ? (
            <UI.NavBar.Item label="Checking auth…" disabled />
          ) : authState.failed ? (
            <UI.NavBar.Item
              label="Auth checking failed"
              title={String(authState.error) + ' (click to retry)'}
              onClick={authState.retry}
            />
          ) : authState.data ? (
            <UI.NavBar.Item
              label={'Sign Out (' + authState.data.displayName + ')'}
              onClick={signOut}
            />
          ) : (
            <UI.NavBar.Item label="Sign in with GitHub" onClick={signIn} />
          )
        }
      </fiery.Auth>
    </UI.NavBar>
  )
}

// The `signIn` and `signOut` functions uses the normal Firebase auth functions.
// No new APIs to learn here!
//
function signIn() {
  firebase
    .auth()
    .signInWithPopup(new firebase.auth.GithubAuthProvider())
    .catch(e => window.alert(`Sorry, cannot sign in! ${e}`))
}
function signOut() {
  if (window.confirm('RLY SIGN OUT?')) firebase.auth().signOut()
}

/**
 * The list of guestbook entries.
 */
function GuestbookList() {
  // The `useFirebaseDatabase` hook makes this component automatically
  // subscribe to Firebase Realtime Database. When the data change,
  // this component is automatically re-rendered.
  //
  const guestbookState = fiery.useFirebaseDatabase(
    firebase
      .database()
      .ref('demos/guestbook')
      .orderByChild('time')
      .limitToLast(8)
  )
  return (
    <UI.EntryList>
      {guestbookState.loading ? (
        <UI.Loading message="Loading messages…" />
      ) : guestbookState.failed ? (
        <UI.ErrorMessage
          error={guestbookState.error}
          retry={guestbookState.retry}
        />
      ) : (
        Object.keys(guestbookState.data).map(key => (
          <UI.EntryList.Item
            key={key}
            text={guestbookState.data[key].text}
            name={guestbookState.data[key].name}
          />
        ))
      )}
    </UI.EntryList>
  )
}

/**
 * The form to submit a guestbook entry.
 */
function GuestbookForm() {
  // The `useFirebaseAuth` hook makes this component automatically
  // subscribe to Firebase Authentication state. When user signs in
  // or signs out, this component will automatically update.
  //
  const userState = fiery.useFirebaseAuth()
  return userState.loading ? (
    <UI.Loading message="Checking authentication status…" />
  ) : userState.failed ? (
    <UI.ErrorMessage error={userState.error} retry={userState.retry} />
  ) : userState.data ? (
    <UI.EntryForm onSend={text => submitForm(text, userState.data)} />
  ) : (
    <UI.AuthenticationWall onSignIn={signIn} />
  )
}

// Write to Firebase Realtime Database using the familiar Firebase SDK!
//
function submitForm(text, user) {
  return firebase
    .database()
    .ref('demos/guestbook')
    .push({
      time: firebase.database.ServerValue.TIMESTAMP,
      name: user.displayName,
      text: text
    })
}

// Render the app...
//
ReactDOM.render(<GuestbookApp />, document.getElementById('GuestbookApp'))
View source (35 SLOC)
// Demo: SuspenseDemo
// In this demo, there are no checks for Loading/Error state.
// Loading state is handled by React.Suspense.
// Error state is handled by using an Error Boundary.
// WARNING: Unstable API!

function SuspenseDemo() {
  return (
    // Set up an Error Boundary to catch errors.
    <UI.ErrorBoundary>
      <SectionSelector />
    </UI.ErrorBoundary>
  )
}

function SectionSelector() {
  // `error` — always results in an error.
  // `protected` — only logged in users can see. If you log out, you will get en error.
  // `even` — only accessible when the Counter (1st demo) contains an even number.
  const sections = ['intro', 'bridge', 'chorus', 'error', 'protected', 'even']
  const [currentSection, setCurrentSection] = React.useState('intro')
  return (
    <section>
      <UI.Tabs
        tabs={sections}
        currentTab={currentSection}
        onTabChange={tab => setCurrentSection(tab)}
      />
      <UI.ContentBox>
        {/* Use `React.Suspense` to display a loading UI
            if any child component is not ready to render */}
        <React.Suspense fallback={<UI.Loading />}>
          <SectionContent sectionName={currentSection} />
        </React.Suspense>
      </UI.ContentBox>
    </section>
  )
}

function SectionContent({ sectionName }) {
  const dataRef = firebase.database().ref(`demos/tabs/${sectionName}`)
  const dataState = fiery.useFirebaseDatabase(dataRef)

  return (
    <div>
      {/* Use `.unstable_read()` to read the data out of Firebase.
          Suspends rendering if data is not ready. */}
      <strong>{sectionName}:</strong> {dataState.unstable_read()}
    </div>
  )
}

ReactDOM.render(<SuspenseDemo />, document.getElementById('SuspenseDemo'))

API Usage

fiery 🔥 provides both hooks-based and render props-based APIs (rationale). These APIs will inject DataState objects into your component.

A DataState object will contain loading, failed, data, error, and retry properties. It also contains an experimental method unstable_read() to make React suspend rendering until the data is loaded.

Synopsis

fiery.useFirebaseAuth()

Subscribe and use authentication state.

fiery.Auth

Render prop version of fiery.useFirebaseAuth.

Takes a single prop:

fiery.useFirebaseDatabase(dataRef: firebase.database.Query)

Subscribe and use data from Firebase Realtime Database.

fiery.Data

Render prop version of fiery.useFirebaseDatabase.

Takes two props:

fiery.DataState<T> — Representing remote data.

When displaying data from remote sources, the data may not be immediately available — it may still be loading, or may have failed to load.

fiery 🔥 represents this by providing you a DataState<T> object, which is a plain JS object with these properties:

If you use TypeScript, our typings file can help preventing you from accessing the data in loading or failed state. Refer to this table.

loading failed data error retry Remarks
true false T | undefined undefined undefined Initial load
true true T | undefined Error undefined Retrying
false false T undefined undefined Completed
false true T | undefined Error () => void Error

Suspense support: A DataState object also contains an experimental method, unstable_read() for reading the data while rendering. It suspends rendering if data from Firebase is not ready. Note that this uses an unstable API and is subject to change.

Looking for Firebase Firestore bindings?

Please contribute!

Development

This project uses Yarn.

Dependencies

To install dependencies, run:

yarn

Development

Run:

yarn dev

This will run Rollup in watch mode and generate umd/fiery.js. It will also re-generate the documentation site on change.

Building

To build the library once, run:

yarn build

This will generate umd/fiery.js.

Docs

The documentation website is generated from README.md.

To generate the docs, run:

yarn docs

License

MIT.