SaaS


Firebase and Supabase are two of the most popular backend-as-a-service (BaaS) platforms. While at Makerkit we started by using Firebase for our original SaaS kit, we are now also working to support SaaS kits based on Supabase.

In this article, we will compare Firebase vs Supabase to help you decide which one is better for your next project, so you can choose the right kit for your needs.

---

Makerkit is a SaaS boilerplate to build a SaaS using Firebase or Supabase. It's a complete solution that includes a landing page, a dashboard, and a billing system. It's built with React, Next.js or Remix, Tailwind CSS, and TypeScript.

## What is Firebase?

Firebase is a BaaS platform that provides a set of tools and services to help you build and run your app. It is developed by Google and is one of the most popular BaaS platforms.

Firebase offers a wide range of services, including:
- Authentication
- Realtime Database / Firestore
- Storage
- Hosting
- Cloud Functions
- Cloud Messaging
- Performance Monitoring
- Remote Config
- Analytics

## What is Supabase?

Supabase is an open-source alternative to Firebase. It is a BaaS platform that provides a set of tools and services to help you build and run your app. It's backed by YC and Mozilla and is one of the fastest-growing BaaS platforms.

Supabase also offers a wide range of services, including:
- Authentication
- Realtime Database / Postgres
- Storage
- Functions

## Features

When it comes to features, it's clear that Firebase has the upper hand, as it offers more services than Supabase.

However, Supabase is catching up fast and is adding new features regularly. It's also worth noting that many Firebase services only work for mobile apps, such as Crashlytics, ML, Dynamic Links, and others.

If you're building a web app, **Firebase and Supabase will offer you a similar set of features**.

## Authentication

Firebase and Supabase both offer complete authentication services that offer a variety of authentication methods, including email/password, phone, magic link, Google, Facebook, Twitter, and GitHub.

Firebase also offers anonymous authentication, which is not available in Supabase. This can be useful if you want to allow users to use your app without signing up.

There isn't a large difference Firebase and Supabase when it comes to authentication. Both platforms offer an exceptional set of features and are easy to use.

## Database

Firebase offers two database options: Realtime Database and Firestore. Realtime Database is a NoSQL database that stores data in JSON format. Firestore is a document-based database that stores data in JSON format.

### Firestore DB
Firestore allows us to write and read data directly from the clients without having to write any server code by writing security rules.

### Supabase Postgres

Supabase offers a managed Postgres database.

Postgres is one of the most popular and battle-tested relational databases that stores data in tables.

Supabase also supports client-side reads and writes by allowing developers to protect their database using Postgres Row Level Security (RLS): these rules allow us to control who can read and write data using SQL.

## Firestore vs Postgres

Firestore and Postgres are two different types of databases. Firestore is a document-based database that stores data in JSON format. Postgres is a relational database that stores data in tables.

I would recommend using Firestore if you're not experienced with SQL and relational databases. Firestore is simpler to use, and most importantly easier to secure: Firestore security rules are arguably much simpler than Postgres RLS.

However, if you're experienced with SQL and relational databases, then Postgres is the better option. Postgres is a battle-tested database that is used by many large companies, allows us to write complex queries, can allow us to use full-text search, and is better when it comes to data integrity.

Simply speaking, Firestore is **better for beginners**, and Postgres is **better for experienced developers** who have already worked with Postgres and SQL.

This does not mean Firestore is not a good option for experienced developers: if your data structure is valid for NoSQL and you don't need to write complex queries, then Firestore is a great option.

### Realtime

Firebase and Supabase both offer realtime database services, but there are differences worth noting.

#### Firebase Firestore Realtime Database

Firebase's realtime queries allow us to listen to changes in the database and receive updates in real-time: the updates include the full snapshot of our query.

The ability to receive real-time snapshots of a query is incredibly useful since we don't need to write any client-side code to manage state and reconcile changes.

The UI will automatically reflect the changes in the database using the snapshot from the realtime query.

#### Supabase Postgres Realtime Database

Supabase's realtime works differently, and it's not as straightforward as Firebase's realtime queries.

It uses a pub/sub system that allows us to listen to changes in the database and receive updates in real-time. Updates do not return the current snapshot of the original query, but rather they indicate what changed in the database. This means that we need to write client-side code to manage the state and reconcile changes.

The UI will not automatically reflect the changes in the database, but we need to write code to update the UI.

When it comes to real-time changes, Firebase is the clear winner.

## Self Hosting

Many developers may want to self-host their app, be it for security reasons or scalability.

When it comes to self-hosting, the answer is simple: **Firebase does not allow us to self-host** our app, while **Supabase does**.

If self-hosting is important to you, then Supabase is the better option.

## Local Development

Firebase and Supabase both offer a local development environment that allows us to run our app locally. This is incredibly useful since we can test our app locally before deploying it to production.

Firebase offers a local emulator that allows us to run the Firebase services locally: it's a bit of a black box, and we cannot see what's happening under the hood. It works fairly well though, and it's feature-complete these days.

Supabase allows us to run a self-hosted instance locally using Docker. It still lacks some features but is getting better every day.

Both services offer a local development Admin UI.

## SDK

Firebase and Supabase both offer a complete set of SDKs. Generally speaking, they're both very valid options.

Firebase's SDK is more mature and has more features. It's split into multiple packages for each feature. This was necessary so that we could tree-shake the library and reduce the bundle size.

Supabase's SDK, instead, has a much smaller API surface, it's more lightweight and simpler to use.

### Isomorphic SDK

Firebase's SDK is split between Client SDK and Admin SDK. When we use the SDK in our API functions, or when server-side rendering, we cannot use the client SDK, but we're constrained to use the Admin SDK.

This has a lot of disadvantages, especially when it comes to server-side rendering (SSR): in fact, we are forced to write separate queries for the client and the server, and we cannot use the same query for both. This leads to more code and more complexity.

Instead, the Supabase client SDK is isomorphic, which means that we can use the same SDK both on the client and on the server. This allows us to write less code and have a simpler architecture.

### Edge Environments

Supabase has a clear advantage over the Firebase SDK: in fact, it can be used in edge environments, such as Cloudflare Workers and Deno. Instead, Firebase's SDK is only available for Node.js and the browser.

What does it mean? It means that by allowing us to use Supabase in edge environments, we can use Supabase to build serverless applications that run on the edge. This can unlock incredibly fast performance and reduce costs.

### SDK: which one is the winner?

