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/[email protected]/umd/fiery.js">
</script>

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

Demo

Try it out!

// 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')
)

// 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'))

// 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

• Using Hooks

  function HookSynopsis() {
    const counterState = fiery.useFirebaseDatabase(counterRef)
  
    if (counterState.loading) {
      return <UI.Loading />
    } else if (counterState.failed) {
      return (
        <UI.ErrorMessage
          error={counterState.error}
          retry={counterState.retry}
        />
      )
    } else {
      return counterState.data
    }
  }

• Suspense + Hooks

  function SuspenseHookSynopsis() {
    const counterState = fiery.useFirebaseDatabase(counterRef)
  
    return counterState.unstable_read()
  }

• Using Render Props

  function RenderPropsSynopsis() {
    return (
      <fiery.Data dataRef={counterRef}>
        {counterState =>
          counterState.loading ? (
            <UI.Loading />
          ) : counterState.failed ? (
            <UI.ErrorMessage
              error={counterState.error}
              retry={counterState.retry}
            />
          ) : (
            counterState.data
          )
        }
      </fiery.Data>
    )
  }

• Suspense + Render Props

  function SuspenseRenderPropsSynopsis() {
    return (
      <fiery.Data dataRef={counterRef}>
        {counterState => counterState.unstable_read()}
      </fiery.Data>
    )
  }

fiery.useFirebaseAuth()

Subscribe and use authentication state.

• Returns a fiery.DataState<firebase.User | null> wrapping a firebase.User object (if signed in) or null (if signed out).

fiery.Auth

Render prop version of fiery.useFirebaseAuth.

Takes a single prop:

• children — A function that determines how the authentication state should be rendered. It will be called with a RemoteDataState wrapping a firebase.User object (if signed in) or null (if signed out).

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

Subscribe and use data from Firebase Realtime Database.

• dataRef — A firebase.database.Reference representing the data reference to fetch.
• Returns a fiery.DataState<any> wrapping the data (if it exists) or null otherwise.

fiery.Data

Render prop version of fiery.useFirebaseDatabase.

Takes two props:

• dataRef — A firebase.database.Reference representing the data reference to fetch.
• children — A function that determines how the data state should be rendered. It will be called with a fiery.DataState<any> wrapping the data (if it exists) or null otherwise.

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:

• loading — A boolean representing whether data is being actively loaded or not.
• failed — A boolean representing whether data failed to load or not. Note: When retrying, the failed flag will stay true until new data has been loaded successfully.
• data — The data of type T. May be undefined if loading || failed.
• error — The Error. May be undefined if !failed.
• retry — A function that may be called to retry the operation. May be undefined if !failed || loading.

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
true	true	`T	undefined`	Error	undefined
false	false	T	undefined	undefined	Completed
false	true	`T	undefined`	Error	() => void

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.