fire-connect v1.0.1
Fire Connect
React bindings for Firebase and Firestore.
Fire Connect aims to be a transparent, flexible set of higher order components to help separate Firebase-related concerns from the rest of the application. It uses the standard Firebase and Firestore syntax, removing the need to learn a new custom syntax and allowing users to follow along with Google's documentation.
Installation
npm i fire-connect
React Firebase requires React 16.3 and Firebase 3 or later.
Usage
firestoreConnect(addListeners, addDispatchers)
Connects a React component to Firestore and Auth.
When invoked, wraps the passed in component in a connector component and gives the passed in component access to the connector's props, state, and context through props.
Example
const MyComponent = ({ task, isLoaded, newTask }) => (
/* some JSX */
)
// single listener
const addListeners = (connector, firestore) => (
firestore.collection('tasks').doc('taskId').onSnapshot(doc => {
connector.setState({ task: doc.data(), isLoaded: true })
})
)
const addDispatchers = (connector, firestore, user) = ({
newTask(task) {
firestore.collection('tasks').add({ ...task, authorId: user.uid })
},
deleteTask(taskId) {
firestore.collection('tasks').doc(taskId).delete()
}
})
export default firestoreConnect(addListeners, addDispatchers)(MyComponent)
// multiple listeners
const addListeners = (connector, firestore) => ({
taskA: () => firestore.collection('tasks').doc('taskA').onSnapshot(doc => {
connector.setState({ taskA: doc.data() })
}),
taskB: () => firestore.collection('tasks').doc('taskB').onSnapshot(doc => {
connector.setState({ taskB: doc.data() })
}),
})
Arguments
addListeners(connector, firestore, user)
Returns either a single listener or an object in which the value of each key is a nullary function that itself returns a listener.addDispatchers(connector, firestore, user)
Returns an object containing functions that send updates to Firestore, these functions are passed to the wrapped component as props.connector
Thethis
reference for the connector component. Can be used to access the connector's props (which includes everything passed to the provider) and callsetState
, among other thingsfirestore
The Firestore instance passed to the provider (firebase.firestore()
)user
Iffirebase.auth()
was passed to the provider, it is the user object ornull
. Else, it isundefined
Returns
A React component class that can be invoked with a component and will pass dispatchers, its state, its props, and its context as props to that component.
firebaseConnect(addListeners, addDispatchers)
Connects a React component to Firebase and Auth.
When invoked, wraps the passed in component in a connector component and gives the passed in component access to the connector's props, state, and context through props.
Example
const MyComponent = ({ task, isLoaded, newTask }) => (
/* some JSX */
)
// single listener
const addListeners = (connector, ref) => (
ref('tasks').onSnapshot('value', snapshot => {
connector.setState({ task: snapshot.data(), isLoaded: true })
})
)
const addDispatchers = (connector, ref, user) = ({
newTask(task) {
ref('tasks').push().set({ ...task, authorId: user.uid })
},
deleteTask(taskId) {
ref(`tasks/${taskId}`).remove()
}
})
export default firebaseConnect(addListeners, addDispatchers)(MyComponent)
// multiple listeners
const addListeners = (connector, ref, user, setEventType) => ({
taskA: () => ref('tasks/taskA').on(setEventType('value'), snapshot => {
connector.setState({ taskA: snapshot.data() })
}),
taskB: () => ref('tasks/taskB').on('child_added', snapshot => {
connector.setState({ taskA: snapshot.data() })
}),
})
Arguments
addListeners(connector, ref, user, setEventType)
Returns either a single listener or an object in which the value of each key is a function that takes no arguments and itself returns a listener.Note:
ref().child()
is not currently supported. Use string concatenation inside ofref
instead.addDispatchers(connector, ref, user)
Returns an object containing functions that send updates to Firebase, these functions are passed to the wrapped component as props.
connector
Thethis
reference for the connector component. Can be used to access the connector's props (which includes everything passed to the provider) and callsetState
, among other thingsref
An internal function that returns the result of callingfirebase.database().ref
and stores the path passed in for unsubscribing when the component unmounts.user
Iffirebase.auth()
was passed to the provider, it is the user object ornull
. Else, it isundefined
setEventType
By default, firebaseConnect will call.off()
with no arguments, removing all listeners at the locationref
was called with. If this behavior causes problems, the first argument to.on
(eventType) can be replaced withsetEventType
invoked with a Firebase eventType. (See multiple listeners example above)
Returns
A React component class that can be invoked with a component and will pass dispatchers, its state, its props, and its context as props to that component.
authConnect(addDispatchers)
Connects a React component to Auth.
When invoked, wraps the passed in component in a connector component and gives the passed in component access to the connector's props and context through props.
Auth can also be accessed in firebaseConnect and firestoreConnect through connector.props.auth
.
Example
const MyComponent = ({ login, logout }) => (
/* some JSX */
)
const addHostDispatchers = (connector, auth) => ({
login() {
auth.signInWithPopup(googleProvider)
},
logout() {
auth.signOut()
},
})
export default authConnect(addListeners, addDispatchers)(MyComponent)
Arguments
addDispatchers(connector, auth, user)
Returns an object containing functions that invoke Auth methods, these functions are passed to the wrapped component as props.connector
Thethis
reference for the connector component. Can be used to access the connector's props (which includes everything passed to the provider) and callsetState
, among other thingsauth
The Auth instance passed to the provider (firebase.auth()
)user
Iffirebase.auth()
was passed to the provider, it is the user object ornull
. Else, it isundefined
Returns
A React component class that can be invoked with a component and will pass dispatchers, its props, and its context as props to that component.
<Provider auth database firestore (anyOtherProps)>
The <Provider>
component wraps the application and uses the context API to pass auth, database, and Firestore references to connected components, as well as any other data the connected components should have. If passed an auth prop, it will initialize an auth listener and pass connected components the resulting user object.
Props
auth
firebase.auth()
database
firebase.database()
firestore
firebase.firestore()
children
: The root of the component hierarchy.onIdTokenChanged
Boolean prop that toggles whether the auth listener isonIdTokenChanged
or the defaultonAuthStateChanged
.- Any other props passed to
<Provider>
will be put in its context and accessible to connected components.
Example
render(
<Provider
auth={firebase.auth()}
database={firebase.database()}
firestore={firebase.firestore()}
firebaseTimestamp={firebase.database.ServerValue.TIMESTAMP}
>
<App />
</Provider>,
document.getElementById('app')
)
FAQ
Can I access Firestore in firebaseConnect or firebase in firestoreConnect?
Yes! The Firebase reference can be found at connector.props.database
and the Firestore reference can be found at connector.props.firestore
. You can use the Firebase once
method or Firestore get
method to fetch data and use any methods to add, update, or delete data. However, setting up listeners is not recommended as they will not be automatically unsubscribed when the component unmounts.
Can I save a Firebase ref or Firestore docRef to a variable so I don't have to keep retypeing a long path?
Yes! One way to do it is to set a property of the wrapper component in either addListeners
or addDispatchers
. Something like connector.myRef = ref('some/really/long/path')
. If you're using a property in both addListeners
and addDispatchers
, it's better to declare it in addDispatchers
as addDispatchers
is invoked in the constructor and addListeners
is invoked in componentDidMount
.
License
MIT