While the Firebase SDK is more mature and has more features, the Supabase SDK is more lightweight and simpler to use. Additionally, it allows us to use the same SDK both on the client and on the server and in edge environments which is a huge advantage.

Personally speaking, I prefer the Supabase SDK.

## Conclusion

Firebase and Supabase are both great BaaS platforms. They both offer a complete set of features and are easy to use. Ultimately, since they offer a similar set of features, the choice between Firebase and Supabase will depend on your use case, your preferences, and your experience.

### When to use Firebase

Here are some examples of use cases where Firebase is a better option:

- If you're building a mobile app, Firebase offers more features than Supabase
- If you're a beginner and you're not familiar with SQL and relational databases, Firestore is a better option than Postgres
- If you prefer not to manage client-side state and rely on real-time features to automatically update the UI, Firebase is a better option than Supabase
- If you prefer to use a more hands-off service, Firebase is a better option than Supabase

### When to use Supabase

Here are some examples of use cases where Supabase is a better option:

- If you want to use Postgres and leverage better data integrity, more complex queries, and full-text search, Supabase is a better option than Firestore
- If you want to use the same SDK both on the client and on the server, Supabase is a better option than Firebase
- If you want to use Supabase in edge environments, Supabase is a better option than Firebase
- If you want to self-host your BaaS, Supabase is a better option than Firebase
- If you want to use a BaaS that is open-source and transparent, Supabase is a better option than Firebase


Firebase vs Supabase: Which one is better for your next project?

Tutorials


During the 2022 Firebase Submit, the Firebase team released a huge new feature for Firestore: `count aggregations`.

Thanks to `count` aggregations, we can query the total number of
documents in a Firestore collection.

To do so, 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.

## A Custom React hook to fetch the documents count from Firestore

In the example, below, we use React.js and Firebase to fetch the number of
documents contained in our Firestore collection `tasks`:

```tsx
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;
```

Now that we have a React hook that returns a function to fetch the number of
documents from the collection, we can use this custom hook in one of our
components and render the result:

```tsx
function TasksCollectionCount(
  props: React.PropsWithChildren<{
    organizationId: string
}>) {
  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 <p>Loading count...</p>;
  }

  return <div>Tasks ({ tasksCount })</div>;
}
```

Great, we can now display how many tasks are in our `tasks` collection for
the organization.

## Billing for Firestore Count Aggregations

When you query aggregated data using the count aggregations, every 1000
documents counted will count as 1 document read.


Counting a collection's documents with Firebase Firestore


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


If you are building a new SaaS and only want to make your service available to small batches of users, you may wish to allow signups but restrict users who can sign into your application.

Thanks to [Firebase Auth Blocking Functions](/blog/tutorials/blocking-authentication-firebase-auth), this has become a much easier task than in the past. In this article, we want to show you how to create a waitlist that allows users to sign up but restricts those who can sign in in batches of users.

This post assumes you have a working authentication implementation with Firebase and Next.js.

This is the (straightforward) strategy we will use:

1. We define a `beforeCreate` function: on sign-up, we add users to a collection `waitlist`: we will store the user ID and the timestamp when they signed up
2. We define a max timestamp where users that signed in before the timestamp will be allowed to sign in
3. We define a `beforeSignIn` function: on sign-in, we verify that the user signed up before the `timestamp` constant we defined

## Adding users to a Waitlist Collection

When users sign-up, we add them to a collection we name `waitlist`: in this collection's documents, we will store the user's ID and the timestamp when they signed up.

The logic is the following:
- allow users that signed up before `timestamp` to sign in and use the application. `timestamp` is defined as a hard-coded timestamp, but of course, you can apply logic as complex as you feel like.

```ts title="src/functions/index.ts"
import { auth } from 'firebase-functions';
import { getFirestore } from 'firebase-admin/firestore';

export const onSignUp = auth.user().beforeCreate(async (user) => {
  const collection = await getWaitlistCollection();

  await collection.add({
    userId: user.uid,
    timestamp: new Date().getTime(),
  });
});

async function getWaitlistCollection() {
  await initializeFirebaseAdminApp();

  const firestore = getFirestore();
  return firestore.collection(`waitlist`);
}
```

Initially, we may want to fully disable sign-ins:

```ts
export const onSignIn = auth.user().beforeSignIn( ({ uid }) => {
  throw new auth.HttpsError('invalid-argument', `Unauthorized user`);
});
```

## Verifying Users signed in before timestamp cutoff

When it's time to allow users to sign in, we can implement the following logic:

1. Retrieve the user record in the waitlist
2. Compare the max timestamp cutoff with the record's `timestamp` property
3. Reject sign-in if the record's `timestamp` property is greater than the cutoff time

```ts
// Thu Oct 06 2022 19:51:58 GMT+0200 (Central European Summer Time)
const ALLOWED_MAX_TIMESTAMP = 1665078710248;

export const onSignIn = auth.user().beforeSignIn(async ({ uid }) => {
  const collection = await getWaitlistCollection();
  const docRef = await collection.where('userId', '==', uid).get();
  const doc = docRef.docs[0]?.data();

  if (!doc) {
    throw new auth.HttpsError('invalid-argument', `Unauthorized user`);
  }

  if (doc.timestamp > ALLOWED_MAX_TIMESTAMP) {
    throw new auth.HttpsError('invalid-argument', `Unauthorized user`);
  }
});
```

Of course, remember to handle the errors on your client-side components.

And that's it! If you need help with the above, feel free to reach out or join our [Discord Community](https://discord.gg/BeJSyQJ6jP)!.

Creating a Waitlist with Firebase Auth


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


While being a less-known authentication method, Email Links are a great way to allow users to sign in to your application. It's easy and simple to use, and Firebase offers full support for it.

In this post, we will learn how to implement Email Link authentication in any Next.js application with Firebase Auth.

In this post, we assume you already have a bare-bone Next.js codebase with `reactfire` installed and the basic Firebase setup.

<Alert type='info'>
  Some of the code below contains references to components and utilities contained in the Makerkit SaaS Boilerplate
</Alert>

## Creating a Form to send an Email Link

First, we want to create a form in our authentication pages that can read an email address and generate an email link.

Here is what we will do:

1. Create a simple form that takes an email address
2. When submitted, we generate the link using the `sendSignInLinkToEmail` function from `firebase/auth`, and save the email in `localStorage`

