Tutorials


Using pagination with Firebase Firestore and React.js is not as simple as it
looks; I know, as it's given me more than a headache.

Unfortunately, Firestore has an important limitation: in fact, we cannot
paginate data using numerical indexes.

For example, we cannot make a query
that takes our data from index 20 to index 40. Instead, our starting point will
need to be a `document snapshot`: this makes it impossible to paginate data
by a specific page, but, instead, we can opt for a sequential pagination.

In this article, I want to show you the simplest way to paginate your
Firestore data in a table, with the possibility of going back and forth
between pages.

Many of the examples below will use Makerkit's components: these are simple
implementation details, so just ignore them if you're not using Makerkit.

The final result will look like the image below:

<Image src='/assets/images/posts/tasks-pagination.webp' width={"2348"} height=
  {"860"} />

### Writing Paginated queries with Firestore

Let's assume that we want to make a query to the `tasks` collection by a
couple of parameters:

1. we will query the tasks that have an `organizationId` property
that matches the argument `organizationId`
2. we will paginate them ordered by the property `dueDate`
3. we will use two parameters to control the pagination: `cursor` and
`itemsPerPage`

```tsx title="useFetchTasks.ts"
import { useFirestore, useFirestoreCollection } from 'reactfire';

import {
  collection,
  CollectionReference,
  limit,
  orderBy,
  startAfter,
  query,
  where,
  DocumentSnapshot,
} from 'firebase/firestore';

import { Task } from '~/lib/tasks/types/task';

function useFetchTasks(
  organizationId: string,
  params: {
    cursor: Maybe<DocumentSnapshot>;
    itemsPerPage: number;
  }
) {
  const firestore = useFirestore();

  // collection path
  const tasksCollection = 'tasks';

  // we order tasks by the "dueDate" property
  const order = orderBy('dueDate', 'desc');

  const path = `organizationId`;
  const operator = '==';

  // create default constraints
  const constraints = [
    where(path, operator, organizationId),
    order,
    limit(params.itemsPerPage),
  ];

  // if cursor is not undefined (e.g. not initial query)
  // we pass it as a constraint
  if (params.cursor) {
    constraints.push(
      startAfter(params.cursor)
    );
  }

  const collectionRef = collection(
    firestore,
    tasksCollection
  ) as CollectionReference<WithId<Task>>;

  const organizationsQuery = query(collectionRef, ...constraints);

  return useFirestoreCollection(organizationsQuery, {
    idField: 'id',
  });
}

export default useFetchTasks;
```

We are going to use the custom hook above to fetch data from the tasks
collection. But first, let's create a new custom hook: `useFetchTasksCount`.

### Counting the documents of a Firestore Collection

As of October 2022, this feature has just been released by Firebase:
counting how many documents are in a Firestore collection.

Thanks to this new functionality, we will know if we can continue paginating
our documents generally, it's also a good UX practice to show how many
documents the user can scroll through.

To count the total number of documents in a Firestore collection we are
going to use the function `getCountFromServer`: this function accepts a
Firestore `query` and will return the number of documents found according to
the query.

In our case, we want to collect the total count of tasks given the
`organizationId` passed as parameter.

```tsx title="useFetchTasksCount.ts"
import { useCallback } from 'react';
import { useFirestore } from 'reactfire';

import {
  where,
  getCountFromServer,
  query,
  collection,
  CollectionReference,
} from 'firebase/firestore';

import { Task } from '~/lib/tasks/types/task';

const tasksCollection = 'tasks';
const path = `organizationId`;
const operator = '==';

function useFetchTasksCount() {
  const firestore = useFirestore();

  return useCallback(
    (organizationId: string) => {
      const constraints = [where(path, operator, organizationId)];

      const collectionRef = collection(
        firestore,
        tasksCollection
      ) as CollectionReference<WithId<Task>>;

      return getCountFromServer(
        query(collectionRef, ...constraints)
      );
    },
    [firestore]
  );
}

export default useFetchTasksCount;
```

## Paginated Table with Firestore and React.js

Now, we can finally use our custom hooks to fetch data from our Firestore
collections and display it in a simple table.

We create two components: a table named `TasksTable` and a pagination
component named `Pagination`.

1. The table component is responsible for fetching and displaying the data
2. The pagination component will render the buttons to go back and forth,
and will notify the table component when the page is changed

