@tatsuokaniwa/swr-firestore NPM

swr-firestore

React Hooks library for Firestore, built using the Firebase v9 modular SDK. It utilizes the useSWRSubscription function from SWR library to enable subscription-based data fetching and caching.

Inspired by swr-firestore-v9

Installation

# if you use NPM
npm i --save @tatsuokaniwa/swr-firestore
# if you use Yarn
yarn add @tatsuokaniwa/swr-firestore
# if you use pnpm
pnpm i @tatsuokaniwa/swr-firestore

Usage

import { useCollection, useCollectionCount } from "@tatsuokaniwa/swr-firestore";
import { initializeApp } from "firebase/app";
import { getFirestore } from "firebase/firestore";

initializeApp();
const db = getFirestore();

type Post = {
  content: string;
  status: "draft" | "published";
  createdAt: Date;
};
export default function App() {
  // Conditional Fetching
  const [isLogin, setIsLogin] = useState(false);
  const { data } = useCollection<Post>(
    isLogin
      ? {
          path: "posts",
          where: [["status", "==", "published"]],
          orderBy: [["createdAt", "desc"]],
          parseDates: ["createdAt"],
        }
      : null
  );
  const { data: postCount } = useCollectionCount<Post>({
    path: "posts",
    where: [["status", "==", "published"]],
  });
  return (
    <div>
      <h1>{postCount} posts</h1>
      {data?.map((x, i) => (
        <div key={i}>
          {x.content} {x.createdAt.toLocaleString()}
        </div>
      ))}
      <button onClick={() => setIsLogin(!isLogin)}>Toggle auth</button>
    </div>
  );
}

For more complex queries

To perform complex queries like using OR queries or raw QueryConstraint, use the queryConstraints parameter. However, this method does not provide input completion for field names from type definitions.

import { or, orderBy, where } from "firebase/firestore";

useCollection<City>({
  path: "cities",
  queryConstraints: [
    or(where("capital", "==", true), where("population", ">=", 1000000)),
    orderBy("createdAt", "desc"),
  ],
});

SSG and SSR

You can use the server module to get the SWR key and data.

import { useCollection, useGetDocs } from "@tatsuokaniwa/swr-firestore"
import { getCollection } from "@tatsuokaniwa/swr-firestore/server"

export async function getStaticProps() {
  const params = {
    path: "posts",
    where: [["status", "==", "published"]],
  }
  const { key, data } = await getCollection<Post>({
    ...params,
    isSubscription: true, // Add the prefix `$sub$` to the SWR key
  })
  const { key: useGetDocsKey, data: useGetDocsData } = await getCollection<Post>(params)
  return {
    props: {
      fallback: {
        [key]: data,
        [useGetDocsKey]: useGetDocsData,
      }
    }
  }
}

export default function Page({ fallback }) {
  const { data } = useCollection<Post>({
    path: "posts",
    where: [["status", "==", "published"]],
  })
  const { data: useGetDocsData } = useGetDocs<Post>({
    path: "posts",
    where: [["status", "==", "published"]],
  })
  return (
    <SWRConfig value={{ fallback }}>
      {data?.map((x, i) => <div key={i}>{x.content}}</div>)}
    </SWRConfig>
  )
}

API

import {
  useCollection, // Subscription for collection
  useCollectionCount, // Wrapper for getCountFromServer for collection
  useCollectionGroup, // Subscription for collectionGroup
  useCollectionGroupCount, // Wrapper for getCountFromServer for collectionGroup
  useDoc, // Subscription for document
  useGetDocs, // Fetch documents with firestore's getDocs
  useGetDoc, // Fetch document with firestore's getDoc
} from "@tatsuokaniwa/swr-firestore";

import {
  getCollection, // Get the SWR key and data for useCollection, useGetDocs
  getCollectionCount, // for useCollectionCount
  getCollectionGroup, // for useCollectionGroup, useGetDocs
  getCollectionGroupCount, // for useCollectionGroupCount
  getDoc, // for useDoc, useGetDoc
} from "@tatsuokaniwa/swr-firestore/server";

Type definitions for parameters