```tsx title="EmailLinkAuth.tsx"
const EmailLinkAuth: React.FC = () => {
  const auth = useAuth();
  const { state, setLoading, setData, setError } = useRequestState<void>();

  const onSubmit: FormEventHandler<HTMLFormElement> = useCallback(
    async (event) => {
      event.preventDefault();

      // read the email field of the form
      const target = event.currentTarget;
      const data = new FormData(target);
      const email = data.get('email') as string;

      setLoading(true);

      // set up return URL (where we will redirect the user)
      const settings = {
        url: getAuthUrl(),
        handleCodeInApp: true,
      };

      try {
        // send sign in link
        await sendSignInLinkToEmail(
          auth, 
          email, 
          settings
        );

        // save email in storage, so we can compare 
        // it when the user uses the link from the email
        storeEmailInStorage(email);

        // success (turns state.success to "true")
        setData();
      } catch (error) {
         setError(error);
      }
    },
    [auth, setData, setError, setLoading]
  );
  
  { /* SUCCESS! */ }
  if (state.success) {
    return (
      <span>
        Yay, link successfully sent!
      </span>
    );
  }

  return (
    <form className={'w-full'} onSubmit={onSubmit}>
      <div className={'flex flex-col space-y-2'}>
        <TextField>
          <TextField.Label>
            Email Address

            <TextField.Input
              data-cy={'email-input'}
              required
              type="email"
              placeholder={'your@email.com'}
              name={'email'}
            />
          </TextField.Label>
        </TextField>

        <Button loading={state.loading}>
          <If
            condition={state.loading}
            fallback={<>Send Email Link</>}
          >
            Sending Email Link...
          </If>
        </Button>
      </div>

      <If condition={state.error}>
        <span>
          Sorry, we encountered an error
        </span>
      </If>
    </form>
  );
};

function getAuthUrl() {
  const origin = window.location.origin;
  const path = '/auth/link';

  return [origin, path].join('');
}

function storeEmailInStorage(email: string) {
  window.localStorage.setItem('emailForSignIn', email);
}

export default EmailLinkAuth;
```

When using the Firebase Auth emulator, the link will be printed to the console that is running the emulators.

Now, we have to create the `/auth/link` page component, in which we will verify the code and, if successful, sign the user in.

## Creating the Email Link page component

As said before, we create this page at `/auth/link`.

Before being able to sign the user in, we're going to do a couple of checks:

1. first, we use the Firebase function `isSignInWithEmailLink` to verify we're using the Email Link authentication method
2. secondly, we verify we're able to retrieve the email address used to receive the link
3. then, we sign the user in using the function `signInWithEmailLink`
4. if successful, we delete the email from local storage and redirect the user to the application
5. whenever we cannot sign the user in, we display the users an error

```tsx
const EmailLinkAuthPage: React.FC = () => {
  const auth = useAuth();
  const router = useRouter();
  const requestExecutedRef = useRef<boolean>();
  const { state, setError } = useRequestState<void>();

  const redirectToAppHome = useCallback(() => {
    return router.push(appHome);
  }, [router]);

  // in this effect, we execute the functions to log the user in
  useEffect(() => {
    // let's prevent duplicate calls (which should only happen in dev mode)
    if (requestExecutedRef.current) {
      return;
    }

    const href = getOriginHref();

    // do not run on the server
    if (!href) {
      setError('generic');

      return;
    }

    // let's verify the auth method is email link
    if (!isSignInWithEmailLink(auth, href)) {
      setError('generic');

      return;
    }

    const email = getStorageEmail();

    // let's get email used to get the link
    if (!email) {
      setError('generic');

      return;
    }

    void (async () => {
      requestExecutedRef.current = true;

      try {
        // sign in with link, and retrieve the ID Token
        await signInWithEmailLink(auth, email, href);

        // let's clear the email from the storage
        clearEmailFromStorage();

        // redirect user to the home page
        await redirectToAppHome();
      } catch (e) {
        if (e instanceof FirebaseError) {
          setError(e.code);
        } else {
          setError('generic');
        }
      }
    })();
  }, [
    auth,
    loading,
    redirectToAppHome,
    setError,
  ]);

  return (
    <Layout>
      <If condition={loading}>
        Signing in...
      </If>

      <If condition={state.error}>
        <div className={'flex flex-col space-y-2'}>
          { state.error }
        </div>
      </If>
    </Layout>
  );
};

function getStorageEmail() {
  if (!isBrowser()) {
    return;
  }

  return window.localStorage.getItem(EMAIL_LOCAL_STORAGE_KEY);
}

function clearEmailFromStorage() {
  window.localStorage.removeItem(EMAIL_LOCAL_STORAGE_KEY);
}

function getOriginHref() {
  if (!isBrowser()) {
    return;
  }

  return window.location.href;
}

export default EmailLinkAuthPage;
```

🎉 And that's it! This is all you need to create a sound email authentication flow with Firebase Auth and Next.js.

Email Link Authentication with Firebase and Next.js


This blog is a summary of the documentation to get started with the Next.js + Firebase boilerplate project quickly and smoothly.

### System Requirements

To get started, you must install Node.js and Git on your system.

If these are already installed, we only recommend you install the Firebase Tools globally using the following command:

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

### Cloning the repository

If you have access to the MakerKit private team, you can fetch the repository from Git using the following command and by replacing `your-saas-app` with the name you prefer:

```
git clone --depth=1 https://github.com/makerkit/next-firebase-saas-kit your-saas-app
```

If you have purchased from Gumroad, you may not yet have access to the team. In that case, simply install the packages and wait for us to add you to the private team on GitHub.

Now, let's get in the folder and install the Node packages using `npm`:

```
cd your-saas-app
npm i
```

To test that everything works, let's run the following commands in two separate terminals (or, better, using your IDE).

#### Running the Next.js server in development mode

```
npm run dev
```

#### Running the Firebase Emulators

```
npm run firebase:emulators:start
```