We're going to use one single state property for handling re-renderings: the
`page` state. When this property changes (using the user's input), the
component will update the cursor and fetch the new data.

```tsx title="TasksTable.tsx"
const itemsPerPage = 4;

const TasksTable: React.FC<{
  organizationId: string;
}> = ({ organizationId }) => {
  const [page, setPage] = useState(0);

  // keep cursors in memory
  const cursors = useRef<Map<number, DocumentSnapshot>>(new Map());

  // use query fetching
  const { data, status } = useFetchTasks(organizationId, {
    cursor: cursors.current.get(page),
    itemsPerPage,
  });

  // collect all the tasks JSON data
  const tasks = useMemo(() => {
    return data?.docs?.map((doc) => doc.data()) ?? [];
  }, [data]);

  // callback called when changing page
  const onPageChanged = useCallback(
    (nextPage: number) => {
      setPage((page) => {
        // first, we save the last document as page's cursor
        cursors.current.set(
          page + 1,
          data.docs[data.docs.length - 1]
        );

        // then we update the state with the next page's number
        return nextPage;
      });
    },
    [data]
  );

  if (status === `loading`) {
    return <span>Loading Tasks...</span>;
  }

  return (
    <div className={'flex flex-col space-y-2'}>
      <table className={'Table'}>
        <thead>
          <tr>
            <th>Name</th>
            <th>Due Date</th>
            <th>Done</th>
          </tr>
        </thead>

        <tbody>
          {tasks.map((task) => {
            return (
              <tr key={task.name}>
                <td>{task.name}</td>
                <td>{task.dueDate}</td>
                <td>{task.done ? `Done` : `Not done`}</td>
              </tr>
            );
          })}
        </tbody>
      </table>

      <Pagination
        currentPage={page}
        organizationId={organizationId}
        pageChanged={onPageChanged}
      />
    </div>
  );
};

export default TasksTable;
```

Let's explain the above.

We keep two stateful constants: `page` and `cursors`.

1. `page` represents the current page. Only the `page` state will trigger re-renderings.
2. `cursors` represents a map page->cursor. We need the cursor because we
use it to retrieve the tasks of a certain page. To prevent re-renderings,
`cursors` is a reference.

```tsx
const [page, setPage] = useState(0);

// keep cursors in memory
const cursors = useRef<Map<number, DocumentSnapshot>>(new Map());
```

Then, we use the custom React hook above to fetch the paginated data from
Firestore.

As you can see below, we pass the page's cursor based on the `page` state:

```tsx
// use query fetching
const { data, status } = useFetchTasks(organizationId, {
  cursor: cursors.current.get(page),
  itemsPerPage,
});

// collect all the tasks JSON data
const tasks = useMemo(() => {
  return data?.docs?.map((doc) => doc.data()) ?? [];
}, [data]);
```

Finally, we listen to the `Pagination` component's callback that will notify
us when the user changes page.

Of course, we set the `page` state to the new page. It's also important to
notice that it's in this callback that we set the cursors for the current
page. In this way, we avoid re-renderings. When the component re-renders, it
will pick up the correct `cursor` for the current page.

```tsx
// callback called when changing page
const onPageChanged = useCallback(
  (nextPage: number) => {
    setPage((page) => {
      // first, we save the last document as page's cursor
      cursors.current.set(
        page + 1,
        data.docs[data.docs.length - 1]
      );

      // then we update the state with the next page's number
      return nextPage;
    });
  },
  [data]
);
```

Now, let's take a look at the pagination component:

```tsx
function Pagination(
  props: React.PropsWithChildren<{
    organizationId: string;
    currentPage: number;
    pageChanged: (page: number) => unknown;
  }>
) {
  const fetchTaskCount = useFetchTasksCount();
  const [tasksCount, setTasksCount] = useState<number>();

  useEffect(() => {
    // when the component mounts, we store the tasks count in the state
    fetchTaskCount(props.organizationId).then((result) => {
      setTasksCount(result.data().count);
    });
  }, [fetchTaskCount, props.organizationId]);

  if (tasksCount === undefined) {
    return <div>Loading...</div>;
  }

  const totalPages = Math.floor(tasksCount / itemsPerPage);
  const canGoBack = props.currentPage >= 1;
  const canGoNext = props.currentPage < totalPages;

  return (
    <div className={'flex flex-row justify-end space-x-0.5'}>
      <Button
        color={'transparent'}
        disabled={!canGoBack}
        onClick={() => props.pageChanged(props.currentPage - 1)}
      >
        <span className={'flex items-center space-x-2'}>
          <ChevronLeftIcon className={'h-5'} />
          <span>Previous</span>
        </span>
      </Button>

      <Button
        color={'transparent'}
        disabled={!canGoNext}
        onClick={() => props.pageChanged(props.currentPage + 1)}
      >
        <span className={'flex items-center space-x-2'}>
          <span>Next</span>

          <ChevronRightIcon className={'h-5'} />
        </span>
      </Button>
    </div>
  );
}
```

## Demo

Below is the final result using the Makerkit's components:

<Video src={'/assets/images/posts/tasks-pagination-demo.mp4'} />


Pagination with React.js and Firebase Firestore


Finally, Firebase has shipped one of the most requested features by
customers: using Firestore queries in the Firebase Storage security
rules: this is incredibly useful when accessing data that is not part of the
user's auth metadata: as it turns out, it's a very common scenario.

The Firebase team has historically warned that performance was the key
reason that adding this feature was not feasible, and honestly I was sort of
disillusioned this would be ever shipped. I am so glad I was wrong.

### Firestore functions within the Storage Security Rules

The Storage Security rules have been enriched with **new powerful functions
that allow cross-service communication** between Firebase
Firestore and Firebase Storage.

We have access to two new functions:

1. `firestore.get`: allows us to fetch the full object of a Firestore document
2. `firestore.exists`: allows us to check if a document exists

This is useful in many situations, such as when a Storage asset is shared
between many users that belong to the same group.

### ...a look at the past

If you have read [my article about Firebase Storage group security](/blog/tutorials/group-security-firebase-storage-nextjs), you'll remember
that we used a valur stored in the user's `custom claims` to check that the
user's group could read or write to Storage asset under a specific path.

For example, assuming the user belonged to the organization with ID `123`,
then the user could only read or write to the path `organizations/123/**`.

To do this, we used a small hack:
1. Added `organizationId` to the asset's metadata
2. Stored a custom claim `organizationId` in the user's authentication data
3. Compared the two using the Firebase Storage rules

The biggest issues were:
1. Propagating the custom claims to the client wen they changed
2. Updating the custom claim when the user changed organization or created one

Long story short, it was a hassle. Thankfully, the new Firebase Storage
rules will allow us to skip all of this.

### The new way: How to use Firestore queries in Storage Security Rules

Let's assume that the users of an organizations have a shared Storage folder
at `/organizations/{organizationId}`, and that the Firestore entity of the
organization has the following information:

```tsx
interface Organization {
  members: {
    [userId]: UserRole;
  }
}
```

As you can see, we have access to a user ID using the path `/organizations/
{organizationId}` and by accessing the object `members.{userId}`.

When writing our Storage rules to protect the organization's assets at
`/organizations/{organizationId}/{fileName=**}`, we
can write the following:

```js
rules_version = '2';
service firebase.storage {
  match /b/{bucket}/o {
    function userId() {
      return request.auth.uid;
    }

    function getOrganization(uid) {
      return firestore.get(/databases/(default)/documents/organizations/$(uid));
    }

    function getOrganizationMembers(uid) {
      return getOrganization(uid).data.members;
    }

    match /organizations/{organizationId}/{fileName=**} {
      allow read, write: if userId() in getOrganizationMembers(organizationId);
    }
  }
}
```

Thanks to the above, we protect writes and reads to `/organizations/
{organizationId}/{fileName=**}` to the users whose ID is in the members's
object of the organization's Firestore record. This waaay easier than the
custom claims hack we had to resort to before this was available.

### Enabling cross-service communication

This feature is already enabled in your local emulators if you're running
the version `11.10.0` of the `firebase-tools` package, but you will need to
enable cross-communication by updating the rules in your Firebase Console.

By enabling the Firestore and Storage services to communicate, you're
effectively giving permissions to Firebase Storage to read your Firestore data.

<Image src='/assets/images/posts/cross-communication-service-modal.webp'
       width="3096" height="1714" />

For better performance **ensure that both services are running within the
same region** which will result in the fastest round-trips between the services.


Using Firestore in Firebase Storage Rules


As a result of the new changes in Firebase Storage allowing you to read
Firestore data, we suggest to use the new method outlined in the following
article: <a className={'underline text-black-500'} href={'/blog/tutorials/firestore-storage-rules'}>Using Firestore in Firebase Storage Rules</a>

---

Firebase Storage's security rules are relatively simple to write when the entity
to protect is individual: for example, making sure that the current user can
perform certain actions, or that an individual
organization can access certain assets in a bucket.

What's slightly trickier with Firebase Storage is writing rules that affect
several users or groups. What makes it particularly hard is the lack of
context we can use in the security rules: for example, we cannot read any
data from Firestore, and are confined to the session's authentication data of
the signed-in user.

Among the authentication data, we can access within the Firebase Storage
security rules, we also find **custom claims, which are some
metadata that you can attach to each user**. This is great, but the bad news
is that the space is extremely limited, hence we cannot simply store all the
groups an individual belongs to.

For example, if your user belongs to an organization, you may want the user
to be able to read all the assets belonging to the organization.
Unfortunately, this is simpler said than done.

While the Firebase documentation
does indeed mention a solution involving custom tokens for this specific
problem, but it does not go as far as showing a proper implementation.

Thankfully, we at Makerkit have thought of a simple and painless solution,
which we will describe in this blog post.

### Scenario: A shared folder within an Organization

The following is an extremely common scenario in any SaaS that supports
users of an organization, project, or team: sharing a folder among team
members of the same team (or whatever we want to call it).

Writing rules that can guard against nonauthorized access to a specific
organization would be fairly simple, but how can we write the logic
necessary to protect access to the users that do not belong to the team?

1. **One way would be to use Firebase Storage from the Firebase Admin on the
server**, and block
access using server-side logic. Unfortunately, this is cumbersome and hard
to maintain, which defeats the purpose of using Firebase Storage straight
from the client. So, in most cases, this is not the way to go.

2.  **Another way can be using Custom Claims**, and storing the group
information
(such as an ID) in the user's session data. Because we can access these in
the Firebase Storage security rules, we can write them such to block or
grant access to the user.

Let's assume our Organization has the ID 123, and the current user belongs
to such organization. Now, let's try to write a security rule that knowing
the user's custom claims would be able to grant access to the user:

So, let's write a rule that, given an organization `organizationId`, can
grant access to only the users who have a `custom claim` named
`organizationId` that matches the path being written.

The path we want to write to is: `/{organizationId}/uploads/{fileName=**}`:

```
match /{organizationId}/uploads/{fileName=**} {
  allow create, read: if organizationId == request.auth.token.organizationId;
  allow delete, update: if resource.metadata.organizationId == request.auth.token.organizationId;
}
```

This rule would prevent users who do not have the correct custom claim
`organizationId` to rear, write, update or delete any item within that path.

The question now is, how can we assign the `organizationId` custom claim to
the user?

We can do this when:
- the server renders a page
- the user changes organization

Let's see how we do it in Makerkit!

## Assigning Custom Claims

On any guarded page (eg. server-side protected) of the application, we have
the possibility to assign the current organization ID (passed via session
cookie) to the user's metadata.

The logic is simple:

1. fetch custom claims
2. get the current organization ID from the cookies
3. if these are different, then update the custom claims with the current
organization ID

### Assigning custom claims at page load

Assigning custom claims is also reasonably simple using the Firebase
Authentication SDK.

**1) First, we define the function to update the custom claims**:

