human-contexts-firebase
Built by Human.
Note: This project has been deprecated in favor of human-hooks-firebase
and human-hooks-firebase-native
. Check out those projects if you haven't already.
A set of simple helpers for accessing Firebase Firestore data in realtime using React Contexts.
This is a pattern we use frequently for quickly building prototypes, new features, and database connections at Human. It's great for prototyping and it doesn't introduce a lot of complicated boilerplate code.
Creating a secure realtime connection with Firestore is simple.
// in /src/contexts/orders.ts
import { authedCollection } from '@humancollective/human-contexts-firebase'
import { Order } from '../types'
export const [OrdersContext, OrdersProvider] = authedCollection<Order>({
getQueryRef: (firebase, uid) =>
firebase
.firestore()
.collection('orders')
.where('customerId', '==', uid),
})
With just a few of lines of code, we've created a new context with a Firestore listener. That listener will return an empty array unless the user is logged in. If they're logged in, it will return all of the orders they own (note - this depends on your data model and security rules).
We now simply wrap the contents of the application that require access to our orders with the <OrdersProvider />
and we'll be able to access the user's orders anywhere within it.
Here, for example, we can access the list of orders in the Account Page:
// in /src/pages/account.tsx
import React from 'react'
import { OrdersContext } from '../contexts/orders'
export const AccountPage = () => {
const orders = React.createContext(OrdersContext)
return (
<div>
<h1>My Account</h1>
{orders.map(({ reference, price }) => (
<div key={reference}>
{reference} - {price}
</div>
))}
</div>
)
}
Usage
Installation
Install this library and firebase.
yarn add firebase @humancollective/human-contexts-firebase
Wrap your application in the <FirebaseProvider />
and give it your firebase app configuration. You can nest this deeper in your application as long as it wraps all of the human-contexts-firebase
providers.
import React from 'react'
import firebase from 'firebase/app'
import { FirebaseProvider } from '@humancollective/human-contexts-firebase'
const MyApplication = ({ children }) => (
<FirebaseProvider
firebase={firebase}
configuration={
{
// The credentials you use to access firebase
// apiKey: "YOUR_API_KEY",
// authDomain: "YOUR_AUTH_DOMAIN",
// databaseURL: "YOUR_DATABASE_URL",
// ...
}
}
>
{children}
</FirebaseProvider>
)
Creating a Context
To create an authenticated collection context, we import the authedCollection
helper.
import { authedCollection } from '@humancollective/human-contexts-firebase'
Now we can create a context and a provider for a collection. Let's create one for a series of posts that require an authenticated user.
// /src/contexts/posts.ts
import { authedCollection } from '@humancollective/human-contexts-firebase'
import { Post } from '../types'
export const [PostsContext, PostsProvider] = authedCollection<Post>({
getQueryRef: (firebase, uid) => firebase.firestore().collection('posts'),
})
Now let's wrap our application in the posts provider.
import React from 'react'
import firebase from 'firebase/app'
import { FirebaseProvider } from '@humancollective/human-contexts-firebase'
// import the provider
import { PostsProvider } from '../contexts/posts'
const MyApplication = ({ children }) => (
<FirebaseProvider firebase={firebase} configuration={YOUR_FIREBASE_CONFIG}>
{/* ... and wrap the application with it */}
<PostsProvider>{children}</PostsProvider>
</FirebaseProvider>
)
Finally, we can access our posts anywhere nested under our layout:
// in /src/pages/account.tsx
import React from 'react'
import { PostsContext } from '../contexts/posts'
export const AccountPage = () => {
const posts = React.createContext(PostsContext)
return (
<div>
<h1>Secret Posts</h1>
{posts.map(({ name, excerpt, link }) => (
<div key={link}>
<a href={link}>{name}</a>
<p>{excerpt}</p>
</div>
))}
</div>
)
}
Include IDs
We can include the Firebase IDs in the collection response by setting the includeIds
flag to true when we create the collection context.
Default Values
Default values can be specified using the defaultValue
option when creating the collection context.