@zachsents/fire-query

fire-query

A set of hooks to facilitate seamless integration between Firebase (specifically Firestore) and React Query.

Installation

npm install fire-query

Features

• Fetch and subscribe to Firestore documents using React Query.
• Use mutation hooks to set, update, and delete Firestore documents.
• Optimized performance with memoized references and query keys.
• Allows for undefined arguments to minimize wrapping in conditional components.
• JSDoc types.

Usage

Setup

Make sure you have initialized Firebase and React Query in your app.

Then, provide the Firebase context (assumed to be available from ./context.js) and set any default document options in your Firebase context.

Fetching and Subscribing to a Firestore Document

import { useDocument } from 'fire-query';

function MyComponent() {
  const { data, isLoading } = useDocument(['myCollection', 'myDocId'], { fetch: true, subscribe: true });

  if (isLoading) return 'Loading...';
  if (!data) return 'No document found';

  return <div>{data.myField}</div>;
}

Using Mutations on a Firestore Document

import { useDocumentMutators } from 'fire-query';

function MyComponent() {
  const { update, set, delete: deleteDoc } = useDocumentMutators(['myCollection', 'myDocId']);

  const handleUpdate = () => {
    update.mutate({ myField: 'newValue' });
  }

  return (
    <>
      <button onClick={handleUpdate}>Update Document</button>
      {/* Similarly use `set.mutate()` and `deleteDoc.mutate()` */}
    </>
  );
}

API Reference

useDocumentReference(pathSegments: string[])

A hook to get a Firestore DocumentReference based on the provided path segments.

useDocument(referenceOrPathSegments: DocumentReference | string[], documentOptions?: UseDocumentOptions, reactQueryOptions?: UseQueryOptions)

The main hook to fetch and/or subscribe to a Firestore document. You can either pass a DocumentReference or an array of path segments.

This hook also provides set, update, and delete mutations based on the includeMutators option.

useDocumentFromPath(pathSegments: string[], documentOptions?: UseDocumentOptions, reactQueryOptions?: UseQueryOptions)

A variant of the useDocument hook that only takes an array of path segments.

useDocumentFromReference(reference: DocumentReference, documentOptions?: UseDocumentOptions, reactQueryOptions?: UseQueryOptions)

A variant of the useDocument hook that only takes a DocumentReference.

useDocumentMutators(referenceOrPathSegments: DocumentReference | string[])

A hook that provides only the set, update, and delete mutations without fetching or subscribing to the document.

Options

• fetch: Fetch the document when the component mounts.
• subscribe: Listen for real-time updates to the document. Only works if fetch is true.
• raw: Return the raw Firestore DocumentSnapshot instead of formatted data.
• includeMutators: Include the mutation methods (set, update, delete).

Note

Ensure that your Firebase rules are correctly set to permit the desired read/write operations.

Contributions

Feel free to submit issues and pull requests if you find bugs or have suggestions for improvements.

License

MIT

---

For detailed documentation and more examples, please visit official documentation.