If everything goes well, you should be able to open the application at [http://localhost:3000](http://localhost:3000).

#### Running the Stripe CLI

Additionally, if you want to run Stripe locally (e.g. sending webhooks to your local server), you will also need to run the following command:

```
npm run stripe:listen
```

The above command runs the Stripe CLI and will route webhooks coming from Stripe to your local endpoint. For example, in the Makerkit starter, this endpoint is `/api/stripe/webhook.`

When running the command, it will print a webhook key used to sign the messages from Stripe. You will need to add this key to your local environment variables file as below:

```
STRIPE_WEBHOOK_SECRET=<KEY>
```

The webhook printed should not change, so you may only need to do this the first time.

##### Yep, no more configuration needed!

As you may have noticed, we required no configuration changes. This is for two reasons:

1. We're using a "demo" project. Any project that starts with `demo-` will never be treated as an actual project by the Firebase tooling
2. Some of the environment variables (API key and APP ID) are pasted from another Makerkit's project, but we invite you to change these as soon as you create a project. This is done so you can get started as quick as possible.

## Screens and Functionalities

Let's take a look at each screen of the boilerplate and its functionalities.

Generally, we split the application into two parts:
1. The **public marketing website**, containing:
  - the landing page, FAQ, pricing and contact pages
  - the blog
  - the documentation
2. The **application**, only accessible via authentication:
  - the dashboard (or home page of the "app")
  - the settings pages
  - any other protected page you will create

Additionally, we have **the authentication pages**, that sit a bit in the middle between the two layers, such as:
  - the sign-in page
  - the sign-up page
  - the reset password page
  - the accept invite page

<Image src="/assets/images/docs/makerkit-codebase.webp" width="2429" height="1719" />

### Landing Page

At the time of writing, the landing page will be fairly simple and empty, and it's by design: we bet you will want to make many changes.

<Image src="/assets/images/posts/landing-page-next-fire.webp" width="2514" height="1650" />

As you may have noticed, you can toggle the dark theme using the moon icon in the header.

### Blog and Documentation

The boilerplate's blog and documentation pages are both accessible from the marketing site's header.

<Video src="/assets/images/docs/blog.mp4" />

#### Adding a Blog Post

The MakerKit's blog posts use MDX. To write a blog post:

1. create a specific "collection" or "category" by adding a `json` file at `_collections/filename.json`. Use the existing collection as an example.
2. add an MDX file at `_posts`, and fill the matter to make the post valid. The boilerplate has an example, so you can simply copy the same metadata to quickly get started.

Remember to:

1. **Restart the Next.js server** command when adding a new file
2. **Refresh the page** to pick up changes as hot reload does not work

#### Adding a new documentation page

The documentation works very similarly to the blog. In the documentation we have `topics` and `pages`:

```
_docs
  [topic]
    [page]
```

Every `topic` folder needs to have a `meta.json` file, with the following content:

```json
{
  "title": "Topic Title",
  "position": 0,
  "description": "Description"
}
```

While `title` and `description` are self-explanatory, you should be aware that the `position` property is needed to place the topic at the correct position within the documentation.

Instead, pages need to have the following matter metadata:

```
---
title: Page Title
label: Page Label within the sidebar tree
position: 0
description: Description
---
```

For each page, and similarly to the topics, you have to specify the page's position.

<Video src="/assets/images/docs/docs.mp4" />

### Authentication

At the time of writing, the Makerkit's SaaS boilerplate supports authentication via email/password or third-party providers supported by Firebase Authentication.

#### Signing Up

By navigating to `/auth/sign-up`, users will be able to sign up to the application.

<Image src="/assets/images/posts/walkthrough-sign-up.webp" width="2276" height="1764" />

#### Onboarding

The first time the user signs up, they will be redirected to the onboarding page: here is where you can ask for useful information and set up the user's organization and account.

By default, Makerkit's only asks for the name of the organization the user is creating. In fact, a user needs to belong to an organization.

<Image src="/assets/images/posts/walkthrough-onboarding.webp" width="2248" height="1748" />

Once submitted the form, the user will be brought to the home page of the application, which in the Makerkit's starter is `/dashboard`, but that you can easily configure from the application's configuration.

#### Signing In

By navigating to `/auth/sign-in`, users will be able to sign in to the application.

<Image src="/assets/images/docs/auth-sign-in.webp" width="2286" height="1894" />

### Application Home Page

The home page of the application, by default, is at `/dashboard`. This is easily configurable in the application's configuration.

<Image src="/assets/images/posts/walkthrough-dashboard.webp" width="2252" height="1750" />

### Creating and Switching Organizations

Organizations (or groups of users) are central to any SaaS application. The starter allows users to belong to multiple projects, create more projects and switch between projects on all the internal pages.

Switching and creating organizations happens through a dropdown, which can be found either in the sidebar (if using the sidebar layout) on in the application header (if using the top-navigation header).

<Video src="/assets/images/posts/create-change-organization.mp4" />

### Application Settings

Much of the logic and complexity of the boilerplate is in its settings, as **this is the part that overlaps the most between SaaS applications**.

#### Update Profile

The Update Profile Page allows your users to update their profiles. For example, they'll be able to update their name, profile photo, and if they signed up by email, also their email and password.

<Video src="/assets/images/posts/update-profile.mp4" />

#### Update Organization

The Update Organization Page allows your users to update their organizations, depending on their role. For example, by default, they'll be able to update the organization's name and logo.

<Video src="/assets/images/posts/update-organization.mp4" />

#### Organization Members

The organization members page lists the current members, and the invited members, and allows users to perform certain actions such as deleting an invite, removing users, and changing a user's role.

<Image src="/assets/images/posts/walkthrough-members-page.webp" width="2266" height="1746" />

<Alert type='info'>
  From now on, we will update the layout of the application by switching from Sidebar to TopHeader.
</Alert>

#### Inviting Members

When clicking on "Invite Members", the user is redirected to the form below, from which users can add many members at once:

<Image src="/assets/images/posts/invite-member-page.webp" width="2266" height="1746" />

When the user is invited, it gets added to the list:

<Video src="/assets/images/posts/inviting-user.mp4" />

##### Testing Emails with Ethereal

During development, emails are sent to [Ethereal accounts](https://ethereal.email).

You can create an account and set the environment variables to use always the same account. Alternatively, a testing account will be created on the fly, and you will need to log in using the credentials logged in the console.

To set a fixed Ethereal account:
1. Create an account, get the credentials
2. Add the credentials to the `.env.development` file using the variables `ETHEREAL_EMAIL` and `ETHEREAL_PASSWORD`.

Alternatively, you will find your testing account details in the console:

<Image src="/assets/images/posts/ethereal-console-log.webp" width="1620" height="856" />

#### Accepting an Invite

In the image below, we logged in Ethereal to retrieve the email sent to the user. From here we can copy the link and navigate to it.

<Image src="/assets/images/posts/walkthrough-accept-ethereal-invite.webp" width="2328" height="1328" />

As you can imagine, we can encounter two situations:

1. users are already signed-in when clicking on the link
2. users do not have an account and therefore are not signed-in

#### Users accepting invitations who are logged out

This is the more straightforward scenario: the user doesn't have an account and is signed out, therefore can choose their credentials and sign-up.

<Image width="2262" height="1754" src="/assets/images/posts/accept-invited-non-signed-in.webp" />

#### Users accepting invitations who are logged in

This is a more complex scenario, because the user may inadvertently accept the invite with the currently signed-in account. Instead, they may want to use a different account based on the invite.

In this case, we explicitly clarify which account the user is accepting the invite with, and offer the possibility to sign out if they wanted to use another one:

<Image width="2276" height="1758" src="/assets/images/posts/accept-invite-as-signed-in.webp" />

### Stripe Subscriptions and Payments

Makerkit allows setting up Stripe with ease to collect payments from your SaaS users. To do so, users can visit the `Subscriptions` page from the `Settings`.

#### Setting up a plan selector

Assuming you have already subscribed to Stripe, and have created `prices` and `products` in Stripe, you can create an automatic plan selector by adding your prices to the Makerkit configuration. At the time of writing, this is fairly basic, but it gives you an idea of how to expand it to suit your needs.

First, we add the plans to the `./configuration.ts` file. In the example below, we add two plans: Basic and Pro.

```tsx
plans: [
  {
    name: 'Basic',
    description: 'Unlimited applications and 2-hour onboarding session',
    price: '$249/year',
    stripePriceId: '',
  },
  {
    name: 'Pro',
    description: 'Unlimited applications and a full-day onboarding session',
    price: '$999/year',
    stripePriceId: '',
  },
],
```

Of course, you'll need to make sure you update the correct `stripePriceId` that you can find in your Stripe console.

When choosing a plan, the checkout button will take the user to the Stripe Checkout Portal, which is Stripe's hosted portal where users can safely pay for your SaaS' services.

<Video src="/assets/images/docs/subscribe-plan-2.mp4" />

Once the user subscribed to a plan, they will also be able to manage their billing and invoices using the Stripe Billing Portal. Additionally, they can unsubscribe from the plan they chose:

<Video src="/assets/images/docs/unsubscribe-plan-2.mp4" />

## Personalization

There are a few things you may want to update when starting your project:

1. Updating the package.json references to Makerkit
2. Updating the logo `LogoImage.tsx` and the favicon with your own
3. Updating the Tailwind theme colors

The first two points are very straightforward, so we'll discuss the third one.

### Updating the Tailwind colors

By updating the Tailwind theme, you will be able to give your project its own look & feel. To do so, we will open the Tailwind configuration at `tailwind.config.js` and update the colors.

The Starter extends the colors with two new types: `primary` and `black` (in my opinion, a nicer shade of blacks).

What you will want to change is `primary`. To do so, pick the main color of your theme, and use this [Material colors palette generator](http://mcg.mbitson.com/) to automatically generate a palette of colors.

Once chosen the main color, you can copy the colors by using the "View Code" button and then choosing "Material UI Next (React)", which returns a nice JSON configuration ready to be pasted.

Finally, simply replace the Makerkit's colors with the ones from the palette you generated.

## Conclusion

This walkthrough helps you get started with the Next.js + Firebase boilerplate and introduces the main features that the project provides.

If you have any questions, do not hesitate to [contact us](/contact)!


Walkthrough: Starting a Makerkit project with Firebase and Next.js


Firebase AppCheck is a service provided by Firebase to protect websites against bad actors, such as spammy users or automated bots. 

Under the hood, Firebase AppCheck uses *Google Recaptcha v3*, an automated version of the popular quizzes that can detect bad actors without the need of completing a quiz. In fact, **Recaptcha v3 works in the background, and never interrupts the user**.

The service is free and helps us protect Firebase Authentication, Firebase Storage, Firebase Firestore and any custom API against threats and disallowed usage of your service.

Obviously, this all sounds great and will surely help you sleep better at night. With that said, you should remember to take into account the implications of using this library, both in terms of bundle size and for your users' privacy. This is why Makerkit disables Firebase AppCheck by default but allows you to easily opt in.

## Registering your website for Recaptcha v3

[To register your website for Recaptcha v3, you need to complete the linked form](https://www.google.com/recaptcha/admin/create). After finishing entering the details, you'll be provided with a `Site Key` which we use to initialize the Firebase AppCheck service.

<Image src="/assets/images/posts/create-recaptchha-key.webp" width="1494" height="878" />

NB: when registering the website, make sure to create a **Recaptcha v3** key, not v2.

After submitting the form, you will receive two keys: 

1. a public key (on the client-side)
2. a private key (to be used on the server side)

Save the public key and add it to your Next.js `.env` file:

```
NEXT_PUBLIC_APPCHECK_KEY=<YOUR_KEY>
```

## Enabling Firebase App Check from the console

First, we need to enable Firebase App Check from the Firebase Console to register our application using the keys we have generated in the previous step.

<Image src="/assets/images/posts/register-app-check.webp" width="2850" height="902" />

Above, you should have added the secret key that we have generated. If it all went well, you have successfully enabled app-check for your application 🎉!

### Enforcing Firestore to use App Check

To enforce Firestore to always validate requests using AppCheck, you will have to enable it from the Console. From where you are, click on the `API` tab, then click on `Firebase Firestore`. You will then be presented with the popup as in the image below:

<Image src="/assets/images/posts/enforce-appcheck-firestore.webp" width="1752" height="1340" />

Continue and enforce Firestore to use AppCheck.

### Adding Debug Tokens during development

Debug Tokens allow us to use App Check while working in a local development environment or while running automated tests in a CI.

Debug Tokens work well when you're running a Firebase project with real credentials. Instead, if you're running a development project with a `demo-` prefix, it will not work. These projects require little to no configuration, so they're ideal to get started, but not for testing Firebase's real services.

To create a Firebase Debug Token, click on the registered application menu, and you should then see the window as in the image below:

<Image src="/assets/images/posts/appcheck-debug-tokens.webp" width="2326" height="1080" />

Once created, copy the debug token and add it as an environment variable to your application:

```
NEXT_PUBLIC_APPCHECK_DEBUG_TOKEN=<YOUR_DEBUG_TOKEN>
```

## Adding Firebase AppCheck to your Next.js App

It's now time to add the Firebase AppCheck library to our Next.js application, so we can protect it from abuse. To initialize Firebase AppCheck we will use `reactfire`, the official Firebase library for React applications.

Assuming you already created a Next.js application, ensure to install `Reactfire` and initialize your Firebase application.

### Creating the FirebaseAppCheckProvider component

Then, we create a component named `FirebaseAppCheckProvider`, responsible for:

1. retrieving the site key constant `appCheckSiteKey` from the application's configuration
2. initializing the AppCheck service using the Firebase method `initializeAppCheck`
3. Providing the provider `AppCheckProvider`

Something very important to remember is to **initialize this component before accessing any service, such as Firebase Auth or Firebase Firestore**, otherwise, the requests to these services will fail.

```tsx title="FirebaseAppCheckProvider.tsx"
import { AppCheckProvider, useFirebaseApp } from 'reactfire';
import { initializeAppCheck, ReCaptchaV3Provider } from 'firebase/app-check';
import configuration from '~/configuration';

const FirebaseAppCheckProvider: React.FCC = ({ children }) => {
  const siteKey = 
    process.env.NEXT_PUBLIC_APPCHECK_KEY;

  const app = useFirebaseApp();

   if (!siteKey || !isBrowser() || configuration.emulator) {
    return <>{children}</>;
  }

  if (!configuration.production) {
    attachAppCheckDebugToken();
  }

  const provider = 
    new ReCaptchaV3Provider(siteKey);

  const sdk = initializeAppCheck(app, {
    provider,
    isTokenAutoRefreshEnabled: true,
  });

  return <AppCheckProvider sdk={sdk}>{children}</AppCheckProvider>;
};

export default FirebaseAppCheckProvider;
```

To attach a debug token, we need to define the following function:

```tsx
function attachAppCheckDebugToken() {
  const token =   
    process.env.NEXT_PUBLIC_APPCHECK_DEBUG_TOKEN;

  Object.assign(window, {
    FIREBASE_APPCHECK_DEBUG_TOKEN: token,
  });
}
```

### Using the FirebaseAppCheckProvider component

To use this provider, import it and place it below the `FirebaseApp` provider. For example, we assume you're initializing Firebase in `_app.tsx`. 

Below is an example of how the [Makerkit SaaS starter](/) renders the main application component:

```tsx title="_app.tsx"
<FirebaseAppShell config={firebase}>
  <FirebaseAppCheckProvider>
    <FirebaseAuthProvider>
      <FirebaseAnalyticsProvider>
        <Component {...pageProps} />
      </FirebaseAnalyticsProvider>
    </FirebaseAuthProvider>
  </FirebaseAppCheckProvider>
</FirebaseAppShell>
```

If everything went well, AppCheck will now be working on your local Firebase web application.

NB: while running the emulators using a demonstration project (such as `demo-makerkit`) AppCheck will not be working.

## Protecting Next.js API endpoints with Firebase AppCheck

Did you know that we can use Firebase AppCheck to protect a custom backend like the Next.js API endpoints? Well, yes, and it's also fairly simple.

Here is how we do it:
1. First, we need to generate a token with AppCheck that we will send as a header to our API requests.
2. The API endpoint is responsible for checking the validity of the token before handling the API handler. If invalid, the request is rejected.

### Sending App Check token along your API requests

The implementation to send a token along your API request may differ depending on how you request your API endpoints, but we will show a fairly simple example so that you can adapt it to your own implementation.

Below is a simple React hook to request a Firebase AppCheck token that we will send along as a header. 

It's important to notice that we will not use the hook `useAppCheck` from `reactfire`, because of a few drawbacks:

- it throws an error when not initialized
- we cannot call it conditionally

Therefore, we initialize the SDK manually through its context `AppCheckSdkContext`, so that we can control its behavior: in our case, **we want to fetch the token only when the SDK is provided**.

```tsx
function useGetAppCheckToken() {
  // instead of using useAppCheck()
  // we manually request the SDK
  // because we *may not have initialized it*
  const sdk = useContext(AppCheckSdkContext);

  return useCallback(async () => {
    try {
      // if the SDK does not exist, we cannot generate a token
      if (!sdk) {
        return;
      }

      const forceRefresh = false;

      const { token } =
         await getToken(sdk, forceRefresh);

      return token;
    } catch (e) {
      return;
    }
  }, [sdk]);
}
```

Now, let's make a simple fetch implementation that takes the token and sends it along. the below is extremely simplified, so please don't copy it literally.

All you need to know is that we need to send the result of the `getAppCheckToken` promise to be included in the `headers` of our API request.

```tsx
async function useFetch<Resp = unknown>(
  url: string,
  payload: string,
  method = 'POST',
  headers?: StringObject
) {
  const options: RequestInit = {
    method,
    headers: {
      accept: 'application/json',
      'Content-Type': 'application/json',
      ...(headers ?? {}),
    },
  };

  const getAppCheckToken = useGetAppCheckToken();
  const token = await getAppCheckToken();

  // if the app-check token was found
  // we add the header to the API request
  if (token) {
    headers['X-Firebase-AppCheck'] = token;
  }

  try {
    const response = await fetch(url, options);

    if (response.ok) {
      return (await response.json()) as Promise<Resp>;
    }

    return Promise.reject(response.statusText);
  } catch (e) {
    return Promise.reject(e);
  }
}
```

### Adding a middleware to protect API routes with AppCheck

To do so, we can create a simple API middleware that checks if the request is successful. If not, it will reject the request before the API handler is executed.

Below is our middleware:

```tsx title="appcheck-middleware.ts"
const FIREBASE_APPCHECK_HEADER =
   'X-Firebase-AppCheck';

export async function withAppCheck(
  req: NextApiRequest, 
  res: NextApiResponse
) {
  const appCheck = getAppCheck();
  const token =
     req.headers[FIREBASE_APPCHECK_HEADER];

  const forbidden = () => forbiddenException(res);

  if (!token || typeof token !== 'string') {
    return forbidden();
  }

  try {
    await appCheck.verifyToken(token);
  } catch (e) {
    return forbidden();
  }
}
```

How to use it?

#### 1) Simply use it within your handlers

```tsx
export default function(req, res) {
  await withAppCheck(req, res);
}
```

#### 2) Use it as a chain of middlewares

```tsx
export default withMiddleware(
  withAdmin,
  withAppCheck,
  withAuthedUser,
  (req, res) => {
    // write here your API handler
  }
)
```

## Conclusion

Many developers are very worried about using Firebase due to security reasons. AppCheck is one of the ways we can protect our applications against abuse, spammy users and automated bots.

Hopefully, this guide will help you improve the security of your Firebase applications and make you sleep better at night.

If you're looking for a complete example of the code above, consider purchasing a copy of our [Next.js and Firebase SaaS starter](/), which will help you get started in no time!

Secure your Next.js application with Firebase AppCheck


While Cypress has greatly simplified E2E testing for developers, it can still be tricky at times. For example, a best practice while running E2E testing is bypassing the UI when testing pages behind user authentication. 

The Cypress team, in particular, has long advocated for programmatically authenticating users when testing code not related to the authentication flow.
For example, if you are testing your Dashboard code, there is no need to use the UI to authenticate your users: this will only result in slower, heavier and more flaky E2E tests.

In this post, we show you how to sign in programmatically with Firebase Authentication to improve the speed of your Cypress tests and increase their reliability.

## Adding a Cypress command to sign-in programmatically

Cypress allows us to write global commands that we can access using the `cy` variable, which is globally available in all our Cypress tests.

To do so, we will extend Cypress commands with a new command we will name `signIn`, and will be available to us using `cy.signIn()`. Neat, isn't it?

First of all, we want to play nice with Typescript. That means we extend the Typescript's interface in a filename we name `global.d.ts`:

```tsx title="global.d.ts"
namespace Cypress {
    interface Chainable {
      signIn(
        redirectPath?: string,
        credentials?: { email: string; password: string }
      ): void;
    }
  }
}
```

Now, we can extend Cypress with a custom command named `signIn`. To do so, we add a command using the method `Cypress.Commands.add`:

```tsx title="commands.ts"
Cypress.Commands.add(
  'signIn',
  (
    redirectPath = '/',
    credentials = {
      email: Cypress.env(`EMAIL`) as string,
      password: Cypress.env(`PASSWORD`) as string,
    }
  ) => {
    // body
  }
);
```

The above function takes two parameters:
1. A path where to redirect users after signing in
2. The user credentials, but by providing some default values using environment variables

Let's now write the body of the function:

```tsx
// preserve the session cookie between tests
// otherwise the user will get logged out
Cypress.Cookies.defaults({
  preserve: ['session'],
});

// the function we will define to sign users in
signInProgrammatically(credentials); // <--- implementation is below

// after sign-in, we redirect the users to the provided path
cy.visit(redirectPath);
```

### Signing in using Cypress sessions

If you are using Cypress 12, you will need to use `cy.session`. The `cy.session` command will preserve the session cookie between tests, otherwise, the user will get logged out.

```tsx
Cypress.Commands.add(
  'signIn',
  (
    redirectPath = '/',
    credentials = {
      email: Cypress.env(`EMAIL`) as string,
      password: Cypress.env(`PASSWORD`) as string,
    }
  ) => {
    cy.session([credentials.email, credentials.password],
      () => {
        signInProgrammatically(credentials);
      }
    );

    cy.visit(redirectPath);
  }
);
```

## Using the Firebase Auth SDK to authenticate users in Cypress E2E tests

To sign our testing users in without having to interact with the application's UI, we will use the Firebase SDK.

### Connecting to the Firebase Auth Emulator

Of course, when running tests, we will be connecting to the Firebase Emulator. 

Below is a function `getAuth` that will initialize the Firebase SDK and return an instance of the Firebase Auth SDK connected to the local Firebase Emulator:

```tsx
import {
  Auth,
  connectAuthEmulator,
  initializeAuth,
  signInWithEmailAndPassword,
  UserCredential,
  indexedDBLocalPersistence,
} from 'firebase/auth';

function getAuthEmulatorHost() {
  const host = Cypress.env('NEXT_PUBLIC_FIREBASE_EMULATOR_HOST') as string;
  const port = Cypress.env('NEXT_PUBLIC_FIREBASE_AUTH_EMULATOR_PORT') as string;

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

let auth: Auth;

function getAuth() {
  const app = createFirebaseApp();

  auth =
    auth ||
    initializeAuth(app, {
      persistence: indexedDBLocalPersistence,
    });

  connectAuthEmulator(auth, getAuthEmulatorHost());

  return auth;
}
```

### Signing users in

Now that we can create an instance of the Firebase Auth SDK connected to the emulators, we can use it to sign users in programmatically:

```tsx
export function signInProgrammatically({
  email,
  password,
}: {
  email: string;
  password: string;
}) {
  const auth = getAuth();

  const signIn = signInWithEmailAndPassword(
    auth, 
    email, 
    password
  )
  .catch((e) => {
    cy.log(`User could not sign in programmatically!`);
    console.error(e);
  });

  return cy.wrap(signIn);
}
```

Finally, the `signInProgrammatically` function completes the `cy.signIn()` command defined in the beginning.

## Writing a Test that signs users in programmatically

Whenever you write tests that require users to be signed in, you can write the below:

```tsx
describe(`Create Invite`, () => {
  const email = `invited-member@makerkit.dev`;

  before(() => {
    cy.signIn(`/settings/organization/members`);
  });

  // your tests go here
});
```

As you can see, we can pass any path to the `signIn` function: after signing in, we redirect the users directly to that page, rather than having to use the UI. This will dramatically improve your E2E tests' speed and make them more reliable. Regardless, no need to test the authentication page over and over!

Programmatic Authentication with Firebase and Cypress


Firebase Auth Functions are **blocking functions** that allow us to write
server-side logic when the user creates an account or when signs in. This has
been one of the most requested features, which is why we're so excited about it.

The two blocking functions are:

1. `beforeCreate`: use this function before signing the user up to your Auth
Database

2. `beforeSignIn`: use this function when the user is verified upon signing in (i.e. when
the sign-in process is successful). This function is also called when the
user is signing up.

### Firebase Authentication Blocking Functions: Use-Cases

These functions can be used for various use-cases, such as:

- only allow users signing up with an allowed email or domain
- prevent users from accessing using certain IP addresses
- modifying user's data upon signing in (for example, set certain custom claims)
- ... and many others!

#### Requirements: Update to Firebase Authentication with Identity Platform

To use this new functionality you have to upgrade your Firebase project to
Firebase Authentication with Identity Platform using the Firebase Console.

## Preventing users from creating an account with Firebase Auth

One common scenario is to prevent the user from signing up based on certain
criteria, such as: email domain, IP address, and so on.

To do so, we can use the `beforeCreate` Firebase Auth
function so that we can check if the details provided meet the criteria for
signing up to your Firebase application.

In the example below, we have a list of allowed domain names, and we check
if the user's email is among the list:

```tsx
import functions from 'firebase-functions';

const ALLOWED_DOMAINS: string[] = [
  '@yourapp.com'
];

export const beforeCreate = functions.auth.user()
  .beforeCreate((user) => {
    const canAccess = ALLOWED_DOMAINS.some(domain => {
      return user.email.includes(domain);
    });

    if (!canAccess) {
      throw new functions.auth.HttpsError(
        'invalid-argument',
        `Unauthorized email "${user.email}"`
      );
    }
  });
```

## Preventing users from signing in with Firebase Auth

We can also prevent user from signing in after they've created a profile.
For example, let's assume an IP is acting suspiciously and we have banned it
from the application:

```tsx
export const beforeSignIn = functions.auth.user()
  .beforeSignIn((user) => {
    const ip = context.ipAddress;

    if (isSuspiciousIpAddress(ip)) {
      throw new functions.auth.HttpsError(
        'permission-denied',
        'Unauthorized access!'
      );
    }
  });
```

Another common scenario can be blocking access to your application from
mobile or unsupported devices:

```tsx
export const beforeSignIn = functions.auth.user()
  .beforeSignIn((user) => {
    const userAgent = context.userAgent;

    if (isMobile(userAgent)) {
      throw new functions.auth.HttpsError(
        'permission-denied',
        'Unauthorized access!'
      );
    }
  });
```

## Deploy Firebase Auth Blocking Functions

Finally, remember to deploy your functions:

```
firebase deploy --only functions
```

To know more about Firebase's blocking functions and the detailed API, visit
the [Firebase documentation](https://firebase.google.com/docs/auth/extend-with-blocking-functions).


Blocking authentication with Firebase Auth Functions


Firebase is a serverless platform by Google that helps developers build and
grow apps. Millions of developers every day use Firebase for building
complex and profitable SaaS projects.

Why is Firebase so popular? Firebase offers many services for developers:

- **Analytics**: Provides data about how people interact with your app on
mobile devices or the web without writing any code
- **Cloud Functions**: Runs server-side JavaScript code in response to events
such as user actions or real-time messages from other platforms like Slack or Facebook Messenger
- **Cloud Storage**: Lets you store and access user-generated content like
images or videos in the cloud
- **Firestore and RealTime DB**: two serverless and NoSQL databases with
different strengths for storing your application data
- **Messaging**: allows sending push messages and notifications to the
connected clients
- **AppCheck**: helps secure your applications with the invisible Recaptcha v3

## Top Reasons why Firebase is great for building a SaaS

### 1) Firebase offers everything you need to build a large SaaS

As you can see, Firebase offers a complete solution for building a SaaS.

It's easy to set up and secure and scales out automatically as you grow. In addition, it's cost-effective and easy to use, so you don't need an army of developers to maintain your database or update its security rules.

In this post, we'll detail why Firebase is one of the best solutions for building a modern SaaS and its weaknesses, so you know how to complement it with other tools should you need to.

### 2) Developers can use Firebase with the whole suite of Google Cloud products

When Firebase doesn't support what you need, you can still use all the other Google Cloud's products, such as:

- SQL databases
- Caching stores such as Redis
- Analytics Tools and DBs such as BigQuery and BigTable
- Secret Management services
- ... and all the rest of Google Cloud's products and its Marketplace that
allows you to install apps with a single click

### 3) The Firebase Emulator helps you develop locally

The Firebase emulator is a fully-functional, real-time simulator of your app that you can use to test your code locally.

The emulator covers all the Firebase products, which means you can create a local environment that almost entirely reflects your Cloud application in production.

### 4) Create different projects for each environment

Firebase isn't stingy about how many projects you create, so you can easily create a project for each environment.: This helps you save money and develop projects that most likely won't cost you anything more.

### 5) It allows to build serverless products on the Cloud

The cloud is a great place to build serverless products. You don’t need to worry about database maintenance or server uptime and reliability because everything is taken care of automatically. Firebase lets you focus on building your core product while keeping costs low.

If you are a solo developer or a small team, relying on Google's cloud reliability is incredibly helpful: in fact, all your time is best spent on building the product and gaining product-market fit, rather than fighting CIs and servers all day.

### 6) It can be used for building web and mobile apps (iOS, Android, and Web)

While Firebase is often regarded as a PaaS for Mobile apps, the truth is that you can build any application with it: Web Apps, IoT apps, and desktop ones.

Firebase has developed its SDKs to work with multiple programming languages and platforms and offers a Rest API for the unsupported ones.

### 7) The Firebase SDKs have received huge updates

Firebase has often been criticized for its SDKs: heavy on the client-side, confusing due to the various published versions, and not the best API out there.

Fortunately, the Firebase SDKs have received more love recently: starting from version 9 (the current one at the time of writing), they are lighter, more straightforward to use, and better documented.

They're finally tree-shakeable, so your client-side will only load what it uses.

### 8) It's reasonably priced

Firebase is a very reasonably priced service for what it does.

Also, thanks to its very generous free tier, it's likely that you will not spend a dollar on developing your application during its first months if your traffic is light.

This is amazing if you are a solo developer, a small startup, or quickly prototyping an internal tool for your company.

## Makerkit is one of the complete Firebase SaaS starters with Next.js

The most complete Firebase SaaS starter kit today is Makerkit: **It's a
complete solution for building a SaaS, including all the modules you need to
start**.

It's built on top of Firebase, Next.js and Tailwind CSS and offers everything
you need to kick-start a fully working SaaS application that you can use as
a starting point for shipping your next SaaS idea.

Makerkit is built on the fastest growing technologies in recent years,
designed to be quick and easy to use.

## Conclusion

In conclusion, Firebase is an excellent choice for building SaaS applications; we think it's even better today than before and will continue to improve.

Therefore, we at Makerkit believe that Firebase is one of the best options available if you're looking to build a scalable, serverless product on the cloud that supports real-time notifications.

If you want to build a new SaaS with Firebase, take a look at our SaaS starter template for creating a SaaS with Firebase and Next.js. We made it so that starting a new SaaS project won't take more than 5 minutes. It's ideal if you are a solo developer or a startup or if you feel like prototyping something new.


Is Firebase good for building a SaaS?


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 title=".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 title=".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 title="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 title="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 title="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 title="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.


Firebase

Tutorials and Guides about Firebase