Tutorials

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 filename=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 filename=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 filename=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 filename=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 Ops! Error encountered while loading organization data...
 }

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

 // 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 filename=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 filename=OrganizationForm.tsx
function OrganizationForm() {
 const [
 createOrganization,
 createOrganizationState
 ] = useCreateOrganization();

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

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

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

 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 is a cloud backend platform backed by *Google Cloud*. Because it's a cloud environment, it wasn't possible to run it locally for a long time, which was rather complex and inconvenient during the development phase.

In addition, it required an Internet connection, and it was using the production services (even if it was a staging project) for just about anything, eating into the free quota available.

In 2021, Firebase finally finalized the roll-out of the Firebase Suite emulated locally. Installed as an NPM package, the `firebase-tools` library allows us to spin up the emulator for each part of the Firebase Stack:

- Authentication
- Firestore
- RealTime DB
- Hosting
- Cloud Functions
- Cloud Storage
- Cloud PubSub

Furthermore, the Firebase Emulators come with a UI console similar to the actual Firebase Console, although much more limited.

This blog post explains how to set up the Firebase Emulators locally and integrate them into a Next.js application using `reactfire`, the official Firebase package for React.

If you haven't created a Next.js application already, please run the following command:

```bash
npx create-next-app@latest --ts
# or
yarn create next-app --ts
```

## Installing the Firebase Tools package

First, we need to install the `firebase-tools` package for NodeJS. It's the Firebase CLI, which we can use for various tasks:

- switching projects
- install and run the emulators
- deploy the project

To install it in your existing Next.js project, please run the following command in your terminal, which installs the package globally:

```
npm i firebase-tools -g
```

In addition, please install the following NPM dependencies, handy to work with React and Firebase:

```
npm i -d reactfire firebase
```

## Installing the Firebase Emulators

If you haven't created a Firebase project yet, please run the following command to initialize it:

```
firebase init
```

The command above should return the following output:

<Image src='/assets/images/posts/firebase-init.webp' width='1894' height='936'/>

We recommend choosing the following options:

- Emulators
- Firestore
- Storage

Afterward, you can choose to create a new project, choose an existing one, or neither of them:

<Image src='/assets/images/posts/choose-firebase-project.webp' width='1468'
 height='560'/>

You are not required to create a project unless you use the Storage emulators.

The CLI should output the emulators you want to install: if you're unsure which ones you want, select them all except for Realtime DB and Cloud Functions. As you're using NextJS, we assume you want to use Vercel's API functions:

<Image src='/assets/images/posts/emulators-setup.webp' width='1474'
 height='478'/>

Finally, choose the ports assigned to each emulator and download the emulators. If you choose a port different from the default one, remember to update the Next.js environment variable we define in the next section.

<Image src='/assets/images/posts/ports-setup.webp' width='1472' height='534'/>

#### In case you have not yet created a Firebase project

If you have opted to start without creating a Firebase project, make sure to add a default project to your `.firebaserc` file, even if it is non-existent yet.

Afterward, open `.firebaserc` and paste the following content:

```json filename=.firebaserc
{
 "projects": {
 "default": "ultimate-guide-auth-firebase-next"
 }
}
```

NB: make sure to update the default project when you create one.

#### After the Installation Completes

After this command completes, your project is going to have the following files generated for you:

```bash
- .firebaserc
- firebase.json
- firestore.rules
- firestore.indexes.json
```

NB: if you are running the Storage Emulators, **Firebase does require you to select a project**.

## Adding the Emulators to the Next.js App

We can now configure our Next.js application to use the Emulators instead of the production Firebase services as we have the emulators installed.

We add the emulators' host and ports to the Next.js environment file. Do not use a production `.env` file, but ideally use the local one (for example, `.env` or `.env.local`):

```bash filename=.env.development
NEXT_PUBLIC_FIREBASE_EMULATOR_HOST=localhost
NEXT_PUBLIC_EMULATOR=true
NEXT_PUBLIC_FIRESTORE_EMULATOR_PORT=8080
NEXT_PUBLIC_FIREBASE_AUTH_EMULATOR_PORT=9099
NEXT_PUBLIC_FIREBASE_STORAGE_EMULATOR_PORT=9199
```

Because we prefixed the environment variables with `NEXT_PUBLIC_`, Webpack compiles and adds these to the final client-side bundle.

Make sure you choose the exact emulator ports we defined when installing the emulators. If you have not changed the default ports, you're all set!

### Running the Emulators

To run the Firebase Emulators, we suggest creating a new NPM script that runs the following command:

```json filename=package.json
{
 "scripts": {
 "firebase:emulators:start": "firebase emulators:start"
 }
}
```

Assuming everything went well, you should see the output below:

<Image
 src='/assets/images/posts/running-firebase-emulators.webp'
 width='1438'
 height='920'
/>

Yay! You did it!

#### Importing an Emulator Snapshot

To import a snapshot of the state, we need to add the parameter `import`:

```
firebase emulators:start --import ./firebase-seed
```

You can change the directory path to something else if you want to.

#### Exporting the current Emulator snapshot

To export the current emulator's snapshot, we can add and run the following command:

```json filename=package.json
{
 "scripts": {
 "firebase:emulators:export": "firebase emulators:export ./firebase-seed"
 }
}
```

### Adding the Auth Emulator

To add the `auth` emulator, we can import the *function* `connectAuthEmulator` from the package `firebase/auth`.

Let's create a component that connects to the Auth emulators and makes the SDK available to all its children:

```tsx filename=FirebaseAuthProvider.tsx
import React, { useEffect } from 'react';
import { AuthProvider, useAuth, useFirebaseApp } from 'reactfire';

import {
 initializeAuth,
 indexedDBLocalPersistence,
 connectAuthEmulator,
 inMemoryPersistence,
} from 'firebase/auth';

function getAuthEmulatorHost() {
 // we can access these variables
 // because they are prefixed with "NEXT_PUBLIC_"
 const host = process.env.NEXT_PUBLIC_FIREBASE_EMULATOR_HOST;
 const port = process.env.NEXT_PUBLIC_FIREBASE_AUTH_EMULATOR_PORT;

 return ['http://', host, ':', port].join('');
}

function isBrowser() {
 return typeof window !== 'undefined';
}

export default function FirebaseAuthProvider({
 children,
}: React.PropsWithChildren) {
 const app = useFirebaseApp();

 // make sure we're not using IndexedDB when SSR
 // as it is only supported on browser environments
 const persistence = isBrowser()
 ? indexedDBLocalPersistence
 : inMemoryPersistence;

 const sdk = initializeAuth(app, { persistence });

 const shouldConnectEmulator =
 process.env.NEXT_PUBLIC_EMULATOR ==='true';

 if (shouldConnectEmulator) {
 const host = getAuthEmulatorHost();

 connectAuthEmulator(sdk, host);
 }

 return (
 <>
 {children}
 </>
 );
}
```

Whenever we want to use the Firebase Auth SDK within our application, we will need to wrap the page with the component defined above:

```tsx filename=page-with-auth/index.tsx
const PageWithAuth = () => {
 return (
 <FirebaseAuthProvider>
 {
 // your page goes here
 }
 </FirebaseAuthProvider>
 );
};

export default PageWithAuth;
```

Are you looking for an example containing the code above? We got you sorted. [The full source code is available on Github](https://github.com/makerkit/ultimate-firebase-nextjs-authentication-guide): it's an open-source codebase with a fully functioning Authentication system with Firebase and Next.js. Feel free to clone, extend and share it as much as you wish!

Check out our [Ultimate Authentication Guide with Next.js and Firebase](/blog/tutorials/ultimate-guide-authentication-firebase-nextjs) that explains in detail how we built the example above.

next

Using Firestore with Next.js

Setting Up the Firebase Emulators with Next.js

The Ultimate Authentication Guide with Next.js and Firebase