```tsx
function setOrganizationIdCustomClaims(
  userId: string,
  organizationId: string,
  existingClaims: UnknownObject
) {
  const auth = getAuth();

  return auth.setCustomUserClaims(userId, {
    ...existingClaims,
    organizationId,
  });
}
```

**2) Here is a snippet of code with the logic above:**

```tsx
const userDidChangeOrganization =
  authOrganizationId !== currentOrganizationId;

const shouldUpdateTokenClaims =
    !authOrganizationId || userDidChangeOrganization;

if (shouldUpdateTokenClaims) {
  await setOrganizationIdCustomClaims(
    user.id,
    organization.id,
    customClaims
  );
}
```
#### Where to add this logic?

**Remember**: the snippet above should be called before rendering the page,
ideally within the `getServerSideProps` function.

### Assigning custom claims when the user switches organization

If your users can switch to another organization, we need to
make sure to update the metadata with the current organization ID.

**Notice**: instead of adding a new organization, we simply update it due to
the limited amount of space we can store within the custom claims.

You can achieve this in two different ways:

1. Simply refresh the page when the user changes organization (which
sometimes can be good for avoiding state management issues)
2. A more seamless way that involves sending an HTTP request to update the
current user's custom claims

In Makerkit, we opted for the second option, **which is a bit more complex but
offers a better UX**.

#### An API endpoint to update the user's custom claims

1) First of all, we need an API endpoint capable of updating the user's custom
claims using the newly selected organization:

```tsx title="/api/organizations/token.tsx"
import { NextApiRequest, NextApiResponse } from 'next';
import { getAuth } from 'firebase-admin/auth';

import { withAuthedUser } from '~/core/middleware/with-authed-user';
import { withPipe } from '~/core/middleware/with-pipe';
import { withMethodsGuard } from '~/core/middleware/with-methods-guard';
import { getCurrentOrganization } from '~/lib/server/organizations/get-current-organization';
import { forbiddenException, notFoundException } from '~/core/http-exceptions';

export async function organizationTokenHandler(
  req: NextApiRequest,
  res: NextApiResponse
) {
  const userId = req.firebaseUser.uid;
  const organizationId = req.cookies.organizationId;

  if (!userId || !organizationId) {
    return forbiddenException(res);
  }

  const organization = await getCurrentOrganization(userId);

  if (!organization) {
    return forbiddenException(res);
  }

  const auth = getAuth();
  const user = await auth.getUser(userId);

  if (!user) {
    return notFoundException(res);
  }

  await auth.setCustomUserClaims(userId, {
    ...(user.customClaims ?? {}),
    organizationId,
  });

  return res.send({ success: true });
}

export default withPipe(
  withMethodsGuard(['POST']),
  withAuthedUser,
  organizationTokenHandler
);
```

2) Secondly, we write a hook that takes care of calling this endpoint using our
hook `useApiRequest`:

```tsx title="~/lib/organizations/hooks/use-update-organization-id-token"
import { useApiRequest } from '~/core/hooks/use-api';

export function useUpdateOrganizationIdToken() {
  const path = `/api/organizations/token`;

  return useApiRequest(path);
}
```

3) Finally, we call the hook when the user changes the organization. This
involves two steps:
1. Executing the HTTP request written above
2. Hard refreshing the user's custom claims using the Firebase SDK's API
`auth.currentUser?.getIdTokenResult(true)`

```tsx title="~/components/OrganizationsSelector.tsx"
import { useUpdateOrganizationIdToken } from '~/lib/organizations/hooks/use-update-organization-id-token';

// within the Component

const [updateOrganizationIdToken] = useUpdateOrganizationIdToken();

// this is called by your component when the organization ID changes
const onChange = useCallback(async () => {
  await updateOrganizationIdToken();
  await auth.currentUser?.getIdTokenResult(true);
}, [auth.currentUser, updateOrganizationIdToken]);

return <OrganizationsListBox onChange={onChange} />;
```

## Conclusion

And that's all!

With the code above, **we can easily add Group Security to our
organizations, teams, projects, and any entity where multiple users are a
part of in Firebase**.

