Fiery NPM | npm.io

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!

// 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}
        currentSection={currentSection}
        onTabChange={tab => setCurrentSection(tab)}
      />
      <UI.ContentBox>
        {/* Use `React.Suspense` to display a loading UI
            if any children 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}`)
  // Use `.unstable_read()` to read the data out of Firebase.
  // Suspends rendering if data is not ready.
  const text = fiery.useFirebaseDatabase(dataRef).unstable_read()
  return (
    <div>
      <strong>{sectionName}:</strong> {text}
    </div>
  )
}

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

API Usage

fiery 🔥 provides both hooks-based and render props-based APIs (rationale).

The state object will contain loading, failed, data, error, and retry properties. Or you can invoke an experimental method unstable_read() to make React suspend rendering until it 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
  }
}

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 + Hooks

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

Suspense + Render Props

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

`fiery.DataState<T>` — Representing remote data.

When loading data from remote sources, the data may not come immediately. In fiery, to represent this, we use a DataState<T>, 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`	Initial load
`true`	`true`	`T \| undefined`	`Error`	`undefined`	Retrying
`false`	`false`	`T`	`undefined`	`undefined`	Completed
`false`	`true`	`T \| undefined`	`Error`	`() => void`	Error

`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.
- It also contains an unstable method, unstable_read() for reading data synchronously. It suspends rendering if data from Firebase is not ready. Note that this uses an unstable API and is subject to change.

`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.