import type {
  endAt,
  endBefore,
  limit,
  orderBy,
  startAfter,
  startAt,
  where,
} from "firebase/firestore";

type DocumentId = "id";
// First argument of hook, specifies options to firestore, and is also used as a key for SWR.
type KeyParams<T> =
  | {
      // The path to the collection or document of Firestore.
      path: string;
      // `Paths` means object's property path, including nested object
      where?: [
        Paths<T> | DocumentId, // "id" is internally converted to documentId()
        Parameters<typeof where>[1],
        ValueOf<T> | unknown
      ][];
      orderBy?: [Paths<T> | DocumentId, Parameters<typeof orderBy>[1]][];
      startAt?: Parameters<typeof startAt>;
      startAfter?: Parameters<typeof startAfter>;
      endAt?: Parameters<typeof endAt>;
      endBefore?: Parameters<typeof endBefore>;
      limit?: number;
      limitToLast?: number;
      // Array of field names that should be parsed as dates.
      parseDates?: Paths<T>[];
    }
  // OR for more complex query
  | {
      // The path to the collection or document of Firestore.
      path: string;
      // raw query constraints from `firebase/firestore`
      queryConstraints?:
        | [QueryCompositeFilterConstraint, ...Array<QueryNonFilterConstraint>]
        | QueryConstraint[];
      // Array of field names that should be parsed as dates.
      parseDates?: Paths<T>[];
    };

Type definitions for return data

import type { QueryDocumentSnapshot } from "firebase/firestore";

type DocumentData<T> = T & Pick<QueryDocumentSnapshot, "exists" | "id" | "ref">;

`useCollection(params, swrOptions)`

Subscription for collection

Parameters

params: KeyParams | null
swrOptions: Options for SWR hook except fetcher

Return values

data: data for given path's collection
error: FirestoreError

import { useCollection } from "@tatsuokaniwa/swr-firestore";

const { data, error } = useCollection<Post>({
  path: "posts",
});

`useCollectionCount(params, swrOptions)`

Wrapper for getCountFromServer for collection

Parameters

params: KeyParams except parseDates | null
swrOptions: Options for SWR hook except fetcher

Return values

Returns SWRResponse

data: number for given path's collection count result
error: FirestoreError
isLoading: if there's an ongoing request and no "loaded data". Fallback data and previous data are not considered "loaded data"
isValidating: if there's a request or revalidation loading
mutate(data?, options?): function to mutate the cached data (details)

import { useCollectionCount } from "@tatsuokaniwa/swr-firestore";

const {
  data: postCount,
  error,
  isLoading,
} = useCollectionCount<Post>({
  path: "posts",
});

`useCollectionGroup(params, swrOptions)`

Subscription for collectionGroup

Parameters

params: KeyParams | null
swrOptions: Options for SWR hook except fetcher

Return values

data: data for given path's collectionGroup
error: FirestoreError

`useCollectionGroupCount(params, swrOptions)`

Wrapper for getCountFromServer for collectionGroup

Parameters

params: KeyParams except parseDates | null
swrOptions: Options for SWR hook except fetcher

Return values

Returns SWRResponse

data: number for given path's collectionGroup count result
error: FirestoreError
isLoading: if there's an ongoing request and no "loaded data". Fallback data and previous data are not considered "loaded data"
isValidating: if there's a request or revalidation loading
mutate(data?, options?): function to mutate the cached data (details)

`useDoc(params, swrOptions)`

Subscription for document

Parameters

params: KeyParams except where, orderBy, limit | null
swrOptions: Options for SWR hook except fetcher

Return values

data: data for given path's document
error: FirestoreError

import { useDoc } from "@tatsuokaniwa/swr-firestore";

const { data, error } = useDoc<Post>({
  path: `posts/${postId}`,
});

`useGetDocs(params, swrOptions)`

Fetch documents with firestore's getDocs function

Parameters

params: KeyParams & { useOfflineCache?: boolean; isCollectionGroup?: boolean } | null
set isCollectionGroup: true to get data from collectionGroup
swrOptions: Options for SWR hook except fetcher