I hope you enjoyed this post. Please consider subscribing to our newsletter
or [purchasing a copy of Makerkit](https://github.com/sponsors/makerkit),
where we took care of all this code for you already.


Group Security with Firestore Storage and Next.js


There are tons of resources on the Internet for making a SaaS data model,
but very few use NoSQL or Firebase Firestore.

Firestore is fairly simple to use, but structuring it well requires
analysis from a different point of view compared to other databases:

- **securing the data** using [Firestore Security Rules](/blog/tutorials/in-depth-guide-firestore-security-rules)
- optimizing queries and writes to **save on billing costs** (remember, we pay
for reads/writes and the data transferred)
- due to the querying limitations in Firestore, ensuring that the
**data-model allows our queries**

Developing an architecture without taking into account the points above can
result in **expensive and inefficient decisions**.

We developed MakerKit with simplicity in mind, in a way such that you
can effortlessly adapt the data model we created to your application's domain.

In this post, we explore **the data model we at MakerKit adopted for our
own SaaS boilerplate**. Feel free to comment, take it and extend it as you wish!

### Overview of a simple SaaS data model

Every SaaS has a different data model, but we can identify certain entities
that will be pretty common across most apps.

These are:
- Users/Accounts
- Groups of users, such as organizations/teams/projects
- Invites a member to join a group
- A plan/membership the group subscribed to

The above is the core part of a SaaS and what any SaaS boilerplate should
provide by default. However, getting it right for every use case and scenario is impossible:
hence, MakerKit's model is exhaustive yet straightforward.

## Users and Accounts

Users/Accounts are the primary and most basic entities of most applications.
Thanks to Firebase, the aspect of authenticating accounts is separate from
the users' data, which helps simplify our job.

Whenever a user creates a new account for your application using Firebase
Authentication, this **will be added to the Auth Database, but not to
Firestore**.

So, how can we make sure that a user also has its relative
record in Firestore? There are a couple of ways.

## Creating user records in Firestore
First, what you should know is that the most common way of creating user
records in Firestore is to create a `users` collection.

We can set as the ID of the user record the same ID created by Firebase
Authentication, so we can keep them easily in sync and make sure it's unique
across the collection.

Let's assume the ID created by Firebase is `423631`, then we will create a
record in Firestore at the path: `/users/423631`.

#### Creating a record after sign-up

The simplest way is to create a Firestore record right after sign-up. It's
also not the most straightforward when you take into account that **the
transaction isn't atomic** and any
errors can happen between the sign-up and
the creation of the record, which may result in a poor UX and an out-of-sync DB.

#### Creating a record as part of an Onboarding Wizard

The below is my favorite way, especially for collecting valuable data for and about
your users.

After sign-up, your route guard checks that the user is onboarded or
that the user record exists. You can do this using a token's `custom metadata,`
for example.

If not, redirect to the onboarding wizard,
which will take care of creating a user record and its relative organization.

The above is the approach taken by MakerKit.

## Organizations

Organizations, or groups of users, contain information about their members
and their role within the organization.

In MakerKit, organizations have a property named `members,` which is a map
containing information about the member. **We use an object to simplify writing security rules**.

The following is the interface of an organization:

```tsx title="organization.ts"
type UserId = string; // this is the ID assigned by Firebase Auth

interface Organization {
  name: string;
  members: Record<UserId, FirestoreOrganizationMembership>;

  timezone?: string;
  logoURL?: string | null;
  subscription?: OrganizationSubscription;
  customerId?: string;
}
```

Let's focus on the organization members for the time being.

Each member has the following interface:

```tsx title="member.ts"
interface Member {
  role: MembershipRole;
  user: UserRef;
}
```

As you can see, we stored two properties:
- `role` is an enum that defines the user's role. This is very simple
and doesn't allow for granular permissions, which you may needs
- `user` is a Firestore `reference` to the user record for simplifying access to the user
record. It can also be an ID.

### Querying Organizations and Members

How does the data structure above allow us to fulfill the following use-cases?

- Fetch all the organizations the current user belongs to
- Fetch all the members of the selected organization
- Make sure our security rules can allow us to enforce permissions and allow
for efficient querying

#### Fetching data for a specific organization

The user's current organization is passed in via a cookie when the page gets
rendered using SSR. By selecting the first organization, the cookie
will hold the value of the current organization ID selected for the user.

We will use this cookie to fetch the data of the current organization. To do
so, we can query the path `/organizations/{id}`, using the following hook:

```tsx title="use-fetch-organization.ts"
function useFetchOrganization(organizationId: string) {
  const firestore = useFirestore();
  const path = `/organizations`;

  const ref = doc(
    firestore,
    path,
    organizationId
  );

  return useFirestoreDocData(ref);
}
```

##### Security Rules to read an Organization

How can we structure our Firestore Security Rules to allow this
query?

We can check if the authed user ID is within the members `map` of the
organization.

The function below allow us to read the current user ID:

```js title="firestore.rules"
function userId() {
    return request.auth.uid;
}
```

We can now check if the ID exists in the members' `map`:

```js title="firestore.rules"
match /organizations/{organizationId} {
  allow read: if userId() in existingData().members;
}
```

#### Fetching a user's organizations

To list all the organizations a user belongs to, we can check if the user ID
appears to be within the `members` property of the organization.

The hook below will allow us to list the user's organizations:

```tsx title="use-fetch-user-organizations.ts"
export function useFetchUserOrganizations(userId: string) {
  const firestore = useFirestore();
  const path = `organizations`;

  const organizationsCollection = collection(
    firestore,
    path
  );

  const userPath = `members.${userId}`;
  const operator = '!=';
  const constraint = where(userPath, operator, null);

  const organizationsQuery = query(
    organizationsCollection,
    constraint
  );

  return useFirestoreCollectionData(organizationsQuery);
}
```

### Invites

We store `invites` to join an organization as a collection under each
organization, such as `organizations/1/invites/1`.

Because we may need to access an invitation without knowing the organization
ID, we have two ways to go:

- do not store invitations as a `subcollection`, but as a top-level collection
- create an index using the Firestore Console, which allows us to query deep
collection using the `collectionGroup` method. At MakerKit, we decided to go
with the second way

#### Defining the Invite's data model

Below is the interface of an `Invite`:

```tsx title="membership-invite.ts"
interface MembershipInvite {
  email: string;
  role: MembershipRole;
  code: string;
  expiresAt: number;

  organization: {
    id: string;
    name: string;
  };
}
```

We stored the email of the user invited, which can also be helpful if you
want to restrict the invited user's email to the same one provided by the
inviter.

Additionally, it's essential to store the role assigned by the invitee, the
the time when we consider the invite expired, and a unique code `code`
which we can use to expose and retrieve the invite.

We also add (duplicate) some information about the organization to embed it
into the invitation email. Adding the organization saves one more read each time we query the
invite.

The invite gets sent with a URL similar to the following: `/auth/invite/{code}`. We know which invite we need to process by adding the code to the URL.

After the invite is processed, it gets deleted from the DB.

#### Security Rules for Invites

To securely list the invites to join an organization, we need to
check that the member reading the invites belongs to it:

```js title="firestore.rules"
match /organizations/{organizationId} {
    match /invites/{inviteId} {
        allow list: if userIsMemberByOrganizationId(organizationId);
    }
}
```

As you may have noticed above, we can access the organization ID,
which also allows us to query the organization document.

The functions below help us evaluate if, given an organization ID, the
current user belongs to it.

```js title="firestore.rules"
function userIsMemberByOrganizationId(organizationId) {
    return userIsMember(
        getOrganization(organizationId)
    );
}

function getOrganization(organization) {
    return get(/databases/$(database)/documents/organizations/$(organization));
}

function userIsMember(organization) {
    let role =
        getUserRole(organization, userId());

    return role >= 0;
}

function getUserRole(organization, userId) {
    let members = organization.data.members;
    let member = members[userId];

    return member != null ? member.role : -1;
}
```

Yes, it looks very similar, but the code above **is not Javascript**!

## Payments and Subscriptions

Without payments, your SaaS won't get paid. It's needless to say that any
SaaS will eventually need a payment system.

The most popular for startups is probably Stripe, but it's also common
having to integrate different billing
systems for hosting your SaaS on marketplaces: for instance, you may have to
get paid via Apple if you host your app on iOS, or using Shopify Billing if
you allow shops to install the app via the Shopify Marketplace.

In practice, it means we will need a model generic enough to adapt to
multiple payments processors.

### Subscription Model

The model below is added to an `Organization` when creating a plan. We consider it an optional field because
creating a plan **may or may not happen**.

```tsx title="organization-subscription.ts"
type PaymentProcessor = string;

enum OrganizationPlanStatus {
  AwaitingPayment = 'awaitingPayment',
  Paid = 'paid',
}

interface OrganizationSubscription {
    id: string;
    planId: string; // priceId in Stripe
    processor: PaymentProcessor;

    status: OrganizationPlanStatus;
    currency: string | null;

    interval: string | null;
    intervalCount: number | null;

    createdAt: UnixTimestamp;
    periodStartsAt: UnixTimestamp;
    periodEndsAt: UnixTimestamp;
    trialStartsAt: UnixTimestamp | null;
    trialEndsAt: UnixTimestamp | null;
}
```

The above is the bare minimum amount of data you may want to store; depending on
your needs, you may want to collect more information from the payments
processors' webhooks.

### Security Rules for Subscriptions

A membership is probably not something you want clients able to modify, no
matter which role the user has.

To avoid any issues, we will need to write a security rule that disallows
updating the `subscription` fields of an
organization.

```js title="firestore.rules"
match /organizations/{organizationId} {
    allow update: if canUpdateOrganization(organizationId);
}

function canUpdateOrganization(organizationId) {
    let isMember = userIsMemberByOrganizationId(organizationId);
    let noDisallowedFields = fieldsNotInUpdateAction(['members', 'subscription']);

    return isMember && noDisallowedFields;
}
```

As an alternative to this, you can also store subscriptions in their
collection. The only downside to this is that it takes one additional read
to grab the subscriptions' data.

## Final Words

Time to wrap this post. The above is an introduction to how we modeled our
Firestore data structure to support the basics needs of any SaaS application,
while keeping it open for change; as it will inevitably happen, there will
be lots of changes.

I hope you've found this helpful post. Consider [contacting us](/contact) if
you need any help with starting to build your SaaS application with Next.js
and Firebase. We're here to help.


A Data Model for your Firebase SaaS


Next.js is a serverless framework that can be used with any database you
prefer, and it's one of the reasons why it's so popular among developers.

## Why we use Firestore with Next.js
Firestore is a common choice among Next.js developers due to
it being performant, scalable, simple, real-time, offline-first, and with a
generous free tier. There's a lot to like.

Firestore is a serverless database that we can use from both the client and
the server. Communicating with Firestore right from the browser
is likely one of its biggest strengths: you no longer need an API to read
and write to your database because it can be accessed directly via the SDK.

The possibility of not having to write an API is a huge time-saver for
developers, and further help to front-end developers who want to write
full-stack applications from scratch.

If you're wondering how we can keep our database secure despite being used
from a client (good question!), you may want to take a look at [this guide for
writing Security Rules for your Firestore database](/blog/tutorials/in-depth-guide-firestore-security-rules).

One of the biggest criticisms of Firestore was the fact that it added a
significant additional size to client-side bundles due to its heavy SDK.

Fortunately, The newly released version 9 of Firebase made massive
improvements in terms of size, which can go even further when using the
Lite version.

In this article, I want to introduce you to Firestore using Next.js at the
time of writing one of the most popular React frameworks, and the framework we built
MakerKit on.

## Setting Up Firestore with Next.js

If you haven't yet configured your application, you may want to get started
using our article about [setting up the Firestore Emulators with Next.js](/blog/tutorials/setting-up-firebase-emulators-nextjs).

We use `reactfire`; it's a [Typescript library by Firebase](https://github.com/FirebaseExtended/reactfire) designed to
help developers use Firebase with any React codebase.

### Firestore Provider

We need to initialize Firestore and write a provider to wrap the children that use the Firestore hooks.

The code below is a simplified version of what MakerKit does to initialize a
Firestore instance:

```tsx title="FirebaseFirestoreProvider.tsx"
import { FirestoreProvider, useFirebaseApp } from 'reactfire';
import { useMemo } from 'react';

import {
  enableIndexedDbPersistence,
  connectFirestoreEmulator,
  initializeFirestore,
} from 'firebase/firestore';

import { isBrowser } from '~/core/generic';

export default function FirebaseFirestoreProvider({
  children,
  useEmulator,
}: React.PropsWithChildren<{ useEmulator?: boolean }>) {
  const firestore = useFirestore();

  // connect to emulator if enabled
  if (useEmulator) {
    const host = getFirestoreHost();
    const port = Number(getFirestorePort());

    try {
     connectFirestoreEmulator(firestore, host, port);
    } catch (e) {
      // this may happen on re-renderings
    }
  }

  const enablePersistence = isBrowser();

  // We enable offline capabilities by caching Firestore in IndexedDB
  // NB: if you don't want to cache results, please remove the next few lines
  if (enablePersistence) {
    enableIndexedDbPersistence(firestore)
  }

  return <FirestoreProvider sdk={firestore}>{children}</FirestoreProvider>;
}

function getFirestoreHost() {
  return process.env.NEXT_PUBLIC_FIREBASE_EMULATOR_HOST ?? 'localhost';
}

function getFirestorePort() {
  return process.env.NEXT_PUBLIC_FIRESTORE_EMULATOR_PORT ?? 8080;
}

function useFirestore() {
  const app = useFirebaseApp();

  return useMemo(() => initializeFirestore(app, {}), [app]);
}
```

If we use the provider above in `_app.tsx`, every page can have access to
Firestore. Adding the Firebase providers may not be the best solution depending on what your application does and how lightweight you want your pages.

### Our first Firestore hook to read a document

The library `Reactfire` helps us with writing queries to our Firestore database
thanks to a list of predefined React hooks.

For example, one common query in SaaS applications is to fetch the
organization/project a user belongs to. In MakerKit, we wrote it similarly
to the code below:

```tsx title="use-fetch-organization.ts"
import { useFirestore, useFirestoreDocData } from 'reactfire';
import { doc, DocumentReference } from 'firebase/firestore';
import { Organization } from '~/lib/organizations/types/organization';

type Response = Organization & { id: string; };

export function useFetchOrganization(organizationId: string) {
  const firestore = useFirestore();
  const organizationsPath = `/organizations`;

  const ref = doc(
    firestore,
    organizationsPath,
    organizationId
  ) as DocumentReference<Response>;

  return useFirestoreDocData(ref, { idField: 'id' });
}
```

We imported the `Firestore` instance using the React hook `useFirestore`. By using the function `doc` we can get a reference to a Firestore document at the path specified. In this case, we're fetching a reference of the path
`/organizations/${organizationId}`.

Using the hook `useFirestoreDocData,` we can directly query and retrieve the document's data.

By adding the property `idField`, we're also adding the `id` of the document to the data object. Adding the `id` field is the reason why we merge
the interface of the response with the interface `{ id: string }`.

#### Reading a list of documents using Firestore

To read a list of documents from a Firestore collection, we can use the
`useFirestoreCollectionData` hook.

```tsx title="use-fetch-user-organizations.ts"
import { useFirestore, useFirestoreCollectionData } from 'reactfire';
import { collection, CollectionReference, where, query } from
'firebase/firestore';

export function useFetchUserOrganizations(userId: string) {
  const firestore = useFirestore();
  const organizationsPath = `organizations`;

  const ref = collection(
    firestore,
    organizationsPath
  ) as CollectionReference<Organization>;

  const userPath = `members.${userId}`;
  const operator = '!=';

  // adding the constraint where. This means: retrieve the organizations
  // where the field members[userId] is not null, eg: it exists
  const constraint = where(userPath, operator, null);
  const organizationsQuery = query(ref, constraint);

  return useFirestoreCollectionData(organizationsQuery);
}
```

### Using document queries in Firestore

Reactfire's hooks are async and therefore re-render based on the
status of the hook, which can be one of the following: `loading`, `error`, or
`success`.

```tsx title="organization/index.ts"
const Organization: React.FC<{
  id: string
}> = ({ id }) => {
  const { data: organization, status }
    = useFetchOrganization(id);

  // warn users there was an error
  if (status === 'error') {
    return <p>Ops! Error encountered while loading organization data...</p>
  }

  // show a loading indicator
  if (status === 'loading') {
    return <p>Loading organization data...</p>
  }

  // all good! display organization data
  return <OrganizationDetail organization={organization} />;
}
```

### Using document writes in Firestore

Unlike queries, `Reactfire` does not provide any hook to write to documents.

But we can easily make our own by using `useState` (NB: the following is a
a simplified example, but you'll get the gist).

```tsx title="use-create-organization.ts"
import { useCallback, useState } from "react";

import {
  collection,
  addDoc,
} from 'firebase/firestore';

export function useCreateOrganization() {
  const firestore = useFirestore();
  const [state, setState] = useState();

  const mutation = useCallback(async (organization: Organization) => {
    setState('loading');

    const organizationsPath = `/organizations`;
    const collectionReference =
      collection(firestore, organizationsPath);

    try {
      await addDoc(
        collectionReference,
        organization
      );

      setState('success');
    } catch (e) {
      setState('error');
    }
  }, [firestore]);

  return [
    mutation,
    state,
  ] as [
    typeof mutation,
    typeof state,
  ];
}
```

Using the pattern above, we send the mutation as the first element of the
array, and the state of the mutation as the second element.

The pattern can be used as follows:

```tsx title="OrganizationForm.tsx"
function OrganizationForm() {
  const [
    createOrganization,
    createOrganizationState
  ] = useCreateOrganization();

  if (createOrganizationState === 'error') {
    return <p>Ops, we couldn't create this organization</p>;
  }

  if (createOrganizationState === 'loading') {
    return <p>Creating your organization. Please Wait....</p>;
  }

  if (createOrganizationState === 'success') {
    return <p>Yay! It worked.</p>;
  }

  return (
    <OrganizationForm onSubmit={createOrganization} />
  );
}
```

You can also use the same patterns for deleting or updating a document.

### Should you use Firestore with your Next.js app?

OK, we've seen that Firestore is solid. But is it the best choice
for your application? Let's talk about this.

Many developers start using Firestore, only to meet certain obstacles along the
way: rigidity of the data model, need for full-text search, highly relational
data structures, and so on.

The above are all signs that Firestore may not have been
the best choice for your application or you as a developer (as you may
prefer relational databases, for example).

Below is my non-exhaustive checklist for choosing (or not) Firestore:

- I don't need a full-text search, OR I am ready to integrate and duplicate
data using a dedicated search engine (Algolia, ElasticSearch, MeilliSearch,
TypeSense, etc.)
- I am OK with duplicating data, and I know how and where to do so
- I don't need to make a large number of reads, or I am able
to load documents progressively (for example, using pagination)
- I need/want real-time updates
- I need/want offline persistence

## Final Words

Firestore is a robust database: easy to start with, secure, and scale.
But, at the same time, it's not always the correct choice, so it's worth remembering
if you're embarking on starting a SaaS using it.

For example, MakerKit uses Firestore extensively: while it's OK for most
applications, it won't be the perfect choice for several use-cases, and
that's fine.

If you need any help or want to know more about how we use Firestore in MakerKit,
[please reach out and let's talk](/contact).


Using Firestore with Next.js


Firebase's Firestore is a database that applications can communicate with
directly from the client-side. As a result, there are many security
considerations that developers need to take into consideration.

To help secure our databases, we can leverage Firestore's Security Rules using a
scripting language ([CEL](https://github.com/google/cel-spec)), which can be
extended using functions, not too differently from Javascript.

For both Cloud Firestore and Cloud Storage, we can use the following syntax:

```
service <<name>> {
  match <<path>> {
    // Allow the request if the following conditions are true.
    allow <<methods>> : if <<condition>>
  }
}
```

For example, for writing Cloud Firestore's root path, we'd be using the
following rules:

```
service cloud.firestore {
    match /databases/{database}/documents {
        // rules here
    }
}
```

### Document Paths
The `path` variable is the path to your Firestore document. If you specify a
path to a document, the ID of the document is defined as a variable:

```
match /organizations/{organizationId} {
    // rules here
}
```

For nested collections, we can insert additional rules within the same scope:

```
match /organizations/{organizationId} {
    match /invites/{inviteId} {

    }
}
```

### Methods
Methods will disallow any read and write by default. Writing and reading
permissions can be written in batch or granularly.

For example, we can write the following conditions:

```
match /organizations/{organizationId} {
    allow read: if canRead();
    allow write: if canWrite();
}
```

In most situations, you want to write granular conditions.

Reading documents can be split as follows:
- `list` - when we want to query a collection of documents
- `get` - when we want to query a single document

Writing a document, instead, can be split in the following ways:
- `create` - when we create a new document
- `update` - when we write to an existing document
- `delete` - when we delete an existing document

```
match /organizations/{organizationId} {
    allow list: if canList();
    allow get: if canGet();
    allow create: if canCreate();
    allow update: if canUpdate();
    allow delete: if canDelete();
}
```

#### Recursive Wildcards

If you want to apply a specific rule recursively to a deep hierarchy, we can
use the following syntax:

```
match /organizations/{organizationId=**} {
    allow read: if condition();
}
```

#### Security Rules are not filters

One important something you should notice is that **Firestore's rules are not
filters**: queries that violate the Security Rules will be rejected.

## Debugging Firestore's Security Rules using the Emulator UI

As you may know, the Firebase Emulators offer the ability to debug your
Firestore database and the queries/writes against it.

If you aren't sure how to run the emulators,
[take a look at our guide for setting up the Firebase Emulators for your
application](/blog/tutorials/setting-up-firebase-emulators-nextjs).

If you have followed the guide above, you should be able to view the
Firestore Emulator UI at
[http://localhost:4000/firestore](http://localhost:4000/firestore).

<Image
    width={2012}
    height={680}
    alt={'Firestore Emulator Debugging UI'}
    src={'/assets/images/posts/firestore-emulator-ui-debugging.png'}
/>

By clicking one of the rows, we can view and analyze the scope of the
request that the Firestore security rules have evaluated.

In certain situations, Firestore can be quirky and not fully documented, so
it can be necessary to inspect what data is available to the security rules.

You can inspect the scope of a Firestore request using the sidebar the
right-hand side after clicking on a request.

<Image
    width={1020}
    height={906}
    alt={'Firestore Emulator Debugging UI Sidebar'}
    src={'/assets/images/posts/firestore-debug-sidebar.png'}
/>

Knowing how to debug our security rules is the first but essential step to
start developing them effectively.

### Evaluating an existing document's data

When the client is executing a `write` (create, update or delete), we can access
the data of the document written passed via the request.

We can use the scoped data `request.resource` to access the document. We should use the `data` property to access the data itself.

In the image below, you can see the scope of a request that was used to
create a new Firestore document:

<Image
    width={1020}
    height={1226}
    alt={'Firestore Emulator Resource data'}
    src={'/assets/images/posts/firestore-debug-resource-data.png'}
/>

The function below is a quick way to access incoming data being written to a
Firestore document:

```
function incomingData() {
    return request.resource.data;
}
```

How to use this function? Let's write a security rule that allows us to create
a document if the document contains a field with a specific value:

```
function canCreateOrganization() {
    return incomingData().id != null;
}

service cloud.firestore {
    match /databases/{database}/documents {
        match /organizations/{organizationId} {
          allow create: if canCreateOrganization();
        }
    }
}
```

In the function above, we're checking that the `id` property of the document
exists.

### Evaluating the incoming document's data

When we're evaluating data of documents that are already in the database, we
need to use the scope `resource.data`:

```
function existingData() {
    return resource.data;
}
```

For example, let's assume the user wants to read the data from an
`organization` document, and that this document contains a map in which each
`key` is the ID of a member.

Explained: if the current user's ID is a key of
the `map` means the member belongs to the organization.

We can use the rule below:

```
match /organizations/{organizationId} {
    allow read: if userId() in existingData().members;
}
```

### Checking that the user is authenticated

The following function allows us to check that the user is authenticated.

Remember, this only means that the user is not anonymous, not that they're
authorized to perform a specific action.

```
function userId() {
    return request.auth.uid;
}

function isSignedIn() {
    return userId() != null;
}
```

### Accessing any path in Firestore

The security rule can allow us to access any path in the database by using
the correct path.

For example, knowing the user's ID (as it is passed via the `request` scope),
we could access the user record using the `get` function and the following
syntax:

```
get(/databases/$(database)/documents/users/$(userId));
```

Notice: **this will cost reads**. Every time our rule reads another document, it
will be billed as an additional read. It's a good practice to write security
rules efficiently, but sometimes it's simply impossible not to do so.

Similarly, we can use the `exists` function to check that a Firestore path
exists:

```
function userExists() {
  return exists(/databases/$(database)/documents/users/$(userId));
}
```

### Retrieve the currently signed-in user record

As we learned above, we can access paths in Firestore if we have the
data to build the paths to retrieve them.

Let's assume your application, like MakerKit, has a collection named `users`
where we store the data belonging to each user. Your Firestore's collection
name can differ, so you may need to update the snippet below.

It can be very helpful to read your current user's record to access data such
as permissions, the organizations they belong to, etc.

The functions below help you access the data regarding the currently
selected user:

```
function getUser(userId) {
    return get(/databases/$(database)/documents/users/$(userId));
}

function getCurrentUser() {
    return getUser(userId());
}
```

### Disallow writing to specific fields

The following function can prevent clients from writing the fields passed
in as strings when creating a new document. This can be useful when you want
to disallow particular writes from clients.

```
// use this function to prevent from writing certain fields
// to the document, such as sensitive data (permissions, etc.)
// create: if fieldsNotInCreateAction(["permissions"]);

function fieldsNotInCreateAction(fields) {
  return !(request.resource.data.keys().hasAll(fields));
}
```

### Disallow updates to specific fields

The following function can prevent clients from updating the fields passed
in as strings:

```
function fieldsNotInUpdateAction(fields) {
    return (fieldsNotInCreateAction(fields) && !(resource.data.keys().hasAll(fields)));
}
```

### Strictly typing writes

Firestore can also allow us to check if the fields sent by the client have
the correct data type.

The following snippet has been taken straight from the Firstore
documentation:

```
allow create: if request.resource.data.tags is list &&
  request.resource.data.tags[0] is string &&
  request.resource.data.product is map &&
  request.resource.data.product.name is string &&
  request.resource.data.product.quantity is int
  }
}
```

Of course, the best way to write long and complex logic is to split it into its
own function:

```
function canCreateReview(review) {
    return review.score is int &&
      review.headline is string &&
      review.content is string &&
      review.author_name is string &&
      review.review_date is timestamp
}

// conditions
allow create: if canCreateReview(request.resource.data);
```


Firestore

Tutorials and Guides about Firestore

Pagination with React.js and Firebase Firestore

Using Firestore in Firebase Storage Rules

Group Security with Firestore Storage and Next.js

A Data Model for your Firebase SaaS

Using Firestore with Next.js

In-depth guide to Firestore Security Rules