Return values

Returns SWRResponse

data: data for given path's collection
error: FirestoreError
isLoading: if there's an ongoing request and no "loaded data". Fallback data and previous data are not considered "loaded data"
isValidating: if there's a request or revalidation loading
mutate(data?, options?): function to mutate the cached data (details)

import { useGetDocs } from "@tatsuokaniwa/swr-firestore";

const { data, error } = useGetDocs<Post>({
  path: `posts`,
});
// for collectionGroup
const { data, error } = useGetDocs<Comment>({
  path: `comments`,
  isCollectionGroup: true,
});

`useGetDoc(params, swrOptions)`

Fetch the document with firestore's getDoc function

Parameters

params: (KeyParams & { useOfflineCache?: boolean }) except where, orderBy, limit | null
swrOptions: Options for SWR hook except fetcher

Return values

Returns SWRResponse

data: data for given path's document
error: FirestoreError
isLoading: if there's an ongoing request and no "loaded data". Fallback data and previous data are not considered "loaded data"
isValidating: if there's a request or revalidation loading
mutate(data?, options?): function to mutate the cached data (details)

import { useGetDoc } from "@tatsuokaniwa/swr-firestore";

const { data, error } = useGetDoc<Post>({
  path: `posts/${postId}`,
});

Server module

`getCollection(params)`

Fetch documents using the Firebase Admin SDK and return the SWR key and data

Parameters

params: KeyParams

Return values

Returns Promise<{ key: string; data: DocumentData<T>[]; }>

key: SWR Key
data: documents in the collection for the given path

import { getCollection } from "@tatsuokaniwa/swr-firestore/server";

// For useCollection
const { key, data } = await getCollection<Post>({
  path: "posts",
  isSubscription: true, // Add the prefix `$sub$` to the SWR key
});
// For useGetDocs
const { key, data } = await getCollection<Post>({ path: "posts" });

`getCollectionCount(params)`

Fetch document's count using the Firebase Admin SDK and return the SWR key and data

Parameters

params: KeyParams except parseDates

Return values

Returns Promise<{ key: string; data: number; }>

key: SWR Key
data: number of documents in the collection for the given path.

import { getCollection } from "@tatsuokaniwa/swr-firestore/server";

// For useCollectionCount
const { key, data } = await getCollectionCount<Post>({ path: "posts" });

`getCollectionGroup(params)`

Fetch documents using the Firebase Admin SDK and return the SWR key and data

Parameters

params: KeyParams

Return values

Returns Promise<{ key: string; data: DocumentData<T>[]; }>

key: SWR Key
data: documents in the collectionGroup for the given path

import { getCollectionGroup } from "@tatsuokaniwa/swr-firestore/server";

// For useCollectionGroup
const { key, data } = await getCollectionGroup<Comment>({
  path: "comments",
  isSubscription: true, // Add the prefix `$sub$` to the SWR key
});
// For useGetDocs with isCollectionGroup
const { key, data } = await getCollectionGroup<Comment>({ path: "comments" });

`getCollectionGroupCount(params)`

Fetch document's count using the Firebase Admin SDK and return the SWR key and data

Parameters

params: KeyParams except parseDates

Return values

Returns Promise<{ key: string; data: number; }>

key: SWR Key
data: number of documents in the collection group for the given path

import { getCollectionGroupCount } from "@tatsuokaniwa/swr-firestore/server";

// For useCollectionGroupCount
const { key, data } = await getCollectionGroupCount<Comment>({
  path: "comments",
});

`getDoc(params)`

Fetch the document using the Firebase Admin SDK and return the SWR key and data

Parameters

params: KeyParams

Return values

Returns Promise<{ key: string; data: DocumentData<T>; }>

key: SWR Key
data: data for given path's document

import { getDoc } from "@tatsuokaniwa/swr-firestore/server";

// For useDoc
const { key, data } = await getDoc<Post>({
  path: `posts/${postId}`,
  isSubscription: true, // Add the prefix `$sub$` to the SWR key
});
// For useGetDoc
const { key, data } = await getDoc<Post>({ path: `posts/${postId}` });