Tutorials


This tutorial is a comprehensive guide to getting started with the Next.js and Firebase SaaS template to build a basic tasks application, from fetching the repository to deploying the application.

By the end, you'll have a fully working application with the minimum basics a SaaS needs:

1. Landing Page and Marketing pages (blog, documentation)
2. Authentication (sign in, sign up)
3. Payments (Stripe)
4. Profile and Organization management

## Prerequisites

To get started, you're going to need some things installed:

1. Git
2. Node.js version
3. npm 7 or greater
4. A code editor (VSCode, WebStorm)
5. If you'd like to deploy your application, you'll also want an account on Vercel (it's free and easy to use)

Experience with React, TypeScript/JavaScript, and Firebase would be advantageous but not strictly required. The codebase can also serve as a way to learn these topics more in-depth.

If you have all the above installed, I guess we can get started!

Get a head start on your app development with our Makerkit SaaS boilerplate, built with Next.js and Firebase. Follow our step-by-step guide for an easy setup.

Building a SaaS tasks application with Makerkit


## Initializing the Project

You have two ways to initialize the project:

1. Forking it from GitHub, or
2. Cloning it using Git

### 1. Forking the Repository

Fork this repository by clicking on the "Fork" button on the top right
corner in GitHub for the repository you want to use.

Once you have forked the repository, clone it locally. Then, set the
upstream repository to the original repository, so you can pull updates
when needed:

```
git remote add upstream git@github.com:makerkit/next-firebase-saas-kit.git
```

### 2. Cloning the Repository

Alternatively, assuming you have accepted the invites and have access to the repository, open your terminal and run this command (replace `tasks-app` with your name of choice):

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

Once completed, we'll change into the `tasks-app` directory, and then we will install the Node modules:

```
cd tasks-app
npm i
```

### Reinitialize Git

As the Git repository's remote points to Makerkit's original repository, you can re-initialize (optionally!) it and set the Makerkit repository as `upstream`:

```
rm -rf .git
git init
```

Then, we set the Makerkit repository as `upstream`:

```
git remote add upstream git@github.com:makerkit/next-firebase-saas-kit.git
git add .
git commit -a -m "Initial Commit"
```

By adding the Makerkit's repository as `upstream` remote, you can fetch updates (after committing your files) by running the following command:

```
git pull upstream main --allow-unrelated-histories
```

Perfect! Now you can fire up your IDE and open the `tasks-app` project we just created.

This section describes how to set up your development environment to use the Next.js Firebase SaaS template, from forking the repository to installing the Node modules

Initial Setup


When inspecting the project structure, you will find something similar to the below:

```
tasks-app
├── README.md
├── @types
├── src
│   ├── components
│   ├── core
│   ├── lib
│   └── pages
        └── _document.tsx
        └── _app.tsx
│       └── index.tsx
├── package-lock.json
├── package.json
├── public
│   └── favicon.ico
├── next.config.mjs
└── tsconfig.json
```

NB: we omitted a lot of the files for simplicity.

Let's take a deeper look at the structure we see above:

- `src/core`: this folder contains reusable building blocks of the template that **are not related to any domain**. This includes components, React hooks, functions, and so on.
- `src/components`: this folder contains the application's components, including those that belong to your application's domain. For example, we can add the `tasks` components to `src/components/tasks`.
- `src/lib`: this folder contains the business logic of your application's domain. For example, we can add the `tasks` hooks to write and fetch data from Firestore in `src/lib/tasks`.
- `src/pages`: this is Next.js's special folder where we add our application routes.

Don't worry if this isn't clear yet! We'll explain where we place our files in the sections ahead.

A quick overview of the project structure and how to navigate it.

Project Structure


When we run the stack of a Makerkit application, we will need to run a few commands before:

1. **Next.js**: First, we need to run the Next.js development server
2. **Firebase**: We need to run the Firebase Emulators. The emulators allow us to run a fully-local Firebase environment.
3. **Stripe CLI** (optional): If you plan on interacting with Stripe, you are also required to run the Stripe CLI, which allows us to test the webhooks from Stripe against our local server.

### Running the Next.js development server

Run the following command from your IDE or from your terminal:

```
npm run dev
```

This command will start the Next.js server at [localhost:3000](http://localhost:3000). If you navigate to this page, you should be able to see the landing page of your application:

<Image src='/assets/images/posts/tutorial-landing-page.webp' width="2856" height="1972" />

### Running the Firebase Emulators

To interact with Firebase's services, such as Auth, Firestore, and Storage, we need to run the Firebase emulators. To do so, open a new terminal (or, better, from your IDE) and run the following command:

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

If everything is working correctly, you will see the output below:

```
┌────────────────┬────────────────┬─────────────────────────────────┐
│ Emulator       │ Host:Port      │ View in Emulator UI             │
├────────────────┼────────────────┼─────────────────────────────────┤
│ Authentication │ localhost:9099 │ http://localhost:4000/auth      │
├────────────────┼────────────────┼─────────────────────────────────┤
│ Firestore      │ localhost:8080 │ http://localhost:4000/firestore │
├────────────────┼────────────────┼─────────────────────────────────┤
│ Pub/Sub        │ localhost:8085 │ n/a                             │
├────────────────┼────────────────┼─────────────────────────────────┤
│ Storage        │ localhost:9199 │ http://localhost:4000/storage   │
└────────────────┴────────────────┴─────────────────────────────────┘
  Emulator Hub running at localhost:4400
  Other reserved ports: 4500, 9150
```

By default, we run the emulator for the following services: Authentication, Firestore, and Storage. However, you can easily add Firebase Functions and PubSub.

#### Firebase Emulator UI

As you can see from the `View in Emulator UI` column, you have access to the Emulator UI, which helps you see and edit your Firebase Emulator data using a nifty UI that resembles the Firebase Console.

For example, to display the list of users that have signed up, navigate to the [Authentication Emulator](http://localhost:4000/auth).

<Alert type='info'>
  Makerkit's template adds some data to your project by default for testing reasons. In fact, the data you see is used to run the Cypress E2E tests. This is why you'll see some pre-populated data in your Firestore and Authentication tabs.
</Alert>

### Running the Stripe CLI (optional)

Optionally, 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
```

This command requires Docker, but you can alternatively install Stripe on your OS and change the command to use `stripe` directly.

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.

Learn how to run the app locally for development and testing.

Running the App


Makerkit can be configured from a single place: the `src/configuration.ts` object. This file exports a constant we use throughout the project to read our application's settings.

<Alert type='info'>
  <Alert.Heading>
    Use this file to configure your project
  </Alert.Heading>

  We recommend adding additional configuration to this file rather than reading it directly from the environment variables. For example, assuming you rename one of your environment variables, you will only need to update it in one place. Additionally, it helps maintain your codebase more explicit and understandable.
</Alert>

We retrieve some of this file's configuration using **environment variables**: these help us swap and tweak our settings based on which environment we're using, such as the Firebase configuration.

For example, in your Vercel console, you could run multiple projects:
- one for `production`
- and one for `staging`

Here is what the configuration file looks like:

```tsx title="src/configuration.ts"
const configuration = {
  site: {
    name: 'Awesomely - Your SaaS Title',
    description: 'Your SaaS Description',
    themeColor: '#ffffff',
    themeColorDark: '#0a0a0a',
    siteUrl: process.env.NEXT_PUBLIC_SITE_URL as string,
    siteName: 'Awesomely',
    twitterHandle: '',
    githubHandle: '',
    language: 'en',
    convertKitFormId: '',
  },
  firebase: {
    apiKey: process.env.NEXT_PUBLIC_FIREBASE_API_KEY,
    authDomain: process.env.NEXT_PUBLIC_FIREBASE_AUTH_DOMAIN,
    projectId: process.env.NEXT_PUBLIC_FIREBASE_PROJECT_ID,
    storageBucket: process.env.NEXT_PUBLIC_FIREBASE_STORAGE_BUCKET,
    messagingSenderId: process.env.NEXT_PUBLIC_FIREBASE_MESSAGING_SENDER_ID,
    appId: process.env.NEXT_PUBLIC_FIREBASE_APP_ID,
    measurementId: process.env.NEXT_PUBLIC_FIREBASE_MEASUREMENT_ID,
  },
  auth: {
    // Enable MFA. You must upgrade to GCP Identity Platform to use it.
    // see: https://cloud.google.com/identity-platform/docs/product-comparison
    enableMultiFactorAuth: false,
    // NB: Enable the providers below in the Firebase Console
    // in your production project
    providers: {
      emailPassword: true,
      phoneNumber: false,
      emailLink: false,
      oAuth: [GoogleAuthProvider],
    },
  },
  emulatorHost: process.env.NEXT_PUBLIC_EMULATOR_HOST,
  emulator: process.env.NEXT_PUBLIC_EMULATOR === 'true',
  production: process.env.NODE_ENV === 'production',
  paths: {
    signIn: '/auth/sign-in',
    signUp: '/auth/sign-up',
    emailLinkSignIn: '/auth/link',
    onboarding: `/onboarding`,
    appHome: '/dashboard',
    settings: {
      profile: '/settings/profile',
      authentication: '/settings/profile/authentication',
      email: '/settings/profile/email',
      password: '/settings/profile/password',
    },
    api: {
      checkout: `/api/stripe/checkout`,
      billingPortal: `/api/stripe/portal`,
    },
    searchIndex: `/public/search-index`,
  },
  navigation: {
    style: LayoutStyle.Sidebar,
  },
  appCheckSiteKey: process.env.NEXT_PUBLIC_APPCHECK_KEY,
  email: {
    host: '',
    port: 0,
    user: '',
    password: '',
    senderAddress: '',
  },
  emailEtherealTestAccount: {
    email: process.env.ETHEREAL_EMAIL,
    password: process.env.ETHEREAL_PASSWORD,
  },
  sentry: {
    dsn: process.env.SENTRY_DSN,
  },
  stripe: {
    plans: [
      {
        name: 'Basic',
        description: 'Description of your Basic plan',
        price: '$249/year',
        stripePriceId: 'basic-plan',
        features: [
          'Feature 1',
          'Feature 2',
          'common:plans.features.feature1'
        ],
      },
    ],
  }
};
```

Feel free to extend this configuration to your needs. For example, you could new properties to the `site` object to store your social media handles, or add new properties to the `paths` object to store the paths to your pages.


Learn how to set up up your project's configuration

Project Configuration


The starter project comes with three different environment variables files:

1. **.env**: this is a shared environment file. Here, you can add variables shared across all the environments.
2. **.env.development**: the configuration file loaded when running the `dev` command: by default, we add the Firebase Emulators settings to this file.
 - Use this file for your **development configuration**.
3. **.env.production**: the configuration file loaded when running the `build` command locally or deployed to Vercel.
 - Use this file for your **actual project's configuration** (without private keys!).
4. **.env.test**: this environment file is loaded when running the Cypress E2E tests. You would rarely need to use this.

Additionally, you can add another environment file named `.env.local`: this file is never added to Git and can be used to store the secrets you need during development.

<Alert type='warn'>
  <span className='block'>
    Never ever add secrets to your `.env` files. It's not safe, and you risk leaking confidential data.
  </span>

  <span>
    Instead, add your secrets using your Vercel Console, or use the `.env.local` file during development.
  </span>
</Alert>

## Adding Environment Variables

The production environment variables template looks like the below:

```bash
NEXT_PUBLIC_FIREBASE_API_KEY=
NEXT_PUBLIC_FIREBASE_PROJECT_ID=
NEXT_PUBLIC_FIREBASE_STORAGE_BUCKET=
NEXT_PUBLIC_FIREBASE_MESSAGING_SENDER_ID=
NEXT_PUBLIC_FIREBASE_APP_ID=
NEXT_PUBLIC_FIREBASE_MEASUREMENT_ID=
NEXT_PUBLIC_FIREBASE_AUTH_DOMAIN=
NEXT_PUBLIC_SITE_URL=
NEXT_PUBLIC_APPCHECK_KEY=
NEXT_PUBLIC_REQUIRE_EMAIL_VERIFICATION=false

FIREBASE_CLIENT_EMAIL=
GCLOUD_PROJECT=

## SECRET KEYS ARE BEST ADDED TO YOUR CI
FIREBASE_PRIVATE_KEY=

STRIPE_SECRET_KEY=
STRIPE_WEBHOOK_SECRET=
```

Learn how to use environment variables in your Next.js project.

Environment Variables


This SaaS template uses Tailwind CSS for styling the application.

You will likely want to tweak the brand color of your application: to do so, open the file `tailwind.config.js` and replace the `primary` color (which it's `indigo` by default):

```js title="tailwind.config.js"
extend: {
  colors: {
    primary: {
      ...colors.indigo,
      contrast: '#fff',
    },
    black: {
      50: '#525252',
      100: '#363636',
      200: '#282828',
      300: '#222',
      400: '#121212',
      500: '#0a0a0a',
      600: '#040404',
      700: '#000',
    },
  },
},
```

### Updating the Primary color of your app

To update the `primary` color, you can either:

1. choose another color from the Tailwind CSS Color palette (for example, try `colors.blue`)
2. define your own colors, from `50` to `900`

The `contrast` color will be helpful to define the text color of some components, so tweaking it may be required.

Once updated, the Makerkit's theme will automatically adapt to your new color palette! For example, below, we set the primary color to `colors.blue`:

<Image src='/assets/images/posts/blue-dark-theme.webp' width="2842" height="1966" />

### Dark Mode

Makerkit also ships with a dark theme.

The light theme is the default, but users can switch to the other, thanks to the component `DarkModeToggle`.

If you wish to only use one theme, you can tweak the configuration using the following flag in the configuration file `~/configuration.ts`:

```ts title="~/configuration.ts"
{
  ...
  enableThemeSwitcher: false,
  ...
}
```

The default Tailwind media switcher is not supported since Makerkit uses its own system that allows users to choose the System theme (light or dark) or the theme defined by the application.

## Caveats

1. Setting the dark theme by default is currently not supported without some minor tweaks. It is being developed.
2. The default Tailwind media switcher is not supported since Makerkit uses its own system that allows users to choose the System theme (light or dark) or the theme defined by the application.

Learn how to configure Tailwind CSS and tweak the Makerkit's theme.

Tailwind CSS and Styling


The Next.js/Firebase template uses Firebase Auth to manage authentication into the internal application.

The kit supports the following strategies:

1. Email/Password
2. oAuth Providers such as Google, Twitter, Facebook, Microsoft, Apple, etc.
3. Phone Number
4. Email Link

You can choose one, more, or all of them together, and you can easily tweak this using the global configuration.

By default, our SaaS Starter uses Email/Password and Google Auth.

### How does Authentication work?

First, let's just take a high-level overview of how Makerkit's authentication works.

MakerKit **uses SSR throughout the application**, except for the marketing pages. Using SSR, we can persist the user's authentication on every page and access the user's object on the server **before rendering the page**.

This can help you both in terms of UX and DX. In fact, persisting the user's session server-side can help you in various scenarios:

- Simplifying the business logic: for example, checking server-side if a user can access a specific page before rendering that page
- Rendering the user's data server-side by fetching some data from Firestore in the `getServerSideProps` function

#### How does SSR work?

To enable SSR with Firebase Auth, we use [Session Cookies](https://firebase.google.com/docs/auth/admin/manage-cookies).

1. First, we use the Firebase Auth Client SDK to sign users in, as described in every tutorial. Furthermore, when a user signs in or signs up, we retrieve the ID Token and make a request to our API to create a session cookie. The session cookie remains valid for 14 days, after which it will expire.
2. The cookie `sessionId` gets stored as an HTTP-only cookie: we can use this server-side for fetching the current user.
3. When the token expires, we sign users out of the application

So... how do they work?

1. The client SDK uses the Firebase Auth credentials stored in the IndexedDB Storage. This includes interacting with Firebase Storage and Firebase Firestore on the client side.
2. The server-side API uses the `sessionId` cookie to retrieve and authenticate the current user. We can then use the Firebase Admin API and interact with the various Firebase services.

### Authentication Strategies

To add or tweak the authentication strategies of our application, we can update the configuration:

```tsx title="src/configuration.ts"
auth: {
  // Enable MFA. You must upgrade to GCP Identity Platform to use it.
  // see: https://cloud.google.com/identity-platform/docs/product-comparison
  enableMultiFactorAuth: false,
  // NB: Enable the providers below in the Firebase Console
  // in your production project
  providers: {
    emailPassword: true,
    phoneNumber: false,
    emailLink: false,
    oAuth: [GoogleAuthProvider],
  },
},
```

Above, you can see the **default configuration**. It should look like the following:

<Image src='/assets/images/posts/tutorial-sign-in.webp' width="2834" height="1972" />

Ok, cool. But what if we wanted to swap `emailPassword` with `emailLink` and add `Twitter oAuth`?

We will do the following:

```tsx title="src/configuration.ts"
import { GoogleAuthProvider, TwitterAuthProvider } from 'firebase/auth';

auth: {
  // Enable MFA. You must upgrade to GCP Identity Platform to use it.
  // see: https://cloud.google.com/identity-platform/docs/product-comparison
  enableMultiFactorAuth: true,
  // When enabled, users will be required to verify their email address
  // before being able to access the app
  requireEmailVerification:
    process.env.NEXT_PUBLIC_REQUIRE_EMAIL_VERIFICATION === 'true',
  // NB: Enable the providers below in the Firebase Console
  // in your production project
  providers: {
    emailPassword: true,
    phoneNumber: false,
    emailLink: false,
    oAuth: [GoogleAuthProvider],
  },
},
```

And the result will be similar to the image below:

<Image src='/assets/images/posts/tutorial-sign-in-email-link.webp' width="2834" height="1972" />

#### Custom oAuth providers

Additionally, we can add custom oAuth providers, such as `Microsoft` and `Apple`:

```tsx
class MicrosoftAuthProvider extends OAuthProvider {
  constructor() {
    super('microsoft.com');
  }
}

class AppleAuthProvider extends OAuthProvider {
  constructor() {
    super('apple.com');
  }
}
```

Then, you will add these classes to the `auth.providers.oAuth` object of the configuration.

<Alert type='warn'>
  Remember that you will always need to enable the authentication methods you want to use from the Firebase Console once you deploy your application to production
</Alert>

### Creating Accounts

Users can be redirected to the [Sign Up page](http://localhost:3000/auth/sign-up) to create an account.

### Requiring Email Verification

By default, Firebase does not require users to verify their email address before being able to access the application. It is a flag on the user account, but the user is not prevented from accessing the application.

We solve this server-side by checking if the user has verified their email address before rendering the page.

To enable this feature, you can set the `requireEmailVerification` flag to `true` using the following environment variable:

```bash title=".env"
NEXT_PUBLIC_REQUIRE_EMAIL_VERIFICATION=true
```

Learn about the authentication strategies supported by Makerkit and how to configure them.

Authentication


After sign-up, users are redirected to the onboarding flow.

Here, you can ask users questions, configure their accounts or simply show them around.

By default, Makerkit adds one single step, where it asks users to **create an organization**.

<Image src="/assets/images/posts/onboarding-flow-tutorial.webp" width="2940" height="1972" />

Of course, you can extend it and add as many steps as you wish. I would recommend replacing the image on the right-hand side with a screenshot of your application, a video, or something that can help users understand what they are signing up for.

### What happens when the user submits the form?

After the user submits the form, the API will:

1. create the user Firestore record at `/users`
2. create the organization Firestore record at `/organizations` and assign the user as its owner

I encourage you to visit the [Firestore Emulator UI](http://localhost:4000/firestore/) and see the data created.

### What is an "Organization"?

Organizations are groups of users.

You can call them projects, teams, classrooms, or whatever feels suitable for your domain. But, generally speaking, organizations are the backbone of the data model because it's where we store most of the data shared among users.

Users can:

1. create new Organizations
2. be invited to other Organizations
3. switch between organizations using a dropdown

### Can I remove this step?

No, **but you can skip it** by automatically submitting the form.

Yes, you can follow this guide for [removing the onboarding flow and organizations](/recipes/removing-organizations).

Learn how to onboard your users to your app using the Onboarding Flow.

Onboarding Flow


It's time to work on our application's value proposition: adding and tracking tasks! This is likely the most exciting part for you because **it's where you get to change things and add your SaaS features to the template**.

### Page Structure

Before getting started, let's take a look at the default page structure of the boilerplate is the following.

```txt
├── pages
  └── api
    └── onboarding
    └── organizations
    └── stripe
    └── session
    └── user

  └── auth
    └── invite
      └── [code].tsx

    └── link.tsx
    └── password-reset.tsx
    └── sign-in.tsx
    └── sign-up.tsx

  └── dashboard
    └── index.tsx

  └── onboarding
    └── index.tsx

  └── settings
    └── organization
      └── members
        └── index.tsx
        └── invite.tsx

    └── profile
      └── index.tsx
      └── email.tsx
      └── password.tsx
      └── authentication.tsx
    └── subscription

  └── blog
    └── [collection]
      └── [slug].tsx

  └── docs
    └── [page]
      └── slug.tsx
    └── index.tsx

  └── 500.tsx
  └── 404.tsx
  └── _document.tsx
  └── _app.tsx
  └── index.tsx
  └── faq.tsx
  └── pricing.tsx
```

### Setting the application's Home Page

By default, the application's home page is `/dashboard`; every time the user logs in, they're redirected to the page `src/pages/dashboard/index.tsx`.

You can update the above by setting the application's home page path at `configuration.paths.appHome`. The configuration file can be found at `src/configuration.ts`.

Unless you want to change the application's home page, **you can skip this section**, but it's good to know.

### Demo: Tasks Application

Our demo application will be a simple tasks management application. We will be able to create tasks, list them, mark them as completed, and delete them.

Here is a quick demo of what we will build:

<Video src="/assets/images/posts/tasks-demo.mp4" />

### Routing: Adding the Tasks Pages

Ok, so we want to add three pages to our application:

1. **Tasks List**: A page to list all our tasks
2. **Create New Task**: Another page to create a new task
3. **Task Page**: A page specific to the selected task

To create these two pages, we will create a folder named `tasks` at `src/pages/tasks.`

In the folder `src/pages/tasks` we will create three **Page Components**:

#### 1. List Page

We create a page `index.tsx`, which is accessible at the path `/tasks`.

NB: we will be creating the `TasksContainer` in the next steps.

```tsx filename=src/pages/tasks/index.tsx {4,16}
import { GetServerSidePropsContext } from 'next';
import { withAppProps } from '~/lib/props/with-app-props';
import RouteShell from '~/components/RouteShell';
import TasksContainer from '~/components/tasks/TasksContainer';
import { useCurrentOrganization } from '~/lib/organizations/hooks/use-current-organization';

const Tasks = () => {
  const organization = useCurrentOrganization();

  if (!organization) {
    return null;
  }

  return (
    <RouteShell title={'Tasks'}>
      <TasksContainer organizationId={organization.id} />
    </RouteShell>
  );
};

export default Tasks;

export async function getServerSideProps(ctx: GetServerSidePropsContext) {
  return await withAppProps(ctx);
}
```

Notice: we have added a `getServerSideProps` function to the page. This is because we need to fetch the current organization of the user before rendering the page. We will be using this organization ID to fetch the tasks. Additionally, the `withAppProps` function will:
- ensure the user is logged in
- ensure the user has an organization and is onboarded

As a rule of thumb, **every page that requires the user to be logged in should use a `getServerSideProps` function** with `withAppProps`.

```tsx /withAppProps/
import { GetServerSidePropsContext } from "next";
import { withAppProps } from "~/lib/props/with-app-props";

export async function getServerSideProps(
  ctx: GetServerSidePropsContext
) {
  return await withAppProps(ctx);
}
```

#### 2. Create Task Page

We create a page `new.tsx`, which is accessible at the path `/tasks/new`. We will be creating the `CreateTaskForm` component in the next steps.

```tsx filename=src/pages/tasks/new.tsx {4,12}
import { GetServerSidePropsContext } from 'next';
import { withAppProps } from '~/lib/props/with-app-props';
import RouteShell from '~/components/RouteShell';
import CreateTaskForm from '~/components/tasks/CreateTaskForm';

const NewTaskPage = () => {
  return (
    <RouteShell title={'New Task'}>
      <div
        className={'max-w-2xl border border-gray-50 p-8 dark:border-black-400'}
      >
        <CreateTaskForm />
      </div>
    </RouteShell>
  );
};

export default NewTaskPage;

export async function getServerSideProps(
  ctx: GetServerSidePropsContext
) {
  return await withAppProps(ctx);
}
```

#### 3. Task Page

We create a page `[id].tsx`, which is accessible at the path `/tasks/<taskID>` where `taskID` is a dynamic variable that refers to the actual ID of the task.

```txt
├── pages
  └── tasks
    └── index.tsx
    └── new.tsx
    └── [id].tsx
```

Below is what the page looks like. We will be defining the `TaskItemContainer` component in the next steps.

```tsx filename=src/pages/tasks/[id].tsx {5,19}
import { GetServerSidePropsContext } from 'next';
import ArrowLeftIcon from '@heroicons/react/24/outline/ArrowLeftIcon';

import { withAppProps } from '~/lib/props/with-app-props';
import TaskItemContainer from '~/components/tasks/TaskItemContainer';

import RouteShell from '~/components/RouteShell';
import Heading from '~/core/ui/Heading';
import Button from '~/core/ui/Button';
import Alert from '~/core/ui/Alert';
import ErrorBoundary from '~/core/ui/ErrorBoundary';

const TaskPage: React.FC<{ taskId: string }> = ({ taskId }) => {
  return (
    <RouteShell title={<TaskPageHeading />}>
      <ErrorBoundary
        fallback={<Alert type={'error'}>Ops, an error occurred :(</Alert>}
      >
        <TaskItemContainer taskId={taskId} />
      </ErrorBoundary>
    </RouteShell>
  );
};

function TaskPageHeading() {
  return (
    <div className={'flex items-center space-x-6'}>
      <Heading type={4}>
        <span>Task</span>
      </Heading>

      <Button size={'small'} color={'transparent'} href={'/tasks'}>
        <ArrowLeftIcon className={'mr-2 h-4'} />
        Back to Tasks
      </Button>
    </div>
  );
}

export default TaskPage;

export async function getServerSideProps(ctx: GetServerSidePropsContext) {
  const appProps = await withAppProps(ctx);
  const taskId = ctx.query.id;

  if ('props' in appProps) {
    return {
      props: {
        ...(appProps.props ?? {}),
        taskId,
      },
    };
  }

  return appProps;
}
````

Above, we're extending `withAppProps` to include the `taskId` in the props. This is just an example, it's not strictly needed as we would be able to fetch the task ID from the URL in the `TaskItemContainer` component.

With that said, assuming you want to fetch data in the `getServerSideProps` function, you can do so and then pass it to the component as props.

### Adding Functionalities to your application

To add new functionalities to your application (in our case, tasks management), usually, you'd need the following things:

1. **Add a new page**, and the links to it in `pages`
2. **Add the components of the domain** and import them into the pages in `components`
3. Add data-fetching and writing to this domain's entities in `lib`

The above are the things we will do in the following few sections.

To clarify further the conventions of this boilerplate, here is what you should know:

1. **Data Model**: first, we want to define the data model of the feature you want to add
2. **Firestore Hooks**: once we're happy with the data model, we can create our Firestore hooks to write new tasks and then fetch the ones we created
3. **Import hooks into components**: then, we import and use our hooks within the components
4. **Add feature components into the pages**: finally, we add the components to the pages

### Adding page links to the Navigation Menu

To update the navigation menu, we need to update the `NAVIGATION_CONFIG` object in `src/navigation.config.tsx`.

```ts
const NAVIGATION_CONFIG = {
  items: [
    {
      label: 'common:dashboardTabLabel',
      path: configuration.paths.appHome,
      Icon: ({ className }: { className: string }) => {
        return <Squares2X2Icon className={className} />;
      },
    },
    {
      label: 'common:settingsTabLabel',
      path: '/settings',
      Icon: ({ className }: { className: string }) => {
        return <Cog8ToothIcon className={className} />;
      },
    },
  ],
};
```

To add a new link to the header menu, we can add the following item in the `NAVIGATION_CONFIG` object:

```tsx
{
  label: 'common:tasksTabLabel',
  path: '/tasks',
  Icon: ({ className }: { className: string }) => {
    return <Squares2X2Icon className={className} />;
  },
},
```

Now, also add the `common:tasksTabLabel` key to the `public/locales/en/common.json` file:

```json
{
   "tasksTabLabel": "Tasks"
}
```

Save the file and restart the Next server by rerunning the `npm run dev` command.

The result will be similar to the images below:

<Image src="/assets/images/posts/sidebar-layout-link.webp" width="1280" height="984" />

Learn how to get started developing new features in your app

Development: adding custom features


Before writing the Components, we want to tackle the task of fetching data from Firestore.

This involves a couple of steps:

1. We need to define, on paper, what the data model of the Firestore collections looks like
2. We need to update the Firestore rules so we can read and write data to the collection
3. We need to write the hooks to fetch data from Firebase Firestore

#### Firestore Data Model

First, let's write the data model. But... what does it mean?

When thinking about the Firestore data model, we need to answer the following questions:

1. Where does the data live?
2. How is the data structured?
3. How do we protect the data with security rules?

Ok, let's reply to these questions.

##### Where does the data live?

We can place `tasks` as a Firestore top-level collection. Because tasks belong to an organization, we can ensure that only users of that organization can read and write those tasks by adding a foreign key to each `task` named `organizationId`.

##### How is the data structured?

We can define a `Task` model at `src/lib/tasks/types/task.ts`:

```tsx title="src/lib/tasks/types/task.ts"
export interface Task {
  name: string;
  description: string;
  organizationId: string;
  dueDate: string;
  done: boolean;
}
```

##### How do we protect the data with security rules?

To write our Security Rules, we will update the file `firestore.rules`:

```
match /tasks/{taskId} {
  allow create: if userIsMemberByOrganizationId(incomingData().organizationId);
  allow read, update, delete: if userIsMemberByOrganizationId(existingData().organizationId);
}
```

The function `userIsMemberByOrganizationId` is pre-defined in the Makerkit's template: basically, it will verify that the current user is a member of the organization with ID `organizationId`.

If you use VSCode, take a look at the extension `toba.vsfire`.

### Data Fetching: React Hooks to read data from Firestore

Now that our security rules are updated, we can write Hooks to read data from Firestore.

I recommend writing your entities' hooks at `src/lib/tasks/hooks`. Let's start with a `React Hook` to fetch all the organization's tasks:

```tsx title="src/lib/tasks/hooks/use-fetch-tasks.ts"
import { useFirestore, useFirestoreCollectionData } from 'reactfire';

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

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

function useFetchTasks(organizationId: string) {
  const firestore = useFirestore();
  const tasksCollection = 'tasks';

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

  const path = `organizationId`;
  const operator = '==';
  const constraint = where(path, operator, organizationId);
  const organizationsQuery = query(collectionRef, constraint);

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

export default useFetchTasks;
```

Let's take a deep breath and slowly go through the above hook.

1. The hook above uses `useFirestoreCollectionData`, a `React hook` from the library `reactfire` to fetch real-time collection data from Firestore
2. We build a query that checks that the `organizationId` parameter matches the `organizationId` property of each task
3. Finally, we add `{ idField: 'id' }`. This special parameter decorates the data with the ID of the document. Thanks to the interface `WithId`, we add an `id` property to the `Task` interface returned from Firestore

### Displaying Firestore data in Components

Now that we can fetch our data using the hook `useFetchTasks,` we can build a component that lists each `Task.`

To do so, let's create a new component named `TasksListContainer`:

```tsx title="components/tasks/TasksContainer.tsx"
import PageLoadingIndicator from '~/core/ui/PageLoadingIndicator';
import Alert from '~/core/ui/Alert';
import Heading from '~/core/ui/Heading';
import Button from '~/core/ui/Button';

import useFetchTasks from '~/lib/tasks/hooks/use-fetch-tasks';
import TasksList from '~/components/tasks/TasksList';

const TasksContainer: React.FC<{
  organizationId: string;
}> = ({ organizationId }) => {
  const { status, data: tasks } = useFetchTasks(organizationId);

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

  if (status === `error`) {
    return (
      <Alert type={'error'}>
        Sorry, we encountered an error while fetching your tasks.
      </Alert>
    );
  }

  if (tasks.length === 0) {
    return <TasksEmptyState />;
  }

  return (
    <div className={'flex flex-col space-y-4'}>
      <div className={'flex justify-end'}>
        <CreateTaskButton>New Task</CreateTaskButton>
      </div>

      <TasksList tasks={tasks} />
    </div>
  );
};

function TasksEmptyState() {
  return (
    <div
      className={
        'flex flex-col items-center justify-center space-y-4' + ' h-full p-24'
      }
    >
      <div>
        <Heading type={5}>No tasks found</Heading>
      </div>

      <CreateTaskButton>Create your first Task</CreateTaskButton>
    </div>
  );
}

function CreateTaskButton(props: React.PropsWithChildren) {
  return <Button href={'/tasks/new'}>{props.children}</Button>;
}

export default TasksContainer;
```

The data above will automatically update when the `tasks` collection changes!

<Alert type="warn">
  <Alert.Heading>
    Hold on, we're not done yet!
  </Alert.Heading>

  Since the component "TaskListItem" is pretty complex and requires more files, we will define it separately. You will find it below after we explain the mutation hooks that the component will use.
</Alert>


Learn how to fetch data from Firestore in your React applications.

Firestore: Data Fetching


While `reactfire` does not provide hooks for writing data to Firestore, we can still make our own.

In fact, **I encourage you to make a custom hook for each mutation**.

## Mutations

#### Creating a Task

In the example below, we write a custom hook to add a document to the `tasks` collection:

```tsx title="src/lib/tasks/hooks/use-create-task.ts"
import { useFirestore } from 'reactfire';
import { useCallback } from 'react';
import { addDoc, collection } from 'firebase/firestore';
import { Task } from '~/lib/tasks/types/task';

function useCreateTask() {
  const firestore = useFirestore();
  const tasksCollection = collection(firestore, `/tasks`);

  return useCallback(
    (task: Task) => {
      return addDoc(tasksCollection, task);
    },
    [tasksCollection]
  );
}

export default useCreateTask;
```

The hook above returns a callback. Let's take a quick look at its usage:

```tsx
import useCreateTask from '~/lib/tasks/hooks/use-create-task';

function Component() {
  const createTask = useCreateTask();

  return <Form onCreate={task => createTask(task)} />
}
```

#### Updating a Task

Now, let's write a hook to update an existing task.

To update Firestore documents, we will import the function `updateDoc` from Firestore.

```tsx title="src/lib/tasks/hooks/use-update-task.ts"
import { useCallback } from 'react';
import { useFirestore } from 'reactfire';
import { doc, updateDoc } from 'firebase/firestore';
import { Task } from '~/lib/tasks/types/task';

function useUpdateTask(taskId: string) {
  const firestore = useFirestore();
  const tasksCollection = 'tasks';

  const docRef = doc(firestore, tasksCollection, taskId);

  return useCallback(
    (task: Partial<Task>) => {
      return updateDoc(docRef, task);
    },
    [docRef]
  );
}

export default useUpdateTask;
```

#### Deleting a Task

Finally, we write a mutation to delete a task:

```tsx title="src/lib/tasks/hooks/use-delete-task.ts"
import { useFirestore } from 'reactfire';
import { deleteDoc, doc } from 'firebase/firestore';
import { useCallback } from 'react';

function useDeleteTask(taskId: string) {
  const firestore = useFirestore();
  const collection = `tasks`;
  const task = doc(firestore, collection, taskId);

  return useCallback(() => {
    return deleteDoc(task);
  }, [task]);
}

export default useDeleteTask;
```

### Using the Modal component for confirming actions

The `Modal` component is excellent for asking for confirmation before performing a destructive action. In our case, we want the users to confirm before deleting a task.

The `ConfirmDeleteTaskModal` is defined below using the core `Modal` component:

```tsx title="src/components/tasks/ConfirmDeleteTaskModal.tsx"
import Modal from '~/core/ui/Modal';
import Button from '~/core/ui/Button';

const ConfirmDeleteTaskModal: React.FC<{
  isOpen: boolean;
  setIsOpen: (isOpen: boolean) => void;
  task: string;
  onConfirm: () => void;
}> = ({ isOpen, setIsOpen, onConfirm, task }) => {
  return (
    <Modal heading={`Deleting Task`} isOpen={isOpen} setIsOpen={setIsOpen}>
      <div className={'flex flex-col space-y-4'}>
        <p>
          You are about to delete the task <b>{task}</b>
        </p>

        <p>Do you want to continue?</p>

        <Button block color={'danger'} onClick={onConfirm}>
          Yep, delete task
        </Button>
      </div>
    </Modal>
  );
};

export default ConfirmDeleteTaskModal;
```

### Wrapping all up: listing each Task Item

Now that we have defined the mutations we can perform on each task item, we can wrap it up.

The component below represents a `task` item and allows users to mark it as `done` or `not done` - or delete them.

```tsx title="src/components/tasks/TasksListItem.tsx"
import { useCallback, useState } from 'react';
import Link from 'next/link';
import { TrashIcon } from '@heroicons/react/24/outline';
import toaster from 'react-hot-toast';
import { formatDistance } from 'date-fns';

import { Task } from '~/lib/tasks/types/task';
import Heading from '~/core/ui/Heading';
import IconButton from '~/core/ui/IconButton';
import Tooltip from '~/core/ui/Tooltip';
import useDeleteTask from '~/lib/tasks/hooks/use-delete-task';
import ConfirmDeleteTaskModal from '~/components/tasks/ConfirmDeleteTaskModal';
import useUpdateTask from '~/lib/tasks/hooks/use-update-task';

const TasksListItem: React.FC<{
  task: WithId<Task>;
}> = ({ task }) => {
  const getTimeAgo = useTimeAgo();
  const deleteTask = useDeleteTask(task.id);
  const updateTask = useUpdateTask(task.id);

  const [isDeleting, setIsDeleting] = useState(false);

  const onDelete = useCallback(() => {
    const deleteTaskPromise = deleteTask();

    return toaster.promise(deleteTaskPromise, {
      success: `Task deleted!`,
      loading: `Deleting task...`,
      error: `Ops, error! We could not delete task`,
    });
  }, [deleteTask]);

  const onDoneChange = useCallback(
    (done: boolean) => {
      const promise = updateTask({ done });

      return toaster.promise(promise, {
        success: `Task updated!`,
        loading: `Updating task...`,
        error: `Ops, error! We could not update task`,
      });
    },
    [updateTask]
  );

  return (
    <>
      <div
        className={'rounded border p-4 transition-colors dark:border-black-400'}
      >
        <div className={'flex items-center space-x-4'}>
          <div>
            <Tooltip content={task.done ? `Mark as not done` : `Mark as done`}>
              <input
                className={'Toggle cursor-pointer'}
                type="checkbox"
                defaultChecked={task.done}
                onChange={(e) => {
                  return onDoneChange(e.currentTarget.checked);
                }}
              />
            </Tooltip>
          </div>

          <div className={'flex flex-1 flex-col space-y-0.5'}>
            <Heading type={5}>
              <Link
                className={'hover:underline'}
                href={`/tasks/[id]`}
                as={`/tasks/${task.id}`}
                passHref
              >
                {task.name}
              </Link>
            </Heading>

            <div>
              <p className={'text-xs text-gray-400 dark:text-gray-500'}>
                Due {getTimeAgo(new Date(task.dueDate))}
              </p>
            </div>
          </div>

          <div className={'flex justify-end'}>
            <Tooltip content={`Delete Task`}>
              <IconButton
                onClick={(e) => {
                  e.stopPropagation();
                  setIsDeleting(true);
                }}
              >
                <TrashIcon className={'h-5 text-red-500'} />
              </IconButton>
            </Tooltip>
          </div>
        </div>
      </div>

      <ConfirmDeleteTaskModal
        isOpen={isDeleting}
        setIsOpen={setIsDeleting}
        task={task.name}
        onConfirm={onDelete}
      />
    </>
  );
};

export default TasksListItem;

function useTimeAgo() {
  return useCallback((date: Date) => {
    return formatDistance(date, new Date(), {
      addSuffix: true,
    });
  }, []);
}
```

Learn how to write data to Firestore in your React applications.

Firestore: Data Writing


Now that we have created a custom hook to write data to Firestore, we need to build a form to create a new `task`.

The example below is straightforward:
1. We have a form with two input fields
2. When the form is submitted, we read the data using `FormData`
3. Finally, we add the document using the callback returned by the hook `useCreateTask`

```tsx title="components/tasks/CreateTaskForm.tsx"
import { useRouter } from 'next/router';
import { FormEventHandler, useCallback } from 'react';
import toaster from 'react-hot-toast';

import TextField from '~/core/ui/TextField';
import Button from '~/core/ui/Button';
import If from '~/core/ui/If';
import Heading from '~/core/ui/Heading';

import useCreateTask from '~/lib/tasks/hooks/use-create-task';
import { useRequestState } from '~/core/hooks/use-request-state';
import { useCurrentOrganization } from '~/lib/organizations/hooks/use-current-organization';

const CreateTaskForm = () => {
  const createTask = useCreateTask();
  const { setLoading, state } = useRequestState();
  const router = useRouter();
  const organization = useCurrentOrganization();
  const organizationId = organization?.id as string;

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

      const target = event.currentTarget;
      const data = new FormData(target);
      const name = data.get('name') as string;

      const dueDate = (data.get('dueDate') as string) || getDefaultDueDate();

      setLoading(true);

      const task = {
        organizationId,
        name,
        dueDate,
        description: ``,
        done: false,
      };

      await toaster.promise(createTask(task), {
        success: `Task created!`,
        error: `Ops, error!`,
        loading: `Creating task...`,
      });

      await router.push(`/tasks`);
    },
    [router, createTask, organizationId, setLoading]
  );

  return (
    <div className={'flex flex-col space-y-4'}>
      <div>
        <Heading type={2}>Create a new Task</Heading>
      </div>

      <form onSubmit={onCreateTask}>
        <div className={'flex flex-col space-y-3'}>
          <TextField.Label>
            Name
            <TextField.Input
              required
              name={'name'}
              placeholder={'ex. Launch on IndieHackers'}
            />
            <TextField.Hint>Hint: whatever you do, ship!</TextField.Hint>
          </TextField.Label>

          <TextField.Label>
            Due date
            <TextField.Input name={'dueDate'} type={'date'} />
          </TextField.Label>

          <div
            className={
              'flex flex-col space-y-2 md:space-y-0 md:space-x-2' +
              ' md:flex-row'
            }
          >
            <Button loading={state.loading}>
              <If condition={state.loading} fallback={<>Create Task</>}>
                Creating Task...
              </If>
            </Button>

            <Button color={'transparent'} href={'/tasks'}>
              Go back
            </Button>
          </div>
        </div>
      </form>
    </div>
  );
};

function getDefaultDueDate() {
  const date = new Date();
  date.setDate(date.getDate() + 1);
  date.setHours(23, 59, 59);

  return date.toDateString();
}

export default CreateTaskForm;
```


Learn how to build forms in the Next.js Firebase kit

Forms


Now that we have some components to display, we need to add them to the actual Next.js pages.

If you have not created the files in the `Routing` section above, it's time to do it.

#### Using the RouteShell component

The RouteShell component is a wrapper around your internal application pages. This component will:

1. Automatically protect pages when the user is not authenticated
2. Initializes the Firestore provider on the page
3. Wraps the page with one of the two layouts available: `Sidebar` or `Top Header`

```tsx {9,15}
import { ArrowLeftIcon } from "@heroicons/react/24/outline";
import Heading from "~/core/ui/Heading";
import Button from "~/core/ui/Button";
import ErrorBoundary from "~/core/ui/ErrorBoundary";
import Alert from "~/core/ui/Alert";

const TaskPage: React.FC<{ taskId: string }> = ({ taskId }) => {
  return (
    <RouteShell title={<TaskPageHeading />}>
      <ErrorBoundary
        fallback={<Alert type={'error'}>Ops, an error occurred :</Alert>}
      >
        <TaskItemContainer taskId={taskId} />
      </ErrorBoundary>
    </RouteShell>
  );
};

function TaskPageHeading() {
  return (
    <div className={'flex items-center space-x-6'}>
      <Heading type={4}>
        <span>Task</span>
      </Heading>

      <Button size={'small'} color={'transparent'} href={'/tasks'}>
        <ArrowLeftIcon className={'mr-2 h-4'} />
        Back to Tasks
      </Button>
    </div>
  );
}

export default TaskPage;
```

#### Protecting Internal Pages with Route Guards

When we create an internal page that should be protected using authentication, we need to use a Makerkit function named `withAppProps`.

This function is a `server-side props function` that takes the context `ctx` as a parameter:

```tsx {20-24}
import { GetServerSidePropsContext } from "next";

import RouteShell from `~/components/RouteShell`;
import { withAppProps } from '~/lib/props/with-app-props';
import ErrorBoundary from "~/core/ui/ErrorBoundary";
import Alert from "~/core/ui/Alert";

const TaskPage: React.FC<{ taskId: string }> = ({ taskId }) => {
  return (
    <RouteShell title={<TaskPageHeading />}>
      <ErrorBoundary
        fallback={<Alert type={'error'}>Ops, an error occurred :</Alert>}
      >
        <TaskItemContainer taskId={taskId} />
      </ErrorBoundary>
    </RouteShell>
  );
};

export function getServerSideProps(
  ctx: GetServerSidePropsContext
) {
  return withAppProps(ctx);
}
```

The `withAppProps` function will:

1. return the current user data (both Auth and Firestore)
2. return the selected user's authentication
3. return the page's translations
4. return a CSRF token

```tsx
interface PageProps {
  session?: Maybe<AuthUser>;
  user?: Maybe<UserData>;
  organization?: Maybe<WithId<Organization>>;
  csrfToken?: string;
  ui?: UIState;
}
```

Additionally, it will validate the current session:

1. Is the user onboarded? Otherwise, redirect to the onboarding flow
2. Does the user exist? Otherwise, redirect the user back to the login page
3. Is the session cookie valid? Otherwise, redirect the user back to the login page

You can extend this function and add any additional validation you deem needed.

Learn how to create and manage application pages in your Makerkit app

Application Pages


Makerkit provides some utilities to reduce the boilerplate needed to write Next.js API functions. This section will teach you everything you need to know to write your API functions.

As you may know, we write Next.js' API functions at `pages/api`. Therefore, every file listed in this folder becomes a callable HTTP function.

For example, we can write the file `pages/api/hello-world.ts`:

```tsx title="pages/api/hello-world.ts"
export default function helloWorldHandler(
  req: NextApiRequest,
  res: NextApiResponse,
) {
  res.send(`Hello World`);
}
```

This API endpoint will simply return `Hello World`.

### Calling API functions from the client

To make requests to the API functions in the `api` folder, we provide a
custom hook `useApiRequest`, a wrapper around `fetch`.

It has the following functionality:

1. Uses an internal `state` to keep track of the state of the request, like
`loading`, `error` and `success`. This helps you write fetch requests the
"hooks way"
2. Automatically adds a `Firebase AppCheck Token` to the request headers if you
enabled Firebase AppCheck
3. Automatically adds a `CSRF token` to the request headers

Similarly to making Firestore Requests, it's a convention to create a custom
hook for each request for readability/reusability reasons.

```tsx title="src/core/hooks/use-create-session.ts"
import useSWRMutation from "swr/mutation";
import { useApiRequest } from '~/core/hooks/use-api';

interface Body {
  idToken: string;
}

export function useCreateSession() {
  const endpoint = '/api/session/sign-in';
  const fetcher = useApiRequest<void, Body>();

  return useSWRMutation(endpoint, (path, { arg }: { arg: Body }) => {
    return fetcher({
      path,
      body: arg,
    });
  });
}
```

As you can see above, we're using SWR, a popular library for data fetching. We

You can use this hook in your components:

```tsx
import { useCreateSession } from '~/core/hooks/use-create-session';

function Component() {
  const { trigger, error, isMutating, data } = useCreateSession();

  return (
    <>
      { isMutating ? `Loading...` : null }
      { error ? `Error :(` : null }
      { data ? `Yay, success!` : null }

      <SignInForm onSignIn={(idToken) => trigger({ idToken })} />
    </>
  );
}
```

Similarly, you can also use it to fetch data. Below, is an example for fetching data using SWR:

```tsx
import type { User } from 'firebase/auth';
import useSWR from 'swr';

import { useApiRequest } from '~/core/hooks/use-api';

/**
 * @name useFetchOrganizationMembersMetadata
 * @param organizationId
 */
export function useFetchOrganizationMembersMetadata(organizationId: string) {
  const endpoint = getFetchMembersPath(organizationId);
  const fetcher = useApiRequest<User[]>();

  return useSWR(endpoint, (path) => {
    return fetcher({ path, method: 'GET' });
  });
}

function getFetchMembersPath(organizationId: string) {
  return `/api/organizations/${organizationId}/members`;
}
```

And below, we're using the hook in a component:

```tsx
import { Trans } from "next-i18next";
import Alert from "~/core/ui/Alert";
import LoadingMembersSpinner from "~/core/ui/LoadingMembersSpinner";

function MembersListComponent() {
  const {
    data: members,
    isLoading: loading,
    error,
  } = useFetchOrganizationMembersMetadata(organizationId);

  if (loading) {
    return (
      <LoadingMembersSpinner>
        <Trans i18nKey={'organization:loadingMembers'} />
      </LoadingMembersSpinner>
    );
  }

  if (error) {
    return (
      <Alert type={'error'}>
        <Trans i18nKey={'organization:loadMembersError'} />
      </Alert>
    );
  }

  // display members using "members"
  return <>...</>;
}

```

#### Writing your own Fetch Hook

You are free to use your own implementation for sending HTTP requests to your API or use a powerful third-party library.

With that said, you need to ensure that you're sending the required headers:
1. The AppCheck token (if you use Firebase AppCheck)
2. The CSRF Token (for POST requests)

##### Generating an App Check Token

To generate an App Check token, you can use the `useGetAppCheckToken` hook:

```tsx
const getAppCheckToken = useGetAppCheckToken();
const appCheckToken = await getAppCheckToken();

console.log(appCheckToken) // token
```

You will need to send a header `X-Firebase-AppCheck` with the resolved value returned by the promise `getAppCheckToken()`.

##### Sending the CSRF Token

To retrieve the page's CSRF token, you can use the `useGetCsrfToken` hook:

```tsx
const getCsrfToken = useGetCsrfToken();
const csrfToken = getCsrfToken();

console.log(csrfToken) // token
```

You will need to send a header `x-csrf-token` with the value returned by `getCsrfToken()`.

### Piping utilities

Makerkit uses a dead-simple utility to pipe functions named `withPipe`. We can pass any `function` to this utility, which will iterate over its parameters and execute each.

Each function must be a Next.js handler that accepts the `req` and `res` objects. Let's take a look at the below:

```tsx
import {NextApiRequest, NextApiResponse } from "next";

import { withPipe } from '~/core/middleware/with-pipe';
import { withAuthedUser } from '~/core/middleware/with-authed-user';
import { withMethodsGuard } from '~/core/middleware/with-methods-guard';
import { withExceptionFilter } from '~/core/middleware/with-exception-filter';
import { withAppCheck } from '~/core/middleware/with-app-check';

export default function members(
  req: NextApiRequest,
  res: NextApiResponse
) {
  const handler = withPipe(
    withMethodsGuard(['POST']),
    withAuthedUser,
    withAppCheck,
    membersHandler
  );

  return withExceptionFilter(req, res)(handler);
}

function membersHandler(
  req: NextApiRequest,
  res: NextApiResponse
) {
  // API logic
}
```

What happens? We've passed 4 functions to the `withPipe` utility. The utility iterates over each of them. So it will execute `withMethodsGuard`, `withAuthedUser`, `withAppCheck`, and if everything went well during the checks, it will run the API logic we define in `membersHandler`.

1. `withMethodsGuard` checks if the method passed is supported
2. `withAuthedUser` checks if the user is authenticated
3. `withAppCheck` executes a Firebase App Check validation to prevent abuse
4. `membersHandler` is the actual logic of the API endpoint

### API Authentication

To validate that API functions are called by users authenticated with Firebase Auth, we use `withAuthedUser`.

This function will:

1. Initialize the Firebase Admin - this is always needed when using Firebase!
2. Get the user using the `session` cookie
3. Throw an error when not authenticated

By using this function, **we ensure all the following functions will not be executed unless the user is authenticated**.

```tsx
import {NextApiRequest, NextApiResponse } from "next";
import { withPipe } from "~/core/middleware/with-pipe";
import { withAuthedUser } from "~/core/middleware/with-authed-user";
import { withExceptionFilter } from '~/core/middleware/with-exception-filter';

export default function members(
  req: NextApiRequest,
  res: NextApiResponse
) {
  const handler = withPipe(
    withAuthedUser,
    membersHandler
  );

  return withExceptionFilter(req, res)(handler);
}

function membersHandler(
  req: NextApiRequest,
  res: NextApiResponse
) {
  // API logic
}
```

### CSRF Token check

We must pass a `CSRF token` when using POST requests to prevent malicious attacks. To do so, we use the pipe `withCsrfToken`.

1. The CSRF token is generated when the page is server-rendered
2. The CSRF token is stored in a `meta` tag
3. The CSRF token is sent to an HTTP POST request automatically when using the `useApiRequest` hook
4. This function will throw an error when the token is invalid

By using this function, **we ensure all the following functions will not be executed unless the token is valid**.

```tsx
import { NextApiRequest, NextApiResponse } from "next";
import { withPipe } from "~/core/middleware/with-pipe";
import { withAuthedUser } from "~/core/middleware/with-authed-user";
import { withExceptionFilter } from '~/core/middleware/with-exception-filter';
import withCsrfToken from '~/core/middleware/with-csrf';

export default function members(
  req: NextApiRequest,
  res: NextApiResponse
) {
  const handler = withPipe(
    withAuthedUser,
    withCsrfToken,
    membersHandler
  );

  return withExceptionFilter(req, res)(handler);
}

function membersHandler(
  req: NextApiRequest,
  res: NextApiResponse
) {
  // API logic
}
```

### Firebase App Check

App Check is a Firebase service that helps you to protect your web app from
bots, spammy users, and general abuse detected by Google's Recaptcha.

[Check out the documentation to setup Firebase App Check](/docs/app-check).

Using the `withAppCheck` pipe, **we ensure all the following functions will not be executed unless the App Check token is valid**.

```tsx
import {NextApiRequest, NextApiResponse } from "next";
import { withPipe } from "~/core/middleware/with-pipe";
import { withAuthedUser } from "~/core/middleware/with-authed-user";
import { withExceptionFilter } from '~/core/middleware/with-exception-filter';
import withCsrfToken from '~/core/middleware/with-csrf';

export default function members(
  req: NextApiRequest,
  res: NextApiResponse
) {
  const handler = withPipe(
    withAuthedUser,
    withCsrfToken,
    withCsrfToken,
    membersHandler
  );

  return withExceptionFilter(req, res)(handler);
}

function membersHandler(
  req: NextApiRequest,
  res: NextApiResponse
) {
  // API logic
}
```

### Catching and Handling Exceptions

To catch and gracefully handle API exceptions, we use the function `withExceptionFilter`.

As seen from its usage above, we wrap the API function within the utility. When errors are caught, this function will:

1. Log and debug the error to the console
2. Report the error to Sentry (if configured)
3. Return an object stripping the error's data to avoid leaking information

### API Logging

The boilerplate uses `Pino` for API logging, a lightweight logging utility for Node.js.

Logging is necessary to debug your applications and understand what happens when things don't behave as expected. You will find various instances of logging throughout the API, but we encourage you to log more if necessary.

We import the logging utility from `~/core/logger`.

Typically, you can log every time you perform an action, both before and after.

For example:

```tsx
import logger from '~/core/logger';

async function myFunction(params: {
  organizationId: string;
  userId: string;
}) {
  logger.info(
    {
      organizationId: params.organizationId,
      userId: params.userId,
    },
    `Performing action...`
  );

  await performAction();

  logger.info(
    {
      organizationId: params.organizationId,
      userId: params.userId,
    },
    `Action successful`
  );
}

async function performAction() {
  // do something complex here
}
```

It's always important to add context to your logs: as you can see, we use the first parameter to add important information.

Learn how to create and manage API routes in your Next.js application.

API Routes


Validating payloads is necessary to ensure your API endpoints receive the expected data. To validate the API, we use Zod.

[Zod](https://github.com/colinhacks/zod) is a Typescript library that helps us
secure our API endpoints by validating the payloads sent
from the client and also facilitating the typing of the payload with
Typescript.

Using Zod is the first line of defense to validate the data sent against our
API: as a result, it's something we recommend you keep doing. It ensures we
write safe, resilient, and valid code.

When we write an API endpoint, we first define the schema of the payload:

```tsx
function getBodySchema() {
  return z.object({
    displayName: z.string(),
    email: z.string().email(),
  });
}
```

This function represents the schema, which will validate the following
interface:

```tsx
interface Body {
  displayName: string;
  email: Email;
}
```

Now, let's write the body of the API handler that validates the body of the
function, which we expect to be equal to the `Body` interface.

```tsx
import { throwBadRequestException } from `~/core/http-exceptions`;

function inviteMemberHandler(
  req: NextApiRequest,
  res: NextApiResponse,
) {
  try {
     // we can safely use data with the interface Body
    const schema = getBodySchema();
    const { displayName, email } = schema.parse(req.body);

    return sendInvite({ displayName, email });
  } catch(e) {
    return throwBadRequestException(res);
  }
}

export default function apiHandler() {
  const handler = withPipe(
    withMethodsGuard(['POST']),
    withAuthedUser,
    inviteMemberHandler,
  );

  // manage exceptions
  return withExceptionFilter(req, res)(handler);
}
```

I encourage you to **never skip the validation step when writing your API endpoints**.


The best practices to validate your API routes payloads using Zod in your Next.js Firebase application.

API Routes Validation


Most strings in the Makerkit template's application use `next-18n`, a library to translate your application into multiple languages. Thanks to this library, we can store all the application's text in `json` files for each supported language.

For example, if you are serving your application in English and Spanish, you'd have the following files:

- **English** translation files at `/public/locales/en/{file}.json`
- **Spanish** translation files at `/public/locales/es/{file}.json`

There are valid reasons to use translation files, even if you are not planning on translating your application, such as:

1. it's easier to search and replace text
2. tidier render functions
3. easy update path if you do decide to support a new language

### Adding new languages

By default, Makerkit uses English for translating the website's text. All the files are stored in the files at `/public/locales/en`.

Adding a new language is very simple:
1. **Translation Files**: First, we need to create a new folder, such as `/public/locales/es`, and then copy over the files from the English version and start translating files.
2. **Next.js i18n config**: We need to also add a new language to the Next.js configuration at `next-i18next.config.js`. Simply add your new language's code to the `locales` array.

The configuration will look like the below:

```js
const config = {
  i18n: {
    defaultLocale: DEFAULT_LOCALE,
    locales: [DEFAULT_LOCALE, 'es'],
  },
  fallbackLng: {
    default: [DEFAULT_LOCALE],
  },
  localePath: resolve('./public/locales'),
};
```

#### Setting the default Locale

To set the default locale, simply update the environment variable `DEFAULT_LOCALE` stored in `.env`.

So, open the `.env` file, and update the variable:

```txt title=".env"
DEFAULT_LOCALE=de
```

### Using the Language Switcher component

The Language switcher component will automatically retrieve and translate the languages listed in your configuration.

When the user changes language, it will update the URL to reflect the user's preferences and rerender the application with the selected language.

<Video src="/assets/images/posts/language-selector.mp4" />

NB: The language selector is not added to the application by default; you will need to import it where you want to place it.


Learn how to easily translate your Next.js Firebase Makerkit SaaS into multiple languages with our guide. Optimize your app and reach a wider audience.

Translations


This is an extremely important section of the documentation: it will teach you the most important functions you need to know to use the Next.js Firebase kit effectively.

We will cover both client-side and server-side functions.

## Client-Side Functions

### ReactFire Hooks

The Next.js Firebase kit uses [ReactFire](https://github.com/firebaseextended/reactfire) extensively throughout the kit. ReactFire is a library that allows you to bind Firebase data to React components. This allows you to easily display data from Firebase in your React components.

For the majority of use cases, you will be using Reactfire's React hooks to interact with your Firebase data, as we've seen in the previous sections.

These include:
- `useFirestore`: this will allow you to interact with your Firestore database
- `useAuth`: this will allow you to interact with your Firebase authentication
- `useStorage`: this will allow you to interact with your Firebase storage (you are required to add the FirebaseStorageProvider above your component tree for this to work)

### Makerkit Hooks

#### 1. `useCurrentOrganization`: getting the current user organization

This hook will allow you to get the current user organization. It is populated with the data fetched server-side in the `getServerSideProps` function, and is injected using the Context API.

For example, let's see how we can use this hook to get the current user organization name:

```ts
import { useCurrentOrganization } from '~/lib/organizations/hooks/use-current-organization';

export function useCurrentOrganizationName() {
  const organization = useCurrentOrganization();

  return organization?.name;
}
```

There are a variety of other hooks that you can use to get the current user organization data. You can find them in the `~/lib/organizations/hooks` folder.

#### 2. `useCurrentUserRole`: getting the current user role within the current organization

In case you need to access the current user role within the current organization, you can use the `useCurrentUserRole` hook.

For example, let's see how we can use this hook to get the current user role within the current organization:

```tsx
import { useCurrentUserRole } from '~/lib/organizations/hooks/use-current-user-role';

function MyComponent() {
  const role = useCurrentUserRole();

  return (
    <div>
      <p>Current user role: {role}</p>
    </div>
  );
}
```

#### 3. `useUserSession`: getting the current user session information

In case you need to access the current user session data, you can use the `useUserSession` hook.

This hook will return the current user session data, which includes the following information:
- `auth`: the data that comes from Firebase Authentication
- `data`: the data that comes from the user's Firestore document

```tsx
export interface UserSession {
  auth: AuthUser | undefined;
  data: UserData | undefined;
}
```

For example, let's see how we can use this hook to get the current user ID:

```tsx
import { useUserSession } from '~/core/hooks/use-user-session';

function MyComponent() {
  const userSession = useUserSession();
  const userId = userSession?.auth?.uid;

  return (
    <div>
      <p>Current user ID: {userId}</p>
    </div>
  );
}
```

#### 4. `useIsSubscriptionActive`: getting the current organization subscription status and checking if it's active

A subscription is considered active if it's either `active` or `trialing`. The `useIsSubscriptionActive` hook will return `true` if the current organization is on any paid subscription, regardless of plan.

This can be useful if you want to display a message to the user if they are on a paid subscription, or if you want to restrict access to certain pages.

You can customize this hook to fit your needs.

```tsx
import type { Stripe } from 'stripe';
import { useCurrentOrganization } from '~/lib/organizations/hooks/use-current-organization';

const ACTIVE_STATUSES: Stripe.Subscription.Status[] = ['active', 'trialing'];

/**
 * @name useIsSubscriptionActive
 * @description Returns whether the organization is on any paid
 * subscription, regardless of plan.
 */
function useIsSubscriptionActive() {
  const organization = useCurrentOrganization();
  const status = organization?.subscription?.status;

  if (!status) {
    return false;
  }

  return ACTIVE_STATUSES.includes(status);
}

export default useIsSubscriptionActive;
```

## Server-Side Functions

### Props Functions

Props functions are functions that are executed server-side and are used to populate the props of a page. They are executed before the page is rendered, and are used to fetch data that is required for the page to render.

#### 1. `withAppProps`: populating the application pages data

The `withAppProps` function is used to populate the props of the application pages. It is used in the `getServerSideProps` function of the pages you want to gate.

If you take a look at the previous sections, we used this function to protect the `tasks` application so that only authenticated users can access it.

```tsx
import { withAppProps } from "~/lib/props/with-app-props";
import { GetServerSidePropsContext } from "next";

export async function getServerSideProps(ctx: GetServerSidePropsContext) {
  return await withAppProps(ctx);
}
```

#### 2. `withTranslationsProps`: populating the application translations

This function is used to populate the translations of the application. All the other props functions include this by default, so you don't need to use it directly unless it's on a page that does not use any of the other ones.

You will be using this for the majority of your marketing pages.

```tsx
import { withTranslationProps } from "~/lib/props/with-translation-props";
import { GetStaticPropsContext } from "next";

export async function getStaticProps(
  context: GetStaticPropsContext
) {
  const { props } = await withTranslationProps(context);

  return {
    props,
  };
}
```

#### 3. `withAuthProps`: populating the authentication pages data

The `withAuthProps` function is used to populate the props of the authentication pages. You may never need to use it unless you introduce new authentication pages.

This function is used in the `getServerSideProps` function of the authentication pages.

```tsx
import { withAuthProps } from "~/lib/props/with-auth-props";
import { GetServerSidePropsContext } from "next";

export async function getServerSideProps(ctx: GetServerSidePropsContext) {
  return await withAuthProps(ctx);
}
```

This function ensures **authenticated users won't be able to access the authentication pages**.

### API Functions

API Routes have several utilities that help you build your API endpoints, and save you from writing boilerplate code.

#### 1. `withPipe`: piping functions when handling API requests

The `withPipe` function is used to pipe functions when handling API requests.

```ts {12}
import { NextApiRequest, NextApiResponse } from "next";

import { withAuthedUser } from '~/core/middleware/with-authed-user';
import { withPipe } from '~/core/middleware/with-pipe';
import { withMethodsGuard } from '~/core/middleware/with-methods-guard';
import { withExceptionFilter } from '~/core/middleware/with-exception-filter';

export default function helloWorld(
  req: NextApiRequest,
  res: NextApiResponse
) {
  const handler = withPipe(
    withMethodsGuard(['GET']),
    withAuthedUser,
    (req, res) => {
      res.status(200).json({ message: 'Hello World!' });
    }
  );

  return withExceptionFilter(req, res)(handler);
}
```

This helps you write the utility functions we will see next in a more readable way.

#### 2. `withMethodsGuard`: guarding API endpoints by HTTP methods

The `withMethodsGuard` function is used to guard API endpoints by HTTP methods. For example, in the example below, we only allow `GET` and `POST` requests to the `/api/hello-world` endpoint.

```ts {13}
import { NextApiRequest, NextApiResponse } from "next";

import { withAuthedUser } from '~/core/middleware/with-authed-user';
import { withPipe } from '~/core/middleware/with-pipe';
import { withMethodsGuard } from '~/core/middleware/with-methods-guard';
import { withExceptionFilter } from '~/core/middleware/with-exception-filter';

export default function helloWorld(
  req: NextApiRequest,
  res: NextApiResponse
) {
  const handler = withPipe(
    withMethodsGuard(['GET', 'POST']),
    withAuthedUser,
    (req, res) => {
      res.status(200).json({ message: 'Hello World!' });
    }
  );

  return withExceptionFilter(req, res)(handler);
}
```

#### 3. `withAuthedUser`: require authentication to access an API endpoint

The `withAuthedUser` function is used to require authentication to access an API endpoint. It will return a `401` error if the user is not authenticated.

```ts {12}
import { NextApiRequest,NextApiResponse } from "next";

import { withAuthedUser } from '~/core/middleware/with-authed-user';
import { withPipe } from '~/core/middleware/with-pipe';
import { withExceptionFilter } from '~/core/middleware/with-exception-filter';

export default function helloWorld(
  req: NextApiRequest,
  res: NextApiResponse
) {
  const handler = withPipe(
    withAuthedUser,
    (req, res) => {
      res.status(200).json({ message: 'Hello World!' });
    }
  );

  return withExceptionFilter(req, res)(handler);
}
```

#### 4. `withExceptionFilter`: handle exceptions in API endpoints

The `withExceptionFilter` function is used to handle exceptions in API endpoints. It will log errors and report to Sentry when errors are encountered.

```ts {18}
import { NextApiRequest,NextApiResponse } from "next";

import { withAuthedUser } from '~/core/middleware/with-authed-user';
import { withPipe } from '~/core/middleware/with-pipe';
import { withExceptionFilter } from '~/core/middleware/with-exception-filter';

export default function helloWorld(
  req: NextApiRequest,
  res: NextApiResponse
) {
  const handler = withPipe(
    withAuthedUser,
    (req, res) => {
      res.status(200).json({ message: 'Hello World!' });
    }
  );

  return withExceptionFilter(req, res)(handler);
}
```

#### 5. `withCsrf`:  protect API endpoints from CSRF attacks

The `withCsrf` function is used to protect API endpoints from CSRF attacks. It will return a `403` error if the CSRF token is invalid.

```ts {10}
import { NextApiRequest,NextApiResponse } from "next";

import { withAuthedUser } from '~/core/middleware/with-authed-user';
import { withPipe } from '~/core/middleware/with-pipe';
import { withExceptionFilter } from '~/core/middleware/with-exception-filter';
import { withCsrf } from '~/core/middleware/with-csrf';

export default function owner(req: NextApiRequest, res: NextApiResponse) {
  const handler = withPipe(
    withCsrf(),
    withAuthedUser,
    (req, res) => {
      res.status(200).json({ message: 'Hello World!' });
    }
  );

  return withExceptionFilter(req, res)(handler);
}
```

Learn the most important functions you need to know to use the Next.js Firebase kit effectively.

Functions you need to know


Adding pages to the Marketing Site is easy.

You can add a new page by creating a new file in the `pages` directory. For example, if you want to add a new page called `About`, you can create a new file called `about.tsx` in the `pages` directory.

```
pages/
  about.tsx
```

The file should export a React component that will be rendered when the user visits the page.

For example:

```tsx title="pages/about.tsx"
import { GetStaticPropsContext } from "next";
import { withTranslationProps } from "~/lib/props/with-translation-props";

function About() {
  return <div>About</div>;
}

export function getStaticProps(
  context: GetStaticPropsContext
) {
  return withTranslationProps(context);
}

export default About;
```

NB: We've added the `withTranslationProps` function to the `getStaticProps` function. This is required for all pages to ensure that the page is translated correctly.
If you don't add this function, the components that use translations will not be translated, and the component will not be rendered correctly.

### Adding a page to the navigation menu

To update the site's navigation menu, you can visit the `SiteNavigation.tsx` component and add a new entry to the menu.

By default, you will see the following object `links`:

```tsx title="components/SiteNavigation.tsx"
const links: Record<string, Link> = {
  Blog: {
    label: 'Blog',
    path: '/blog',
  },
  Docs: {
    label: 'Docs',
    path: '/docs',
  },
  Pricing: {
    label: 'Pricing',
    path: '/pricing',
  },
  FAQ: {
    label: 'FAQ',
    path: '/faq',
  },
};
```

The menu is defined in the render function:

```tsx
<NavigationMenu>
  <NavigationMenuItem link={links.Blog} />
  <NavigationMenuItem link={links.Docs} />
  <NavigationMenuItem link={links.Pricing} />
  <NavigationMenuItem link={links.FAQ} />
</NavigationMenu>
```

Assuming we want to add a new menu entry, say `About`, we would first add the link object:

```tsx
About: {
  label: 'About',
  path: '/about',
},
```

And then we update the menu:

```tsx
<NavigationMenu>
  <NavigationMenuItem link={links.About} />
  ...
</NavigationMenu>
```


Learn how to add pages to the Marketing Site of your Next.js Firebase application, and how to add them to the navigation menu.

Adding pages to the Marketing Site


We can add your website's blog posts within the `_posts` folder.

#### Collections

Before writing a blog post, we have to define the post's collection. We use `collections` to organize our blog posts by their category.

For example, your blog could have collections such as changelog,
announcements, tutorials, etc.

MakerKit generates every collection with its page, listing all the articles
associated with it.

To change a collection page, please change the file `src/pages/blog/[collection].ts`.

##### Adding collections

Let's see how we can define a `collection` in Typescript:

```tsx
interface Collection {
  name: string;

  // image
  logo?: string;
  emoji?: string;
}
````

As you can see, the only required property to create a collection is a name. You can also attach an image or a simple emoji for each `collection`.

A collection can be simply the following file:

```json
{
  "name":"Changelog"
}
```

#### Writing a Blog Post
The interface of a blog post is the following:

```tsx
interface Post {
  title: string;
  excerpt: string;

  date: string;
  live: boolean;
  tags?: string[];

  coverImage?: string;

  ogImage?: {
    url: string;
  };

  author?: {
    name: string;
    picture: string;
    url: string;
  };

  canonical?: string;
}
```

These values can be defined in MDX files using the `frontmatter`, for example:

```yaml
---
title: An Awesome Post title
except: "Write here a short description for your blog post"
collection: changelog.json
date: '2022-01-05'
live: true
coverImage: '/assets/images/posts/announcement.webp'
tags:
  - changelog
---
```


Learn how to add blog posts to your site.

Adding Blog Posts


We place the documentation pages within the `_docs` folder.

#### Topics

The pages are defined hierarchically so that you can define your
documentation in the following way:

```
- _docs
  - [topic]
    - [topic.json]
    - [page].mdx
```

The documentation you're reading, for example, is defined as follows.

The MakerKit kit has a folder called `_docs`: in this folder, we have a list of
sub-folders for each topic we are describing.

Each folder has a metadata file named `meta.json`:

```json
{
  "title": "Blog and Docs",
  "position": 2,
  "description": "Learn how to configure and write your product's Blog and Documentation"
}
```

The `position` property defines the order of the topics. In
the case above, the topic `Blog and Docs` will be the third topic in the list.

#### Topics Pages

Within each topic, we define the collection pages defined as MDX files.
They share the same components as the blog posts' files.

A page is defined as follows:

```yaml
---
title: Blog
position: 1
---
```

The `position` property defines the order in which the page is listed within
the topic.

Learn how to add documentation pages to your product's website

Adding Documentation pages


Before deploying to production or any remote server, you need to [follow all the steps outlined in the documentation](/docs/next-fire/going-to-production-overview).

**Much of the work below needs to be done externally**, not in the Makerkit codebase.

Generally, you will need to:

1. **Firebase**: Create a new Firebase project (database, storage bucket, getting the private keys)
2. **Security Rules**: Update the remote security rules (both Firestore and Storage)
3. **Environment Variables**: Ensure that your environment variables are set correctly, and that you've added the relevant environment variables to your hosting provider
4. **Auth**: Enable the authentication providers you want to use from the Firebase Console
5. **Indexes**: Update all the Firestore indexes required by your application in the Firebase Console
6. **SMTP**: Set up an SMTP server to send emails by adding the required configuration to `src/configuration.ts`
7. **Payments**: Set up your Stripe or Lemon Squeezy accounts and add the relevant environment variables
8. **Deployment**: Finally, deploy your application to your hosting provider (Vercel, Firebase, Netlify, etc.): please follow the instructions provided by your hosting provider to deploy a Next.js application.

Learn how to deploy your Next.js Firebase app to your hosting provider.

Deploying to Production


If you have followed the steps to set up Git at the beginning of this tutorial, you've already set the original Makerkit repository as `upstream`.

As the repository is constantly updated, it's recommended to fetch updates regularly. You can do so by running the following Git command:

```
git pull upstream main --allow-unrelated-histories
```

Unfortunately, you may need to resolve eventual conflicts.

### Any questions?

If you have questions, please join our [Discord Community](https://discord.gg/BeJSyQJ6jP), even if you have not purchased any kit. We chat and help each other build products.

Learn how to update your Makerkit repository to the latest version.

Updating to the latest version

Let's get started. Configure MakerKit and Firebase, and run the application for the first time!

Getting Started


MakerKit is **the Next.js boilerplate project for SaaS** built to get you started on the right foot.

MakerKit is a fully SSR-rendered Next.js application that uses Firebase for authentication, database (with Firestore), and storage.

MakerKit is ideal for any SaaS application or dynamic websites such as walled Online Publications.

It particularly shines when you wish to provide uniform navigation between your marketing site, documentation, and application.

## What does the boilerplate provide?

### Tech Stack

We built MakerKit with some of the best technologies available today, such as
Next.js, Tailwind, and Firebase:

- **Scalable Next.js** structure template, perfect for the most ambitious
projects
- Beautiful **Tailwind 3** CSS theme - with dark mode!
- **Full Firebase** setup with local emulators
- **Reusable UI components** as building blocks (which you can easily swap
with your own or your favorite library) based on [Radix UI](https://radix-ui.com)
- **SSR-compatible Authentication flow**, including 3rd-party providers (Google,
Facebook, Twitter, GitHub, etc.)

### Template Features

MakerKit is fully functioning from the beginning and comes with the
following features:

- **Payments** with Stripe, and support for **subscriptions** (or, alternatively, using Lemon Squeezy)
- **Onboarding flow**, which allows your users to set up their accounts and
create their organization
- **Organizations**: users can create and edit organizations. An organization is a group of users. You can rename the `Organization` entity according to your domain (for example, teams, projects, etc.)
- **Team Members**: users can invite other users to join their organization and assign them a role
- **MDX-powered Blog and Documentation** generators - already
**SEO-optimized** for you

### Marketing

Marketing matters! But don't get hung up on the technicalities. MakerKit provides:

- **Newsletter Sign-up form** for *ConvertKit*, but easy to adapt to more
providers
- **Google Analytics** script baked-in
- **Email Templates** you can write with React using [React.email]
(https://react.email)

### Debugging and Testing

Never waste time chasing bugs again.

Assuming you have created a Sentry account, MakerKit can catch exceptions (and possible bugs) and  report them to Sentry whenever they happen in both client and server-side code:

- **Error Tracking** set up with Sentry
- Comprehensive **E2E Tests** suite with Cypress, which you can use and learn
from

### After you buy

You're not going to be left alone. We offer help and support:

- Access to the team for feedback, requests, and general support. **We're here to support you build your SaaS**.

This documentation introduces each of the points above and guides you through
so that you can easily adjust MakerKit to your application's domain.

MakerKit has plenty of resources for using both Next.js and Firebase - and if you're stuck, you can always reach out to me for help.


Introduction to MakerKit: a SaaS starter built with Next.js and Firebase

Introduction to MakerKit: a SaaS boilerplate for Next.js and Firebase


MakerKit is built primarily with Next.js, Firebase, and Tailwind CSS.

Under the hood, there are many more libraries and architectural
decisions you should know.

### 1) A Scalable Next.js Application
The codebase is entirely built with [Next.js](https://nextjs.org) (version 13),
a popular React meta-framework created by the fine folks at [Vercel](https://vercel.com).

The front end is fully built with React, leveraging React Hooks
and the best practices available today.

The boilerplate is currently using the `pages` folder structure, but we're
actively working to support Server Components and **Layouts**.

### 2) Built on top of Firebase

[Firebase](https://firebase.com) is one of the most popular *PaaS* out there,
with a very generous free tier and fairly affordable pricing for growing
applications.

MakerKit uses Firebase for Authentication, Firestore for storing your data,
Storage for storing files, and AppCheck to protect your endpoints against
possible attacks.

### 3) Theme built with Tailwind 3

The bulk of the application's theme, built with [Tailwind 3](https://tailwindcss.com/), is
stored in three CSS files rather than HTML.

It may sound like a bad practice, but we approached this way to help you find and edit
the theme's CSS in one single place.

We designed the theme in light and dark, so you can choose to use both according to your user's OS settings or manage it using a local cookie.

### 4) Radix UI Components

All the kits use [Radix UI](https://radix-ui.com), arguably the best headless UI library for React.

The components are styled using Tailwind CSS. Many components are inspired by the template made by [Shad CN](https://ui.shadcn.com/). We recommend taking a look if you want to build your own components.

Some components are still using Headless UI, but will be phased out in the future.

### 5) Fully and Strictly Typed with Typescript

We wrote every single line of code with *strictly-typed
Typescript* both on the client and server side.

### 6) Payload validation with Zod

The API endpoints are **validated and protected with [Zod](https://github.com/colinhacks/zod)**, which also helps with strong-typing.

### 7) E2E testing with Cypress

We ship MakerKit with [Cypress](https://www.cypress.io/), likely the most
popular E2E testing framework.

We made lots of examples and utilities to change the tests as you develop
your application.

### 8) Linted with EsLint and formatted with Prettier

We lint the codebase with **a very strict EsLint configuration**, but
we distribute it with less strict params so that it won't be in your way
as you're experimenting with the starter.

We will show you how to add stricter parameters if that's your thing, but we do not recommend jumping head-in with it. It's much better to activate the stricter configuration once you have already shipped the product and are looking to stabilize it.

Furthermore, the codebase is **formatted with Prettier** automatically.

### 9) Multi-language by default with next-i18n

We configured the application to be translated by default thanks to the
[next-i18n](http://next-i18next.com) package.

All the application's strings are translated by default, so you can easily
extend it to other languages if necessary.

Using translation files can help you if you want to **translate your apps in multiple
languages**, but it also allows you to find the text strings you
want to replace.

In this way, you do not need to change strings in the codebase, but they're
**neatly organized in JSON files**.

### 10) Logging with Pino

MakerKit uses [Pino](https://github.com/pinojs/pino), a lightweight logging library.

API errors are logged with just enough information to help you debug
your API routes.


MakerKit uses Next.js, Firebase, Firestore, Tailwind CSS, Zod, Pino, Headless UI, Typescript and Cypress to build wonderful SaaS applications

The technologies that make up a MakerKit application


If you have bought a license for MakerKit, you have access to all the
repositories built by the MakerKit team. In this document, we will learn how
to fetch and install the codebase.

### Requirements

To get started with the Next.js and Firebase SaaS template, we need to ensure
you install the required software.

- Node.js (LTS recommended)
- Git
- Docker (optional but highly recommended)

### Cloning the repository

To get the codebase on your local machine, clone the repository with the
following command:

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

The command above clones the repository in the folder `my-saas` which
you can rename it with the name of your project.

### Initializing Git

Now, run the following commands for:

1. Moving into the folder
2. Reinitialize your git repository
3. Adding the original Makerkit repository as "upstream" so we can fetch updates from the main repository:

```
cd my-saas
rm -rf .git
git init
git remote add upstream git@github.com:makerkit/next-firebase-saas-kit.git
git add .
git commit -a -m "Initial Commit"
```

In this way, to fetch updates (after committing your files), simply run:

```
git pull upstream main --allow-unrelated-histories
```

You'll likely run into conflicts when running this command, so carefully choose the changes (sorry!).

### Installing the Node dependencies

Finally, we can install the NodeJS dependencies with `npm`:

```
npm i
```

While the application code is fully working, we now need to set up your Firebase
project.

So let's jump on to the next step!


Learn how to clone the MakerKit repository

Clone the MakerKit SaaS boilerplate repository


After installing the modules and the emulators, we can finally run the
application in development mode.

We need to execute two commands (and an optional one for Stripe):

1. **Next.js Server**: the first command is for running the Next.js server
2. **Firebase Emulators**: the second command is for running the Firebase
emulators
3. **Stripe CLI**: finally, the Stripe CLI is needed to dispatch webhooks to
our local server (optional, only needed when interacting with Stripe)

### Running the Firebase Emulators

First, let's run the emulators. The command below runs the emulators for
the following products: Authentication, Firestore, and Storage.

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

Additionally, it imports the default emulator's data from the folder `.
/firebase-seed`, which we set up upfront to run the Cypress tests.

After running the command above, you will be able to access the [Firebase
Emulators UI](https://firebase.google.com/docs/emulator-suite) at
[http://localhost:4000](http://localhost:4000).

### Running the Next.js Server

And now, the Next server:

```bash
next run dev
```

If everything goes well, your server should be running at
[http://localhost:3000](http://localhost:3000).

### Running the Stripe CLI

Run the Stripe CLI with the following command:

```bash
next run stripe:listen
```

#### Add the Stripe Webhooks Key to your environment file

If this is the first time you run this command, you will need to copy the Webhooks key printed on the console and add it to your development environment variables file:

```bash title=".env.development"
STRIPE_WEBHOOKS_KEY=<PASTE_KEY_HERE>
```

## Saving the Firebase Emulator's data

After shutting the emulators down, the Firebase emulator clears all the records
and the users added during the session while the emulators are running.

Fortunately, we can save and restore as many dumps as we want. For example, this can be useful for saving and loading particular scenarios for testing.

To save the current snapshot, run the following command while the emulators are up and running:

```bash
npm run firebase:emulators:export
```

By default, MakerKit imports and exports to `./firebase-seed`, but you can change this to any other path.

### Always Save on exit

We don't particularly recommend this, but if you want to keep persisting data as you exit the emulators,
you can decorate the `firebase:emulators:start` with the following options:

```bash
firebase emulators:start --export-on-exit=./your-directory
```

Saving your emulators' state can be handy, but keep in mind that for testing reasons,
it's always best to create a snapshot of your data and use the same one so that your tests won't break if the data changes.

Of course, change `./your-directory` to your preferred path.


How to run a Next.js and Firebase MakerKit application


## React.FC vs React.FCC

Since React 18, `React.FC` no longer implies that components can accept a `children` prop. The alternative to that is using the interface `React.FC<React.PropsWithChildren<{}>>`, which is a bit long.

`React.FCC` is a shorthand that includes `children` as a possible property that works similarly to how it used to work. When a component needs `children`, `React.FCC` is preferred since it's faster to type.

## Exporting functions vs constants

We use both conventions in the boilerplate, i.e., exporting functions as components and constants.

My general rule is the following:

- if it's the exported component, use `const` typed with `React.FC` or `React.FCC`
- if it's not exported, use `function` since my personal preference is to define functions below the exported component

NB: sometimes, that may not be the case, and that's not necessarily intentional. The two constructs are essentially the same in most cases.

## Why is useCallback used in most components?

Most functions defined within a render function use `useCallback`. In my experience, this is the better default to avoid re-renders that I can't immediately explain.

Whether you want to adhere to this convention is totally up to you; just be aware of the potential issues.

## Interfaces, Types, and Inline 

I've gone through phases, so you may find some types defined as `type` and others as `interface`. I've since realized that I prefer `interface`, but you will find some instance that uses `type`.

Inline types are typically only defined when the type isn't reused anywhere. For example, when defining a function that accepts parameters as objects.

## Function parameters

I adhere to the principle that if a function accepts multiple parameters of the same type, then use an object. Unfortunately, Typescript can't save us if the types match.

Consider the example below:

```tsx
function makeDiv(width: number, height: number) {}

const height = 10;
const width = 40;

// correct according to TS, not in practice!
const div = makeDiv(height, width);
```

Now we rewrite it using an object:

```tsx
function makeDiv(params: { width: number, height: number}) {}

const height = 10;
const width = 40;

// Okay, now it looks better!
const div = makeDiv({ height, width });
```

## Custom React Hooks

The boilerplate uses Custom React Hooks when:

- fetching/writing using an API function
- fetching/writing using Firestore
- fetching/writing using Storage

It makes the code more understandable and reusable.

An explanation of the coding conventions used in the boilerplate

SaaS template Coding Conventions

Configuration


We store the global configuration of a MakerKit application in `/configuration.ts`.

Within any application file, we can use the path `~/configuration` to
import it from any other file.

<Alert type='info'>
You do not need any changes to start developing your application. Feel free
to complete the configuration once you want to deploy the app for the first
time.
</Alert>

The configuration has the following structure:

```tsx title="configuration.ts"
export default {
  site: {
    title: '',
    description: '',
    themeColor: '',
    siteUrl: '',
    siteName: '',
    twitterHandle: '',
    language: 'en',
  },
  paths: {
    signIn: '/auth/sign-in',
    signUp: '/auth/sign-up',
    emailLinkSignIn: '/auth/link',
    onboarding: `/onboarding`,
    appHome: '/tasks',
    settings: {
      profile: '/settings/profile',
      authentication: '/settings/profile/authentication',
      email: '/settings/profile/email',
      password: '/settings/profile/password',
    },
    api: {
      checkout: `/api/stripe/checkout`,
      billingPortal: `/api/stripe/portal`,
    },
    searchIndex: `/public/search-index`,
  },
  firebase: {
    apiKey: process.env.NEXT_PUBLIC_FIREBASE_API_KEY,
    authDomain: process.env.NEXT_PUBLIC_FIREBASE_AUTH_DOMAIN,
    projectId: process.env.NEXT_PUBLIC_FIREBASE_PROJECT_ID,
    storageBucket: process.env.NEXT_PUBLIC_FIREBASE_STORAGE_BUCKET,
    messagingSenderId: process.env.NEXT_PUBLIC_FIREBASE_MESSAGING_SENDER_ID,
    appId: process.env.NEXT_PUBLIC_FIREBASE_APP_ID,
    measurementId: process.env.NEXT_PUBLIC_FIREBASE_MEASUREMENT_ID,
  },
  auth: {
    // Enable MFA. You must upgrade to GCP Identity Platform to use it.
    // see: https://cloud.google.com/identity-platform/docs/product-comparison
    enableMultiFactorAuth: true,
    // NB: Enable the providers below in the Firebase Console
    // in your production project
    providers: {
      emailPassword: true,
      phoneNumber: false,
      emailLink: false,
      oAuth: [GoogleAuthProvider],
    },
  },
  appCheckSiteKey: process.env.NEXT_PUBLIC_APPCHECK_KEY,
  navigation: {
    style: NavigationStyle.TopHeader,
  },
  email: {
    host: '',
    port: 0,
    user: '',
    password: '',
  },
  emailEtherealTestAccount: {
    email: process.env.ETHEREAL_EMAIL,
    password: process.env.ETHEREAL_PASSWORD,
  },
  environment: process.env.NEXT_PUBLIC_VERCEL_ENV ?? 'development',
  emulatorHost: process.env.NEXT_PUBLIC_EMULATOR_HOST,
  emulator: process.env.NEXT_PUBLIC_EMULATOR === 'true',
  production: process.env.NEXT_PUBLIC_NODE_ENV === 'production',
  stripe: {
    products: [
      {
        name: 'Basic',
        description: 'Describe your basic plan',
        plans: [
          {
            price: '$249/year',
            stripePriceId: '<STRIPE_PRICE_ID>',
          }
        ],
      },
      {
        name: 'Pro',
        description: 'Describe your pro plan',
        plans: [
          {
            price: '$249/year',
            stripePriceId: '<STRIPE_PRICE_ID>',
          }
        ],
      },
    ],
  },
};
```

These values are used throughout the application instead of being hardcoded into the codebase.

As you may have noticed, some of these values are taken from Node's
environment. We will use an additional file name `.env`, which is used by
`Next` to read the configuration.

This file will not be committed (at least not
the "secret" variable). So instead, you should define those variables within your
favorite CI/CD.

## Environment Variables

Makerkit provides templates for configuring your environment variables correctly and the **minimum** environment variables to run your local environment.

To push your project to production, **you must fill these variables by creating your Firebase project** and adding the required values.

<Alert type='warn'>
  When you first run your project build, ensure to fill the required environment variables using the ".env.production" environment file.
</Alert>

### Development Environment Variables

The development environment variables set your application up for the Firebase Emulators:

```
NEXT_PUBLIC_EMULATOR=true

GCLOUD_PROJECT=demo-makerkit
NEXT_PUBLIC_FIREBASE_PROJECT_ID=demo-makerkit
NEXT_PUBLIC_FIREBASE_STORAGE_BUCKET=demo-makerkit.appspot.com
NEXT_PUBLIC_SITE_URL=http://localhost:3000
NEXT_PUBLIC_FIREBASE_AUTH_DOMAIN=localhost
NEXT_PUBLIC_FIREBASE_EMULATOR_HOST=localhost
NEXT_PUBLIC_FIRESTORE_EMULATOR_PORT=8080
NEXT_PUBLIC_FIREBASE_AUTH_EMULATOR_PORT=9099
NEXT_PUBLIC_FIREBASE_STORAGE_EMULATOR_PORT=9199

# Change this with your project's APP ID
NEXT_PUBLIC_FIREBASE_APP_ID=<MAKERKIT_DEV_APP_ID>
# Change this with your project's API KEY
NEXT_PUBLIC_FIREBASE_API_KEY=<MAKERKIT_DEV_API_KEY>

FIRESTORE_EMULATOR_HOST=localhost:8080
FIREBASE_AUTH_EMULATOR_HOST=localhost:9099
FIREBASE_STORAGE_EMULATOR_HOST=localhost:9199
FIREBASE_PUBSUB_EMULATOR_HOST=localhost:8085

FIREBASE_CLIENT_EMAIL=
FIREBASE_PRIVATE_KEY=
```

Please remember to update the `NEXT_PUBLIC_FIREBASE_APP_ID` and `NEXT_PUBLIC_FIREBASE_API_KEY` with the ones from your Firebase project ID. The only reason they're predefined is to allow you to quickly start the application.

### Production Environment Variables

When you go to production, create the `.env.production` by copying the content of `.env.production.template`:

```
NEXT_PUBLIC_FIREBASE_API_KEY=
NEXT_PUBLIC_FIREBASE_PROJECT_ID=
NEXT_PUBLIC_FIREBASE_STORAGE_BUCKET=
NEXT_PUBLIC_FIREBASE_MESSAGING_SENDER_ID=
NEXT_PUBLIC_FIREBASE_APP_ID=
NEXT_PUBLIC_FIREBASE_MEASUREMENT_ID=
NEXT_PUBLIC_SITE_URL=

FIREBASE_CLIENT_EMAIL=

## SECRET KEYS ARE BEST ADDED TO YOUR CI
FIREBASE_PRIVATE_KEY=
SECRET_KEY=
SECRET_APPCHECK_KEY=

NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY=

# Add these in Vercel or .env.local
STRIPE_SECRET_KEY=
STRIPE_WEBHOOK_SECRET=
```

All the secret variables should be added from your Vercel or CI console; if you need them locally, you should add them to your `.env.local` file, an environment file that is ignored by Git, and, therefore, suitable for storing sensitive data that is local and isolated to your machine.

When pushing your project to Vercel, the build will pick up the values added to `.env.production`.

### Configuring the Firebase Secret Key environment variable

If you are adding the Firebase secret key as an environment variable (as you
should) from your Vercel console (or other providers), you should make sure to
 enter the key in a valid format. But, again, this can differ between providers.

If using Vercel, add the line breaks to the pasted code.
 To do so, you can use the following regexp to replace `\\n` with `\n`. You
 should be seeing the private key with the correct line breaks (instead of
 `\n`).

Next, you can paste the secret key in the correct format into your Vercel
console.

### MakerKit configuration details

Let's see the configuration in detail:

## Site

In this section, we define some overall details about the website. We use most of these configuration properties in public pages, blog posts, and documentation.

#### Title

This property is the default title of the website. We use it in conjunction with the page's name. For example, the blog's title will be `Blog - { site.name }`.

#### Description

This title is the default description of the website. For blog posts, we override it with each entry's excerpt.

#### Theme Color

We use the property `themeColor` to define the primary color browsers display. For example, in a PWA, it is the background color of the window's header.

#### Site URL

This `siteUrl` property should be your website's URL, including the protocol, such as https://yourwonderfulwebsite.com

#### Twitter Handle

You can use this or your company's Twitter handle to link your blog posts.

## Paths

Some of the paths are repeated many times throughout the codebase. For example: where should the user be redirected to after login?

These paths help you set up the default behavior when the user signs in, out, etc.

Of course, while we could store these in the codebase, it's the quickest way to get started with the boilerplate without changing any line of code.

## Firebase

The `firebase` object is Firebase's configuration which you can retrieve from the Firebase console. You could copy and paste it in, as it's all required.

If you use multiple environments (for example, `staging` and `production`), I recommend creating two `.env` files and starting your application using the correct one.

We will show later how to do set-up multiple environments effectively.

## Email

This setting allows you to define your email provider's SMTP authentication details to send emails in your application.

While in development, you can leave this as-is: MakerKit uses the `nodemailer` test account.

## Plans

Here you can store the plans that your application offers. They should match
the plans that you are going to create in the Stripe Dashboard.


Learn how to define the global configuration of a MakerKit application with Next.js and Firebase

Define the global configuration of your MakerKit SaaS application with Next.js and Firebase


You should be all set if you have already installed NodeJS on your machine. If not, please install [NodeJS](https://nodejs.org) before continuing.

If any of the following commands do not work, please install the Firebase tools package globally:

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

Now, run this command to set up your Firebase project:

```
firebase init
```

Now, select all the products you would like to set up. If you're not sure yet, I recommend the following ones:
- Emulators
- Cloud Firestore
- Cloud Storage
- Remote Config

<Alert type='info'>
You do not need any changes to start developing your application. Feel free
to complete the configuration once you want to deploy the app for the first
time.
</Alert>

By default, Makerkit starts the application with a demo project
`demo-makerkit`.

You can rename the demo name however you want, as long as you keep the
prefix "demo", which tells Firebase not to use any production service and
not to require additional configuration for developing the application. In
fact, you do not need to create a Firebase project to get started!

Additionally, remember to change the project in the environment variables.

**If you also want to create a real Firebase project, please read on.**

#### Create or select a Project

If you have already created a project using the Firebase Console, continue by
using "Use an existing project"; otherwise, you can create one right away by
selecting "Create a new project".

If you're more comfortable creating a new project using the Firebase Console,
 [create a new project from here](https://console.firebase.google.com/).

#### Emulators

The CLI should prompt you to choose the emulators to download and the ports for each. Next, select the emulators you need based on the products selected during the first step.

Otherwise, you don't need to make any changes because this starter already uses the Firebase default ports.

Once completed, you should have the following new files in your project:
- `.firebaserc`
- `firebase.json`
- `firestore.rules`
- `firestore.indexes.json`

## Firebase Project Set-up

If you have created a Firebase project, you should be able to access this
project using the [Firebase Console](https://console.firebase.google.com/).

We assume you're building a web app: let's create a new web project.

<Video src='/assets/images/docs/create-web-app-firebase.mp4' />

### Copying the Firebase configuration in the environment file

After the previous step, you should be seeing the Firebase configuration
object.

We need to add this to your `.env.production` file, which will automatically
populate the project configuration file `~/.configuration`.

```
NEXT_PUBLIC_FIREBASE_API_KEY=
NEXT_PUBLIC_FIREBASE_AUTH_DOMAIN=
NEXT_PUBLIC_FIREBASE_PROJECT_ID=
NEXT_PUBLIC_FIREBASE_STORAGE_BUCKET=
NEXT_PUBLIC_FIREBASE_MESSAGING_SENDER_ID=
NEXT_PUBLIC_FIREBASE_APP_ID=
NEXT_PUBLIC_FIREBASE_MEASUREMENT_ID=
```

<Alert type='warn'>
Next.js bundles the environment variables prefixed with "NEXT_PUBLIC" with
your client-side code. It means that you should use these for non-secret values that need to be exposed.
</Alert>

### Getting the service account

You can find the service account by clicking on `Settings->Service Accounts`.
You should copy the text highlighted in the video below:

<Video src='/assets/images/docs/find-service-account.mp4' />

Afterward, you need to populate the relative environment variable:

```
FIREBASE_CLIENT_EMAIL=
```

You could safely add it using the file of your staging account. If it's
 your production environment, please add it using the Vercel console instead (or any other service you use to
 deploy the project).

### Generating the Private Key

The private key is fundamental to running your app with Admin permissions on the
server side. From the same page, click on "Generate Private key".

You should see the modal below:

<Image
  width={'1368'}
  height={'1018'}
  src={'/assets/images/docs/generate-private-key.webp'}
  alt={'Generate Firebase Private Key'}
/>

Once you open the generated JSON file, copy the `private_key` property and place it in your CI or your environment file as long as you do not commit the environment file.

The environment variable to populate is `FIREBASE_PRIVATE_KEY`:

```
FIREBASE_PRIVATE_KEY=
```

The key looks like this:

```
-----BEGIN PRIVATE KEY-----
***************************
-----END PRIVATE KEY-------
```

If you enter the wrong key, you will not be able to sign in server-side. In short, it won't work.

<Alert type='warn'>
Do not commit the file if you add the private key to your local environment file
</Alert>

## Firestore

Now it's time to set up Firestore DB. From the main panel on the left-hand side of the Firebase Console, click on `Firestore Database`.

Once you click on the `Create Database` CTA, you will se a modal like in the
image below:

<Image
  width={'1810'}
  height={'1132'}
  src={'/assets/images/docs/create-firestore-db.webp'}
  alt={'Create Firestore DB'}
/>

Don't overthink what to choose: we use the default MakerKit Firestore
rules which use the production configuration by default.

### Location
The next step is to choose the Firestore Database's location.

Which option to choose here depends entirely on **where you think most of
your users come from**.

<Image
  width={'1724'}
  height={'1034'}
  src={'/assets/images/docs/firestore-location.webp'}
  alt={'Choose Firestore Location'}
/>

Be careful to the Firebase notice:

<Alert type='warn'>
After you've set this location, you cannot change it later. Also, this location setting will be the location for your default Cloud Storage bucket.
</Alert>

If you're not sure, think it through. You do not need this step to start
working on your app with the Emulators, so feel free to come back to this
later when you have made a decision.

### Firestore Indexes

If you are setting up Makerkit for the first time, remember to set up an
index for querying an invitation without knowing its organization.

You can do so using the following link (replace
"\[\[YOUR_PROJECT_ID\]\]" with your real project ID):

https://console.firebase.google.com/u/0/project/\[\[YOUR_PROJECT_ID\]\]/firestore/indexes/single-field?create_exemption=ClBwcm9qZWN0cy9zdG9yeWpveS00NmVlMy9kYXRhYmFzZXMvKGRlZ
mF1bHQpL2NvbGxlY3Rpb25Hcm91cHMvaW52aXRlcy9maWVsZHMvY29kZRACGggKBGNvZGUQAQ

## Firestore and Storage Security Rules

Finally, you are required to publish the security rules to the production project. 

You can do so by logging in to the Firebase Console and pasting the rules from the `firestore.rules` and `storage.rules` files in their respective sections.

You don't need to do this right away, but you will need to do it before you deploy your application to production.

Learn how to set up your Firebase project with a MakerKit application

Setting up a Firebase project for your MakerKit application


<Alert type="info">
  Setting Firebase Functions is optional. You only need to set up Firebase Functions if you need certain features, such as Firestore Triggers, Storage Triggers, Authentication Blocking Functions, etc.
</Alert>


While you may want to use Next.js's own API functions for your application's API, there are many scenarios where you may be required to use Firebase Functions, for example:

1. You want to implement [Authentication Blocking Functions](/blog/tutorials/blocking-authentication-firebase-auth)
2. You need to use Firebase Storage Triggers
3. You need to use Firebase Firestore Triggers

Therefore, it's essential to know how to set up Firebase Functions in a Next.js environment, such as the Makerkit SaaS template.

## Initializing Firebase Functions

Assuming you have a working Makerkit project installed, let's type the following command in your terminal:

```
firebase init functions
```

When prompted about creating a new project, choose not to create a default project, as you may have already done it.

After completing the CLI prompts, you should have a few more files in your project:

```
✔  Wrote functions/package.json
✔  Wrote functions/tsconfig.json
✔  Wrote functions/src/index.ts
✔  Wrote functions/.gitignore
```

#### Adjust or delete the eslint configuration file

You may need to delete (or adjust) the `eslint` file generated by the CLI, as it may conflict with the one in the root of your project. We recommend using the one in the root of your project shipped with Makerkit.

If you leave it as is, you may see linting errors in your functions code, that can also prevent you from deploying your functions.

### Firebase Functions setup

I usually proceed to copy some of the scripts to the root `package.json`, such as the below:

```
"build:functions": "tsc -P functions/tsconfig.json",
"build:functions:watch": "tsc -P functions/tsconfig.json --watch",
"deploy:functions": "firebase deploy --only functions"
```

1. `build:functions` builds the functions bundle and then exits
2. `build:functions:watch` builds the functions in development mode, so it will re-bundle your code on changes
3. `deploy:functions` deploys your Functions to the Firebase cloud

### Writing your First Function

Let's write our first, very simple Firebase Function:

```tsx
import { https } from 'firebase-functions';

export const helloWorld = https.onRequest((req, res) => {
  res.send({ Hello: `World` })
});
```

### Running the Firebase Functions emulators

When using Makerkit, simply run the emulators:

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

If working correctly you'll see the following output:

```
✔  functions: Loaded functions definitions from source: helloWorld.
```

🎉 And now you can finally use the full power of Firebase's Functions!

### Ignore the Firebase Functions folder when deploying to Vercel

Since Firebase Functions are to be deployed to Firebase, you can ignore the `functions` folder when deploying to Vercel.

To do so, create a file named `.vercelignore` in the root of your project and add the following line:

```
functions
```

Learn how to set up Firebase Functions in your Makerkit SaaS project

Setting up Firebase Functions for your MakerKit application

A high-level overview of Makerkit's Design and Architecture

Architecture


MakerKit's primary goals are:

- **Solid Foundations** - providing you with the necessary code to get up and
running
with a Saas with minimal configuration
- **Extendable and Adaptable** - the ability to change and extend the codebase as efficiently as possible

While it's relatively simple to provide a functioning codebase, it's not always easy to make it:
- **Simple** - a clean codebase quickly understandable by anyone
- **Easy to change** - a codebase that can be easily changed to a
particular domain

Once you start your project, you can begin unpicking and replacing the existing code to adapt it to your application's domain. At the same time, MakerKit may have pushed an update that fixed a bug or added a new cool feature.

The two projects will diverge and inevitably end up in a conflicting state.

Thankfully, Git makes it easy to merge conflicts. But it's still a hassle.

### Framework Architecture

To reduce the number of possible conflicts, MakerKit ships with a particular folder structure:

```
- src
  - lib
  - components
  - pages
    - api
  - core
```

These folders represent four separate layers. MakerKit is an Onion:

<Image
  width={'2103'}
  height={'1221'}
  src={'/assets/images/docs/architecture.png'}
  alt={"MakerKit's architecture"}
/>

### Core
Let's talk about the lower level: the `core`. This layer is a collection of building blocks, utilities, and APIs that make up MakerKit.

This part of the boilerplate is configurable and makes no assumptions about your domain.

You are still welcome to change this code to suit your needs, but you can expect most updates from upstream to change the code in this directory.

### Lib and Components

The mid-level is in two separate folders (to avoid excessive nesting):

- `lib`: here is where we write most domain-related business logic (hooks, contexts, queries, mutations, etc.)
- `components`: here is where we write the domain-related components (ex. Profile Page, Create Project form, etc.)

MakerKit comes with some business logic (it would be nearly impossible otherwise to build a genuinely functioning SaaS). You should customize the existing business logic for your application, and it is likely where you will add most of your code.

This layer can still be updated by the `upstream` repository, but you should not expect too many changes unless it's additions for new features or bug fixes.

### Pages

Finally, the `pages` layer is the outer layer of the application.

It's entirely dependent on your application, and you should not expect updates from upstream unless for fixing blatantly buggy code.

## Import Flow

<Image width="1433" height="218" src="/assets/images/docs/nodejs-structure-imports-wrong.png" />

We use `eslint` to check that imports are flowing correctly through your application: if this feds you up, you can remove them from the `eslint` configuration at `/.eslintrc.json`;



Learn how MakerKit allows you to build a Next.js application with a scalable and production-grade architecture and folder structure

Architecture and Folder Structure for your Next.js SaaS application


In the previous section, we learned the fundamentals of Makerkit's architecture and the application layers.

In this section, we learn how to structure your application in practical terms with an example. For example, your application has an entity "events": how do we add this entity to a Makerkit application?

<Alert type='info'>
NB: entities rarely (or never) get added to "core". Business domain is added to "components" and "lib".
</Alert>

In short, this is how we add a new entity to the application:

1. First, we add a new folder to `lib`. If the entity is "event", we add `lib/events`.
2. Then, we add the components of the `event` domain to `components/events`
3. Finally, we add the pages of the `event` domain to `pages/events`

```txt title="Structure"
- src
  - components
    - events
      - EventsContainerComponent.tsx
      - ...

  - lib
    - events
      - types
        - event-model.ts
        - ...
      - hooks
        - use-fetch-events.ts
        - use-create-event.ts
        - ...
      - utils
        - create-event-model.ts

  - pages
    - events
      - index.tsx
      - [event].tsx
```

### 1) Adding the entity's business domain

We will add various business logic units in the `lib/events` folder, such as types, custom hooks, API calls, factories, functions, utilities, etc.

#### Types

First, we define a type `EventModel` at `lib/events/types/event-model.ts`:

```tsx title="lib/events/types/event-model.ts"
export interface EventModel {
  name: string;
  description: string;
}
```

#### Custom Hooks

For example, let's write a custom hook that retrieves a list of "events" from a Firestore collection.

We create a file at `lib/events/hooks/use-fetch-events.ts` with the following content:

```tsx title="src/lib/events/hooks/use-fetch-events.ts"
import EventModel from '~/lib/events/types/event-model.ts'

export function useFetchEvents() {
  const firestore = useFirestore();
  const eventsCollection = 'events';

  const collectionRef = collection(
    firestore,
    eventsCollection,
  ) as CollectionReference<EventModel>;

  return useFirestoreCollectionData(collectionRef, {
    idField: 'id',
  });
}
```

Good! We have a way to fetch our events, but we have to use it somewhere: to do so, let's create a component `EventsListContainer`. 

<Alert type='warn'>
  NB: remember to update the Firestore rules to be able to read the collection.
</Alert>

### 2) Components

As said before, we add React components that belong to the "events" domain to `components/events`. 

In the component below, we will fetch a list of events with `useFetchEvents`:

```tsx title="components/events/EventsListContainer.tsx"
import { useFetchEvents } from '~/lib/events/hooks/use-fetch-events';
import { Alert } from `~/core/ui/Alert`;

const EventsListContainer: React.FC = () => {
  const { data: events, status } = useFetchEvents();

  if (status === `loading`) {
    return <p>Loading Events...</p>
  }

  if (status === `error`) {
    return (
      <Alert type='error'>
        Ops, we encountered an error!
      </Alert>
    );
  }

  return (
    <div>
      {events.map(event => {
        return (
          <div key={event.name}>
            <p>{event.name}</p>
            <p>{event.description}</p>;
          </div>
        );
      })}
    </div>
  )
};

export default EventsListContainer;
```

### 3) Pages

Finally, we can add the events component `EventsListContainer` to a page. To do so, let's create a page component at `pages/events/index.ts`:

```tsx title="pages/events/index.ts"
import { GetServerSidePropsContext } from 'next';

import RouteShell from '~/components/RouteShell';
import EventsListContainer from '~/components/EventsListContainer';

import { withAppProps } from '~/lib/props/with-app-props';

const EventsPage: React.FC = () => {
  return (
    <>
      <Head>
        <title key="title">Events</title>
      </Head>
      
      <RouteShell title="Events">
        <EventsListContainer />
      </RouteShell>
    </>
  );
};

export default EventsPage;

// guard the page!
export function getServerSideProps(ctx: GetServerSidePropsContext) {
  return withAppProps(ctx);
}
```

🎉 That's it! We have now built a nicely structured "events" domain.

Learn how to structure your application with additional entities and business logic

Structure your Makerkit Application


MakerKit's data model is voluntarily as simple as possible, with a limited
set of assumptions.

MakerKit is not supposed to be a finite product but a solid foundation on which it is quick to get started and build your SaaS product.

To summarize, the Firestore model contains three main entities: `users`, `organizations`, and `invites`.

1. **Users**: a Firestore representation of the authentication database. In fact, to store data about users, we need to create a user record within our `/users` collection in Firestore
2. **Organizations**: Organizations are groups of users. Here, we store the list of members that belong to the organizations and everything that needs to be shared between the users: for example, templates, settings, integrations, and so on.
3. **Invites**: invites are a sub-collection of organizations used to store invitations that users can accept.

<Image src="/assets/images/docs/data-model.webp" width="1775" height="2436" />

## Users

Users are, of course, foundational to any application.

If a user signed in using Firebase Authentication, it merely means we have verified their credentials, not that they have an account.

We have to create an additional collection to store a user's data, such as:
- settings
- the memberships they belong to
- any other information which is not possible to update using their Authentication record (profile photo, name, email, and sign-in providers)

We only store the user's organizations as an object on the `users` collections by default.

The Firestore model looks like something similar:

```
- users
  - [userId]:
    - ... user data
```

We store the relationships between users and organizations within the
`Organizations` collection.

## Organizations

`Organizations` are groups of users.

If the name doesn't suit your domain, don't worry: you can always change the terminology using the localization files.

A user can belong to one or many organizations: each organization lists its members in an object, similar to what we do with `users`.

Below is what the `Organizations` schema looks like:

```
- organizations
  - [organizationId]
      - name
      - timezone
      - members
        - [memberId]
          - role
          - user // this is a Firestore reference
  }
```

Of course, we can assign a `name` to every organization and a `timezone` property (before you realize you're going to need it).

We define each membership by the user ID. Each membership contains the following information:

- the user role
- the user reference to `/users/[userId]`

Thus, we store the role in both collections to reduce the number of reads when we query the project members: we need to keep them in sync.

### User Roles

By default, MakerKit defines three roles: Owner (can be only one), Admin, and Member.

This enum is hierarchical and associated with a number:

```tsx
enum MembershipRole {
  Member,    // 0
  Admin,     // 1
  Owner      // 2
}
```

An Admin can do anything a member can do, and an Owner can do anything an Admin can.

### Invites

To create an invite to join an organization, we use a new collection
`invites` placed below an `organization` document: for example,
`/organizations/1/invites/1`.

The invite's interface is also straightforward:

```tsx
interface MembershipInvite {
  code: string;
  email: string;
  role: MembershipRole;
  expiresAt: number;

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

- the `email` property represents the email of the user invited. The application supports users signing up with a different email: you have to change this if you wish to disallow it
- the `role` is the assigned role, which cannot be `Owner`
- the `code` property is the unique identifier from which the user can access
the invite through a link
- the `expiresAt` property is the Unix timestamp when the invite will
expire. By default, it's going to be one week
- the `organization` object duplicates some valuable data from its
parent (which saves us from rereading the document)


Learn how MakerKit defines the model of your SaaS application with Next.js and Firebase

The MakerKit Data Model for your SaaS project built with Next.js and Firebase

Learn how MakerKit authenticates your users, and how to set-up Firebase Auth


MakerKit uses Firebase to manage authentication within your application.

By default, every kit comes with the following built-in authentication methods:
- **Email/Password** - we added, by default, the traditional way of signing in
- **Third Party Providers** - we also added by default Google Auth sign-in
- **Email Links**
- **Phone Number**

You're free to add (or remove) any of the methods supported by Firebase's
Authentication: we will see how.

This documentation will help you with the following:
 - **Setup** - setting up your Firebase project
 - **SSR** - use SSR to persist your users' authentication, adding new
providers
 - **Customization** - an overview of how MakerKit works so that you can adapt
it to your own application's needs

## Configuration

The way you want your users to authenticate can be driven via configuration.

If you open the global configuration at `src/configuration.ts`, you'll find
the `auth` object:

```tsx title="configuration.ts"
auth: {
  enableMultiFactorAuth: true,
  providers: {
    emailPassword: true,
    phoneNumber: false,
    emailLink: false,
    oAuth: [GoogleAuthProvider],
  },
},
```

As you can see, the `providers` object can be configured to only display the
auth methods we want to use.

1. For example, by setting both `phoneNumber` and `emailLink` to `true`, the
authentication pages will display the `Email Link` authentication
 and the `Phone Number` authentication forms.
2. Instead, by setting `emailPassword` to `false`, we will remove the
`email/password` form from the authentication and user profile pages.

Additionally, we can choose to add one or multiple oAuth providers by adding
the Firebase provider to the `oAuth` array. For example, we could also add
Facebook, Twitter, and GitHub:

```tsx
import { FacebookAuthProvider, TwitterAuthProvider, GitHubAuthProvider } from
'firebase/auth';

oAuth: [
  GoogleAuthProvider,
  FacebookAuthProvider,
  TwitterAuthProvider,
  GitHubAuthProvider
],
```

Additionally, we can add custom oAuth providers. First, we define them by
extending the `OAuthProvider` class:

```tsx
class MicrosoftAuthProvider extends OAuthProvider {
  constructor() {
    super('microsoft.com');
  }
}

class AppleAuthProvider extends OAuthProvider {
  constructor() {
    super('apple.com');
  }
}
```

And then, we simply add them to the `oAuth` array:

```tsx
oAuth: [
  GoogleAuthProvider,
  MicrosoftAuthProvider,
  AppleAuthProvider
],
```

<Alert type={'warn'}>
  Remember that you will always need to enable the authentication methods
  you want to use from the Firebase Console once you deploy your application
  to production
</Alert>

## SSR

Using SSR, we set up MakerKit to persist the user's session on all the website's pages.

SSR allows for seamless integration between the pages of your website. For example, your pricing page could prompt users to upgrade to the new plan rather than what it shows to non-subscribers of your service.

Many websites use persistent sessions in different ways:

- personalized content
- pre-filled forms
- and a lot more

While it sounds great, there is a downside: by server-side rendering the page (SSR), we lose the possibility to statically generate the page (SSG), which is faster.

#### Should you use SSR or SSG?

Ultimately, it comes down to what your needs and preferences are. We recommend:

- using SSG for static pages, such as the home page, your blog, and the
documentation pages
- using SSR for dynamic pages, such as your application's code (the
 pages behind authentication)

The above is the default configuration of the Makerkit's codebase, so if you're OK with that, simply keep using the same patterns as the base application.

MakerKit uses Firebase Authentication to allow access to your Next.js application using oAuth providers and email/password.

Setting up Firebase and Next.js authentication with MakerKit


If you have completed the previous steps, you should have already created a Firebase Project and initialized the repository.

At this point, we can start setting up the authentication providers from the Firebase admin console.

While using the emulator, this step is not needed; feel free to skip this part in the beginning.

## Getting Started with Firebase Auth

From the Firebase console, navigate to the `Authentication` menu item using
the left-hand side panel.

<Image
  width={'1838'}
  height={'798'}
  src={'/assets/images/docs/auth-setup.webp'}
  alt={'Firebase Auth Getting Started'}
/>

After clicking on "Getting Started" you should see all the available providers that you can choose:

<Video src='/assets/images/docs/activate-sign-up.mp4' />

Please activate all the ones you're planning on using.

We have already configured MakerKit to work with:

 - Email/Password authentication
 - Google oAuth
 - Facebook oAuth (remember to create a FB app before going to production)
 - Email Links
 - Phone Number


Learn how to set up Firebase Auth in your MakerKit application

Setting up Firebase Auth with Next.js


If you use SSR, the flow is slightly different from what you may be
used.

Typically, Firebase allows signing users in on the client-side. If you use SSR,
we need a way to authenticate the user on the server-side.

To do so, we use Firebase Auth's session cookies: we create the cookie when
the user signs in and then destroy it when the user signs out.

### Step 1: User signs in using the client SDK

The user can sign in (or up) using the Firebase Auth client SDK from the client side.

### Step 2: Creating a Session Cookie using an API endpoint

After being authenticated (signing in or up), the application requests to create and store a session cookie using an API endpoint.

The cookie is stored as an HTTP-only cookie and will be sent to the server,
so we can authenticate users right when we render the page.

When needed, we can perform the necessary redirects and security checks server-side.

### Step 3: User gets redirected to Application Home Page

The application renders a session-aware page if you have opted to use SSR on every page. Otherwise, the Firebase SDK should reflect the current session once the page has been rendered.

When the user is redirected to a protected page, the user's session authentication state is checked in the `getServerSideProps` function.

### Step 4: User signs out

The client SDK starts a sign-out request when the user decides to sign out.

When Firestore Auth destroys the current user session, the event is intercepted by a listener and then calls the API endpoint to destroy the session cookie.

Here is an illustration of the flows:

<Image src="/assets/images/docs/auth-flow.png" width="2344" height="1166" />

## Keeping the client and server sessions in sync

Because the Firebase Session cookies expire after 14 days, we need to keep the client SDK session in sync when the session cookie expires. 

To do so, when the user signs in, we also store a cookie with the expiration date. When the client SDK detects that the server-side session cookie expired, the user gets automatically signed out.

Learn how MakerKit handles the authentication flow with Firebase Auth and Next.js

Firebase and Next.js authentication flow


By default, the kit uses Google as the third-party provider to allow users
to access the application.

With that said, you could decide to add other providers that Firebase provides or even custom ones.

## Customizing the Third Party providers

To add one or multiple oAuth providers, we will need to customize the global
configuration by adding the Firebase provider to the `oAuth` array.

For example, we could also add Facebook, Twitter, and GitHub:

```tsx title="configuration.ts"
import { FacebookAuthProvider, TwitterAuthProvider, GitHubAuthProvider } from
'firebase/auth';

{
  auth: {
    providers: {
      oAuth: [
        GoogleAuthProvider,
        FacebookAuthProvider,
        TwitterAuthProvider,
        GitHubAuthProvider
      ],
    }
  }
}
```

Additionally, we can add custom oAuth providers. First, we define them by
extending the `OAuthProvider` class:

```tsx
class MicrosoftAuthProvider extends OAuthProvider {
  constructor() {
    super('microsoft.com');
  }
}

class AppleAuthProvider extends OAuthProvider {
  constructor() {
    super('apple.com');
  }
}
```

And then, we simply add them to the `oAuth` array:

```tsx
oAuth: [
  GoogleAuthProvider,
  MicrosoftAuthProvider,
  AppleAuthProvider
],
```

<Alert type={'warn'}>
  <p>
    Remember that you will always need to enable the authentication methods
    you want to use from the Firebase Console once you deploy your application
    to production.
  </p>

  <p>
    Often, these need an additional configuration you need to
    enable on the provider's end.
  </p>
</Alert>

## Adding Additional Scopes

To add additional scopes to the oAuth provider, we can tweak the
`OAuthProviders.tsx` component and assign the scopes based on the instance type:

```tsx title="OAuthProviders.tsx"
import {
  GoogleAuthProvider,
  FacebookAuthProvider,
} from 'firebase/auth';

{OAUTH_PROVIDERS.map((OAuthProviderClass) => {
  const providerInstance = new OAuthProviderClass();
  const providerId = providerInstance.providerId;

  if (providerInstance instanceof GoogleAuthProvider) {
    providerInstance.addScope('scope');
  }

  if (providerInstance instanceof FacebookAuthProvider) {
    providerInstance.addScope('scope');
  }

   return (
     // render <AuthProviderButton />
   );
});
```

For example, if you are adding the scopes for Facebook Login, [you can check
out the Firebase documentation](https://firebase.google.com/docs/auth/web/facebook-login). Then, add them to the `addScope` method
as described above.


Learn how to setup Third-Paerty providers with Firebase Auth in your MakerKit application

Set up Third party authentication providers with Next.js and Firebase


Makerkit provides a component and a route to sign your users in using an Email Link.

Thanks to Email Links Authentication, users can enter their email and then sign in by clicking on the link they received to their email.

<Alert type='warn'>
  Remember, when using this authentication method in production, ensure you manually activate it from the Firebase Console first.
</Alert>

Navigate to the `configuration.ts` file, and let's switch the
`email/password` method with `email link`:

```tsx title="configuration.ts"
{
  auth: {
    providers: {
      emailPassword: false, // we switch this to false
      phoneNumber: false,
      emailLink: true, // we switch this to true
      oAuth: [GoogleAuthProvider, FacebookAuthProvider],
    },
  }
}
```

That's it! The result should be similar to the image below:

<Image src="/assets/images/posts/email-link-authentication.webp" width="1128" height="1206" />

Ok, cool, **but can you use both?**

Yes, of course! With that said, you may need to tweak the
UI so that the result will look nice.


Learn how to setup Email Link Authentication with Firebase Auth in your MakerKit application

Set up Email Link Authentication with Next.js and Firebase


Multi-Factor Authentication allows users to add an additional layer of protection when logging in to a website, which is ideal for services that tend to be more sensitive or where privacy is paramount. 

At the time of writing, Firebase Auth supports only SMS MFA.

## Enabling Multi-Factor Authentication

Enabling MFA in your Makerkit application requires two steps:

1. You need to upgrade to [Google Cloud Identity Platform](https://cloud.google.com/identity-platform/docs/product-comparison) from the Firebase Console, as it is needed to support MFA
2. Flipping the variable `auth.enableMultiFactorAuth` to `true` in the configuration file, as it is disabled by default

```tsx title="configuration.ts"
auth: {
  // flip this to "true"
  enableMultiFactorAuth: true,
}
```

After enabling MFA, users can set it up from the `Authentication` page at `/settings/authentication`.

<Video src="/assets/images/posts/enabling-multi-factor-authentication.mp4" />

Learn how to setup Multi Factor Authentication with Firebase Auth in your MakerKit application

Set up Multi-Factor Authentication


By default, Firebase does not enforce email verification. This means that users can sign up with an email address and password, and then immediately start using your app. However, you may want to require that users verify their email address before they can use your app.

To do so, Makerkit can check that the user has verified their email address before allowing them to use your app from the server side. How? When loading the server side session, we check that the user's property `emailVerified` is `true`. If not, the user is redirected to the sign in page, and signed out.

By default, **this feature is disabled**. To enable it, you need to set the environment variable `NEXT_PUBLIC_REQUIRE_EMAIL_VERIFICATION` to `true`.

## Enabling requiring email verification

Simply set the following environment variable to `true`:

```bash
NEXT_PUBLIC_REQUIRE_EMAIL_VERIFICATION=true
```

That's pretty much it!

NB: invited users are not required to verify their email address, since they are already verified by having received the invitation by email.

Learn how to enforce email verification for your users with Firebase.

Requiring Email verification


MakerKit uses SSR throughout the website. If you choose to use SSR, you can persist the user's authentication on every page.

Whether SSR on every page is something your website may need or not is up to your needs, but MakerKit makes this process very easy.

Let's assume the following is your Next.js Index page, and we want to show the user's Profile avatar if they signed in. Therefore, you will need to fetch the user's data from the `getServerSideProps` function and return it as `props` to the current page.

The MakerKit default template does it for you, but you need to remember to add the following snippet to every page you want the authentication persisted.

```tsx
import { withUserProps } from '~/app/with-user-props';

function Index({ user }) {
    // display user in your components
}

export function getServerSideProps(ctx: GetServerSidePropsContext) {
  return withUserProps(ctx);
}
```

MakerKit also provides a `UserSessionContext` context, which you can inject with `useContext` in any of your components. Assuming you have a component `AvatarComponent` in which you want to display your user's avatar:

```tsx
function ProfileAvatar() {
    const { user } = useContext(UserSessionContext);

    return (
        <img src={user.profileURL} alt='Profile Photo' />
    )
}
```

Alternatively, you can use the hook `useUserSession`:

```tsx
function ProfileAvatar() {
    const {auth} = useUserSession();

    return (
        <img src={auth.profileURL} alt='Profile Photo' />
    )
}
```


Learn how to use SSR with Firebase Authentication and Next.js

Using SSR with Firebase and Next.js authentication


MakerKit provides various utilities that allow you to restrict access to
certain pages or API according to factors such as sign-in state, role,
membership plan, etc.

## Protecting Next.js Pages

To protect against access to certain pages, we can use the function
`withAppProps`. This function is a server-side props handler that will take
care of checking the following conditions:

- if the user is signed in - otherwise will be redirected back to the sign
in page (this is customizable)
- if the user is onboarded - otherwise will be redirected back to the
onboarding
- if the page they are trying to access requires a particular membership plan

Assuming you want to protect the `Dashboard` page, it will be as easy as:

```tsx
import { withAppProps } from '~/lib/props/with-app-props';

export async function getServerSideProps(
  ctx: GetServerSidePropsContext
) {
  return await withAppProps(ctx);
}
```

You will likely want to add additional logic or additional props
to be sent to the page. In this case, you can partially evaluate
`withAppProps` and extend the props with other information:

```tsx
import { withAppProps } from '~/lib/props/with-app-props';

export async function getServerSideProps(
  ctx: GetServerSidePropsContext
) {
  const { props: appProps } =
    await withAppProps(ctx);

  const data = await getDataFromDb();

  return {
    props: {
      ...appProps,
      data,
    }
  };
}
```
This handler takes the following parameters:

```tsx
const DEFAULT_OPTIONS = {
  redirectPath: configuration.paths.signIn,
  locale: 'en',
  localeNamespaces: <string[]>[],
  requirePlans: <string[]>[],
}
```

- `redirectPath`: by default, we redirect the user to the signIn page when
they're not authenticated
- `redirectPath`: by default, we use the `en` locale
- `localeNamespaces`: additional namespaces you want to add to the route
- `requirePlans`: a list of Stripe price IDs that you may want to require to
access this page. If you require more complex logic, it's best to handle it
separately

## Makerkit's default page guards

### withAppProps

The page guard `withAppProps` is ideal for internal pages of your application, i.e. the pages that require that the user is authenticated and that have an active account; i.e. they went past the onboarding:

This page guard will:
- ensure the user is authenticated
- ensure the user created an account after the onboarding flow
- ensure the user belongs to an organization

### withAuthProps

The page guard `withAuthProps` will disallow users from entering authentication routes (sign-in, sign-up, password-reset) while they are authenticated:

This page guard will:
- ensure the user is not authenticated before granting access to pages that **require the user not to be authenticated**

### withTranslationProps

The page guard `withTranslationProps` is used by default by the other guards and is used to load the translations before rendering the page. Use this as the default guard for static pages that do not have any authentication requirement:

This page guard will:
- ensure the translations are loaded onto the page being rendered

Page Guards allow you to protect certain routes from unauthorized access. This docs explain how MakerKit makes the process of protecting your Next.js pages easy and quick.

Protect your Next.js application's pages with Guards


API Guards are similar to Page Guards, except they belong to the server and
will protect our API endpoints.

As an example, let's take MakerKit's implementation for handling user
invites.

We want to check that:
- the user is authenticated
- the endpoint method being called is correct

```tsx
import { withAuthedUser } from '~/core/middleware/with-authed-user';

export default function inviteHandler(
  req: NextApiRequest,
  res: NextApiResponse
) {
  const handler = withPipe(
    withMethodsGuard(SUPPORTED_METHODS),
    withAuthedUser,
    inviteMembersToOrganizationHandler
  );

  return withExceptionFilter(req, res)(handler);
}
```

The `withPipe` is a simple utility that can chain API handlers that respect the interface of a Next.js handler. The above handler can be written as follows, by passing in the parameters `req` and `res` explicitly:

```tsx
export default withPipe(
  (req, res) => withMethodsGuard(SUPPORTED_METHODS)(req, res),
  (req, res) => withAuthedUser(req, res),
  (req, res) => inviteMembersToOrganizationHandler(req, res)
);
```

The final `inviteMembersToOrganizationHandler` is the one that gets called at the end and is responsible for returning data to the client.

## Makerkit Default API Guards

As you can see above, we're using various guards: `withMethodsGuard` and
`withAuthedUser`.

These two guards will make sure that the **request will get rejected if the
user isn't authenticated** or if the user **submitted a request using a
disallowed HTTP method**.

You can also simplify the above if you only want to check if the user is
signed-in:

```tsx
export default function myAPIHandler(
  req: NextApiRequest,
  res: NextApiResponse
) {
  await withAuthedUser(req, res);

  // do something with res
}
```

### withAuthedUser

The `withAuthedUser` API guard will reject the API request when the user is not authenticated.

### withMethodsGuard

The `withMethodsGuard` API guard will reject the API request when the method is not among the ones used.

For example, the code below will never execute the handler `myApiHandler` if the method is not `GET`:

```tsx
export default withPipe(
  withMethodsGuard(['GET']),
  myApiHandler
);
```

### withAdmin

The `withAdmin` API guard will ensure the Firebase Admin is initialized before continuing with the rest of the handlers. This is useful before accessing any of the Firebase Admin packages.


MakerKit uses API Guards allow to protect your Next.js API endpoints from unauthorized users, bad input, etc.

Protect your Next.js application's API with Guards


App Check is a Firebase service that helps you to protect your web app from
bots, spammy users, and general abuse detected by Google's Recaptcha.

The Makerkit SaaS starter is already configured to secure your application with Firebase AppCheck, but you will need to set it up in the Firebase Console first.

### 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 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, 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 must 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.

### Testing AppCheck

AppCheck will not work in emulator mode, so you have two options to ensure it's working as intended:

- run a production build locally
- or simply deploy your applications

Learn how to set up Firebase AppCheck in your MakerKit application to protect your application from abuse

Protect your Next.js application from abuse using Firebase AppCheck


Makerkit provides a set of React hooks to help you manage authentication in your React application. These hooks are an addition to the ones provided by `reactfire`.

## useUserSession

This hook returns the current user session. It contains the user's auth data from Firebase, and its data record from Firestore. Basically, it wraps the `UserSessionContext` value.

```tsx
import { useUserSession } from "~/core/hooks/use-user-session";

const userSession = useUserSession();
```

## useUserId

This hook returns the current user's ID.

```tsx
import { useUserId } from "~/core/hooks/use-user-id";

const userId = useUserId();
```

## useCreateServerSideSession

This hook returns a function that can be used to create a server-side session. It is useful for creating a session when a user logs in, or when a user is created.

You shouldn't be needing this unless you're customizing the authentication flow.

```tsx
import { useCreateServerSideSession } from "~/core/hooks/use-create-server-side-session";

const [sessionRequest, { loading, error }] = useCreateServerSideSession();
```

Reference for the authentication React hooks

Authentication React Hooks


Here are some common issues with authentication and how to fix them.

## I keep getting signed out after signing in

**Possible cause**: You are using the wrong Firebase private key.

This issue is usually caused by a misconfigured Firebase private key. Make sure you are using the correct private key and that it is not expired.

The Firebase private key is downloaded from the JSON Service Account file after you create a new service account in the Firebase console

The key looks like this:

```
-----BEGIN PRIVATE KEY-----
***************************
-----END PRIVATE KEY-------
```

It's much longer than the above, but you get the idea.

The key needs to be added to your environment variables settings. Please use your CI to add this key since it's a secret key:

```
FIREBASE_PRIVATE_KEY=
```

Authentication Troubleshooting

Learn the MakerKit best practices for building and shipping your app

Data Fetching


Similarly to reading data from Firestore, we may want to create a `custom
hook`` also when we write, update or delete data.

Assuming we have an entity called `tasks`, and we want to create a hook to
create a new `Task`, we can do the following.

1. First, we create a new hook at `lib/tasks/hooks/use-create-task.ts`
2. We add the `tasks` collection name to `lib/firestore-collections`
3. Wrap the `addDoc` function from Firestore within a `useCallback` hook

```tsx title="lib/tasks/hooks/use-create-task.ts"
import { TASKS_COLLECTION } from '~/lib/firestore-collections';

function useCreateTask() {
  const firestore = useFirestore();
  const tasksCollection = collection(firestore, TASKS_COLLECTION);

  return useCallback(
    (task: Task) => {
      return addDoc(tasksCollection, task);
    },
    [tasksCollection]
  );
}
```

And now, we could use this hook within a component:

```tsx
function Component() {
  const createTask = useCreateTask();

  return <MyForm onSubmit={task => createTask(task)} />
}
```

Let's take a look at a complete example of a form that makes a request using
the hook above:

```tsx title="components/tasks/NewTaskForm.tsx"
const CreateTaskForm = () => {
  const createTask = useCreateTask();
  const { setLoading, state } = useRequestState();
  const router = useRouter();
  const organization = useCurrentOrganization();
  const organizationId = organization?.id as string;

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

      const target = event.currentTarget;
      const data = new FormData(target);
      const name = data.get('name') as string;
      const dueDate = data.get('dueDate') as string;

      setLoading(true);

      const task = {
        organizationId,
        name,
        dueDate,
        description: ``,
        done: false,
      };

      await toaster.promise(createTask(task), {
        success: `Task created!`,
        error: `Ops, error!`,
        loading: `Creating task...`,
      });

      await router.push(`/tasks`);
    },
    [router, createTask, organizationId, setLoading]
  );

  return (
    <div>
      <form onSubmit={onCreateTask}>
        <div className={'flex flex-col space-y-3'}>
          <TextField.Label>
            Name
            <TextField.Input
              required
              name={'name'}
              placeholder={'ex. Launch on IndieHackers'}
            />
            <TextField.Hint>Hint: whatever you do, ship!</TextField.Hint>
          </TextField.Label>

          <TextField.Label>
            Due date
            <TextField.Input
              required
              defaultValue={getDefaultDueDate()}
              name={'dueDate'}
              type={'date'}
            />
          </TextField.Label>

          <div
            className={
              'flex flex-col space-y-2 md:space-y-0 md:space-x-2' +
              ' md:flex-row'
            }
          >
            <Button loading={state.loading}>
              <If condition={state.loading} fallback={<>Create Task</>}>
                Creating Task...
              </If>
            </Button>

            <Button color={'transparent'} href={'/tasks'}>
              Go back
            </Button>
          </div>
        </div>
      </form>
    </div>
  );
};

function getDefaultDueDate() {
  const date = new Date();
  const year = date.getFullYear();
  const month = pad(date.getMonth() + 1);
  const day = pad(date.getDate() + 1);

  return `${year}-${month}-${day}`;
}

function pad(n: number) {
  return n < 10 ? `0${n}` : n.toString();
}

export default CreateTaskForm;
```


Learn how to write, update and delete data using Firestore in Makerkit

Writing data to Firestore


When fetching data from Firestore, we use the hooks provided by `reactfire`,
although you could also use plain functions from the Firebase SDK if you
preferred.

To make data-fetching from Firestore more reusable, our convention is to
create a custom React hook for each query we make.

For example, let's take a look at the hook to fetch an organization from
Firestore:

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

type Response = WithId<Organization>;

export function useFetchOrganization(
  organizationId: string
) {
  const firestore = useFirestore();

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

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

export default useFetchOrganization;
```

Let's explain the above:

1. First, we get the Firestore instance using `useFirestore`
2. We create a Firestore reference to the path of the organization collection
3. Strong-type the document reference `as DocumentReference<Response>` so
that Typescript will correctly infer the following usages of the reference
4. Finally, we request the data using the hook `useFirestoreDocData,` which will
 return the record's data.

NB: Additionally, we tell Firestore to
add the `id` of the field to the object's dat using `{ idField: 'id' }`.
This is why the interface returned is `WithId<Organization>`. We're
basically telling Typescript that the data returned is the combination of
the following interfaces:

```tsx
interface WithId {
  id: string;
}

interface Organization {
  // ...
}
```

This is very useful, as often times you will need the IDs of your Firestore
documents on the client-side.

When you create a new Firestore collection, remember to:
1. Add the required Firestore rules
2. Store and read the name of the collection from
`~/lib/firestore-collections`:
this helps you avoid magic strings when typing your collection names
3. Create hooks to fetch data. Usually, we store these in `lib/<entity>/hooks`

### Consuming data from the Firestore hooks

Reactfire's custom hooks help us fetch data from Firestore effortlessly, but
we need to pay attention when using them due to their asynchronous nature.

For example, let's see how we can use the hook above correctly by displaying
a different UI based on the status of the hook:

```tsx
import { useFetchOrganization } from './use-fetch-organization';

function OrganizationCard({ organizationId }) {
  const {
    data: organization,
    status,
  } = useFetchOrganization(organizationId);

  /* data is loading */
  if (status === `loading`) {
    return <div>Loading...</div>
  }

  /* request errored */
  if (status === `error`) {
    return <div>Error!</div>
  }

  /* request successful, we can access "organization" */
  return <div>{organization.name}</div>;
}
```

### Fetching data from a collection using a Firestore query

Fetching data from a collection using a query is a common scenario.

For example, we assume you have a collection named `tasks`, with a foreign key
`organizationId` represents the ID of the organization to which it belongs.

Of course, you will want to write a query to fetch a list of tasks for your
organization.

When we define our entity, we will need to add a key `organizationId` so we
can match it against the ID of the organization it belongs to. For example,
take a look at the `Task` interface below:

```tsx
export interface Task {
  name: string;
  description: string;
  dueDate: string;
  done: boolean;

  // here we use organizationId as a foreign key
  organizationId: string;
}
```

Now, we can write a hook that gets a list of `tasks` that have
`organizationId` equal to the one we pass:

```tsx
import { useFirestore, useFirestoreCollectionData } from 'reactfire';

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

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

function useFetchTasks(organizationId: string) {
  const firestore = useFirestore();
  const tasksCollection = 'tasks';

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

  const path = `organizationId`;
  const operator = '==';
  const constraint = where(path, operator, organizationId);
  const organizationsQuery = query(collectionRef, constraint);

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

export default useFetchTasks;
```

### Security Rules

What about securing our Firestore database? We will use Firestore's security
rules. During development, you can update the `firestore.rules` file in your
root folder, but remember that you need to propagate these to your Firebase
instance using the console.

The functions `userIsMemberByOrganizationId` and `isSignedIn` are added by
default to the Makerkit's starter:

```js title="firestore.rules"
match /tasks/{taskId} {
  allow create: if isSignedIn();
  allow read, update, delete: if userIsMemberByOrganizationId(existingData().organizationId);
}
```

## Strong Typing

When reading data, it's necessary to strong-type your queries. While the
Firebase SDK isn't exactly type-friendly in some situations; we can make it
work by casting references to the correct type.

### Casting Documents References

When casting Firestore documents, you can use `as DocumentReference<T>`:

```tsx
const organizationRef = doc(
  firestore,
  ORGANIZATIONS_COLLECTION,
  organizationId
) as DocumentReference<WithId<Organization>>;
```

When getting the response from Firestore, the type will be correctly
inferred as `WithId<Organization>`.

### Casting Collections References

When casting Firestore collections, you can use `as CollectionReference<T>`:

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


Learn how fetch data from your Firestore database in Makerkit

Fetching data from Firestore


To make requests to the API functions in the `api` folder, we provide a
custom hook `useApiRequest`, a wrapper around `fetch`.

It has the following functionality:

1. Automatically adds a `Firebase AppCheck Token` to the request headers if you
enabled Firebase AppCheck
2. Automatically adds a `CSRF token` to the request headers

We use this in conjunction with the [swr](https://swr.vercel.app/) to simplify its usage using React components.

```tsx title="src/core/hooks/use-create-session.ts"
import useApiRequest from '~/core/hooks/use-api';

interface Body {
  idToken: string;
}

export function useCreateSession() {
  const endpoint = '/api/session/sign-in';
  const fetcher = useApiRequest<void, Body>();

  return useSWRMutation(endpoint, (path, { arg }) => {
    return fetcher({
      path,
      body: arg,
    });
  });
}
```

You can use this hook in your components:

```tsx
import { useCreateSession } from '~/core/hooks/use-create-session';

function Component() {
  const { trigger, ...mutationState } = useCreateSession();

  return (
    <>
      { mutationState.isMutating ? `Mutating...` : null }
      { mutationState.error ? `Error :(` : null }
      { mutationState.data ? `Yay, success!` : null }

      <SignInForm onSignIn={(idToken) => trigger({ idToken })} />
    </>
  );
}
```

Learn how to make requests to your Remix API in Makerkit

API requests


## 1) Add the Storage Provider

First, we need to wrap the component using Firebase Storage with the
`FirebaseStorageProvider`, which is responsible for initializing the
Firebase Storage SDK.

```tsx
import FirebaseStorageProvider from '~/core/firebase/components/FirebaseStorageProvider';

<FirebaseStorageProvider>
  <ComponentThatUsesStorage />
</FirebaseStorageProvider>
```

## 2) Create a Hook to fetch data from Storage

Let's assume we want to fetch a list of files from storage by getting their
`url`. This is a common scenario for retrieving images stored in Firebase
Storage.

```tsx
function useOrganizationAssets() {
  const storage = useStorage();

  const { setData, setError, setLoading, state } =
    useRequestState<MediaItem[]>();

  const path = `/${organizationId}/uploads`;
  const reference = ref(storage, path);

  useEffect(() => {
    void (async () => {
      try {
        const result = await list(reference);

        const items = await Promise.all(
          result.items.map(async (item) => {
            const url = await getDownloadURL(item);

            return url;
          })
        );

        setData(items);
      } catch (e) {
        setError(e);
      }
    })();
  }, [reference, setData, setError]);

  return state;
}
```

## 3) Use the custom hook in your components

And then we can use the hook in our components:

```tsx
function MyImages() {
  const { data, loading, error } = useOrganizationAssets();

  if (loading) {
    return <p>Loading...</p>;
  }

  if (error) {
    return <p>We could not fetch your images :(</p>;
  }

  return (
    <div className={'flex flex-col space-y-2'}>
      {data.map(image => {
        return <img src={image} key={image} />
      })}
    </div>
  );
}
```


Reading data from Storage


When uploading data to storage, the data needs to be secured so that it
can only be accessed by the organization that created it; we need to add the
organization ID to the file's custom data.

By doing so, we will be able to
compare the custom data ID with the user's organization ID, and verify they
match.

## 1) Add the Storage Provider

First, we need to wrap the component using Firebase Storage with the
`FirebaseStorageProvider`, which is responsible for initializing the
Firebase Storage SDK.

```tsx
import FirebaseStorageProvider from '~/core/firebase/components/FirebaseStorageProvider';

<FirebaseStorageProvider>
  <ComponentThatUsesStorage />
</FirebaseStorageProvider>
```

## 2) Using the Firebase Storage SDK

Now we can use the Firebase Storage SDK by using the `useStorage` hook. From
Here, we can simply use the SDK described by the Firebase documentation.

```tsx
const storage = useStorage();
```

Let's assume we have a function `uploadFile` that receives a `File`
parameter, and that we need to upload to Firebase Storage:

```tsx
import { ref, uploadBytes } from 'firebase/storage';
import toaster from 'react-hot-toast';
import { useStorage } from 'reactfire';
import { useCurrentOrganization } from './use-current-organization';

function Component() {
  const storage = useStorage();
  const organization = useCurrentOrganization();

  async function uploadFile(file: File) {
    if (!organization) return;

    const organizationId = organization.id;
    const path = `/${organizationId}/uploads/${file.name}`;
    const reference = ref(storage, path);

    const promise = uploadBytes(reference, file, {
      cacheControl: 'max-age=31536000',
      customMetadata: {
        organizationId,
      },
    });

    await toaster.promise(promise, {
      success: `Yay, uploaded!`,
      loading: `Uploading...`,
      error: `Error :(`
    });
  }

  return <UploadForm onFileChosen={uploadFile} />
}
```

## 3) Security Rules for Storage

As you can see from the code above, we are setting some custom metadata when we
upload the file:

```ts
customMetadata: {
  organizationId,
},
```
By doing this, we're effectively telling the file to store `organizationId`
as metadata on the file.

This will help us with the Storage security rules
for disallowing users in other organizations from reading the file:

```js
match /organizations/{organizationId}/{fileName=**} {
  allow read: if resource.metadata.organizationId == request.auth.token.organizationId;
  allow write: if request.auth.token.organizationId == organizationId;
}
```


Uploading data to Storage


By default, MakerKit uses a custom hook that wraps the browser's `fetch` to make it easier to use with React's components named `useApiRequest`. 

Additionally, this custom hook automatically adds two headers for security reasons: 
- `X-Firebase-AppCheck` - which is the token generated when using **Firebase AppCheck**
- `x-csrf-token` - the page's CSRF token generated when the page is server-rendered. It's needed to protect the page from CSRF attacks.

Since the `useApiRequest` hook is pretty basic, if you make complex queries to your API, you may want to use a more complete implementation such as `react-query` or `swc`. However, If you don't make complex queries, it can be unnecessary since most of your queries will be to Firestore, which uses its own client-side data-fetching method.

To make these libraries seamlessly work with the API, you only need to consider the headers above if the API uses them to protect your application's endpoints.

### Generating an App Check Token

To generate an App Check token, you can use the `useGetAppCheckToken` hook:

```tsx
const getAppCheckToken = useGetAppCheckToken();
const appCheckToken = await getAppCheckToken();

console.log(appCheckToken) // token
```

You will need to send a header `X-Firebase-AppCheck` with the resolved value returned by the promise `getAppCheckToken()`.

### Sending the CSRF Token

To retrieve the page's CSRF token, you can use the `useGetCsrfToken` hook:

```tsx
const getCsrfToken = useGetCsrfToken();
const csrfToken = getCsrfToken();

console.log(csrfToken) // token
```

You will need to send a header `x-csrf-token` with the value returned by `getCsrfToken()`.

Guide to writing your own fetch implementation

Writing your own Fetch

Development


As we've mentioned before, the Starter Kit uses various conventions around how the code is split.

While you're free to use your own conventions, in this post I want to describe how to build new features using the existing conventions of the Next.js and Firebase kit.

Let's take a high-level overview of how we can go about adding new features. In this example, we want to add "events" to our application:

### 1) Adding the business logic

First, we create a new folder within `lib`. For example, such as `lib/events`. This folder will contain all the code related to events.

In this folder, we will add types, hooks, utilities, and **anything
regarding the domain of this feature**.

For example, let's assume we want to write a feature that allows users to fetch and list `events`. We will create a `lib/events/hooks/use-fetch-events.ts` file that will contain the hook for fetching a list of events from Firestore.

```tsx title="lib/events/hooks/use-fetch-events.ts"
export default feature useFetchEvents() {
  const firestore = useFirestore();
  const eventsCollection = 'events';

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

  const path = `organizationId`;
  const operator = '==';
  const constraint = where(path, operator, organizationId);
  const organizationsQuery = query(collectionRef, constraint);

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

We will now use the hook above within our React components to fetch the events.

### 2) Adding the "events" components 

We will add a new folder within `src/components` called `events`. This folder will contain all the components related to events.

For example, `EventsContainer.tsx`, `EventDetail.tsx` and so on. These components will be imported within our Next.js pages components.

```tsx title="components/events/EventsContainer.tsx"
export default function EventsContainer() {
  const { data, status } = useFetchEvents();

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

  if (status === `error`) {
    return <Error />;
  }

  return (
    <div>
      {data.map((event) => (
        <EventDetail key={event.id} event={event} />
      ))}
    </div>
  );
}
```

### 3) Finally, we add the events Next.js Pages

Finally, **we need to add the pages to our Next.js application**. We can do this by adding the events pages to `pages/events/**.tsx`. 

The page components will then import the components as building blocks from `components/events`. 

```tsx title="pages/events/index.tsx"
export default function EventsPage() {
  return (
    <RouteShell>
      <EventsContainer />
    </RouteShell>
  );
}

export function getServerSideProps(ctx: GetServerSidePropsContext) {
  return withAppProps(ctx);
}
```

### 4) Using API Requests

Let's now assume you need to **use an API request** to fetch your data; since this can be due to various factors:

1. You need to fetch data from an external API
2. You need to fetch data from a different database
3. You need to fetch from Firestore that requires elevated permissions
4. You need to fetch from particularly complex Firestore queries

These are all good reasons! The flow explained above still makes a lot of sense, but the convention used by the kit is slightly different. 

In fact, we store the server queries within `~lib/server/events`. Of course, you can also add these below your domain `~/lib/events/server`. The choice is yours.

```tsx title="lib/server/events/fetch-events.ts"
export default function fetchEvents() {
  return makeExternalDatabaseRequest();
}
```

Now that we have a function to retrieve data from the external service, we can finally create an API handler to call this function.

```tsx title="pages/api/events.ts"
export default async function eventsHandler(
  req: NextApiRequest,
  res: NextApiResponse
) {
  const events = await fetchEvents();

  res.status(200).json(events);
}
```

From the client side, we can use the hook `useApiRequest` to call the API handler.

```tsx title="lib/events/hooks/use-fetch-events.ts"
export default function useFetchEventsFromApi() {
  return useApiRequest('/api/events');
}
```

Finally, we can use the hook within our React components.

```tsx title="components/events/EventsContainer.tsx"
export default function EventsContainer() {
  const { data, loading, error } = useFetchEventsFromApi();

  if (loading) {
    return <Loading />;
  }

  if (error) {
    return <Error />;
  }

  return (
    <div>
      {data.map((event) => (
        <EventDetail key={event.id} event={event} />
      ))}
    </div>
  );
}
```

Learn the flow and patterns that you can use to build new features

Building features for your Next.js Makerkit application


Here are all the commands defined in the MakerKit's template:

### Analyzing the Next.js bundle

Run the command:

```
npm run analyze
```

The command will automatically bundle your clients and open a page with an analysis of your bundles. This will allow you to understand which libraries are taking the most space.

### Run the development server

Run the command:

```
npm run dev
```

### Run the E2E testing server

This command is needed for running the E2E tests. Run the command:

```
npm run dev:test
```

### Build a production bundle

Run the command:

```
npm build
```


### Start a production server

Run the command after building the application with the `build` command:

```
npm start
```

### Build RSS feeds

Run the command:

```
npm run rss
```

This is optional as it is automatically called after the `build` command.

### Build Sitemap

Run the command:

```
npm run sitemap
```

This is optional as it is automatically called after the `build` command.

### Format all the files

Run the command:

```
npm run format
```

### Healthcheck: Lint code and check types

Run the command:

```
npm run healthcheck
```

### Start the Firebase Emulator

Run the command:

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

This is needed during development.

### Export data from the Firebase Emulator

Run the command:

```
npm run firebase:emulators:export
```

### Run Cypress for E2E Tests (with UI)

Run the command:

```
npm run cypress
```

### Run Cypress for E2E Tests (Headless)

Run the command:

```
npm run cypress:headless
```

### Run Tests and Exit

Run the command:

```
npm test
```

### Run the Local Stripe Webhooks Server

This is needed if you are testing Stripe. This command requires Docker, but you can alternatively install Stripe on your OS and change the command to use `stripe` directly.

Run the command:

```
npm run stripe:listen
```

### Run the Mock Stripe Server

Run the command:

```
npm run stripe:mock-server
```

### Index blog and documentation pages for making the documents available for searching

Run the command:

```
npm run blog-docs-indexer
```

### Kill Ports

The following commands kills all the ports that need to be free to run the Makerkit stack. This can be necessary after running the tests, for example when the emulators don't free up the ports after shutting down.

Run the command:

```
npm run killports
```


All the commands to use for your Makerkit app


The Makerkit's boilerplate codebase is formatted with *Prettier*. You can configure it as you wish by updating the file `.prettierrc` you find in the project's root.

The default settings look like the below:

```json
{
  "tabWidth": 2,
  "useTabs": false,
  "semi": true,
  "arrowParens": "always",
  "parser": "typescript",
  "printWidth": 80,
  "singleQuote": true
}
```

For example, to remove semicolons, update the `semi` and set it to `false`.

After adjusting the Prettier configuration, you can reformat the whole project by running the following command:

```
npm run format
```


Adjust the codebase style according to your preferences


When running the Firebase Emulator, you can update your Firebase Firestore and Storage security rules by simply changing the files `firestore.rules` and `storage.rules`.

### Firestore Security Rules

By default, Makerkit comes with pre-configured Security Rules that work with the original boilerplate's data structure. However, you will likely be updating your structure to fit your SaaS data model, and therefore you will probably be updating the Firestore Security Rules.

To change your Firestore security rules, simply edit the `firestore.rules` file in the root directory of your Makerkit repository; the Firebase Emulator will automatically pick the new changes up.

### Storage Security Rules

At the moment, Makerkit does not add any security rule for your Storage buckets; this will be added very soon.

### Publish your rules

Publishing your security rules is a critical pre-production step you should never forget; otherwise, your users will encounter runtime exceptions, ultimately leading to bugs in your app.

<Alert type='warn'>
  Remember: updating your repository's rules does not automatically publish them!
</Alert>

To publish your Security rules, open your Firebase Admin Console and copy-paste the content of your security rules. It can take some time before they fully propagate.


Setting up your Firebase Security Rules during development


Much of the MakerKit's codebase uses translations using the package `next-i18next':

- this package allows you to create multi-language apps effortlessly
- it also helps easily renaming the Makerkit's entities according to your preferences: for example, renaming "organizations" to another entity such as "team" or "workspace"
- in a way, it helps write cleaner HTML

To add or update the default strings, you must use the locale files at `public/locales/{lang}.json`. For example, all the locale files for the English language are placed under `public/locales/en`.

<Alert type='warn'>
  When adding new keys, you'll need to restart the MakerKit server (npm run
  dev) to see the changes.
</Alert>

The locales are split by functionality, page, or entity: as your application grows, you may not want to load every JSON file to reduce your bundle size.

For example, the translations for the authentication are placed in `auth.json,` while the ones used across every page are placed under `common.json.`

If you are unsure where to add some translations, simply add them to `common.json`.

<Alert type='info'>
  To simplify things, the MakerKit's starter uses all the available JSON
  files, and we recommend doing so until you have too many files or too many
  keys.
</Alert>

### Adding new languages

By default, Makerkit uses English for translating the website's text. All the files are stored in the files at `/public/locales/en`.

Adding a new language is very simple:
1. **Translation Files**: First, we need to create a new folder, such as `/public/locales/es`, and then copy over the files from the English version and start translating files.
2. **Next.js i18n config**: We need to also add a new language to the Next.js configuration at `next-i18next.config.js`. Simply add your new language's code to the `locales` array.

The configuration will look like the below:

```js
const config = {
  i18n: {
    defaultLocale: DEFAULT_LOCALE,
    locales: [DEFAULT_LOCALE, 'es'],
  },
  fallbackLng: {
    default: [DEFAULT_LOCALE],
  },
  localePath: resolve('./public/locales'),
};
```

### Adding new translation files

For example, let's assume you add a new namespace (e.g. a JSON file) named `editor.json`. Now, to automatically add the translations of this file, we will add it to the `DEFAULT_OPTIONS` variable:

```tsx
const DEFAULT_OPTIONS: Options = {
  locale: DEFAULT_LOCALE,
  localeNamespaces: [
    'common',
    'auth',
    'organization',
    'profile',
    'subscription',
    'editor' // <--- HERE IT IS
  ],
};
```

If you want to simplify things, simply merge all the files into one; the only downside is that lazy-loading translation files will not be possible.

#### Setting the default Locale

To set the default locale, simply update the environment variable `DEFAULT_LOCALE` stored in `.env`.

So, open the `.env` file, and update the variable:

```txt title=".env"
DEFAULT_LOCALE=de
```

### Using the Language Switcher component

The Language switcher component will automatically retrieve and translate the languages listed in your configuration.

When the user changes language, it will update the URL to reflect the user's preferences and rerender the application with the selected language.

<Video src="/assets/images/posts/language-selector.mp4" />

NB: The language selector is not added to the application by default; you will need to import it where you want to place it.

### Lazy Loading Locale files

Let's assume your `editor.json` file is only loaded in your `EditorPage` component; so it can make sense to only load translations on that page. To do so, we can use `withAppProps`:

```tsx title="pages/editor.tsx"
export default function EditorPage() {
  return <></>;
}

export function getServerSideProps() {
  return withAppProps({
    localeNamespaces: ['editor']
  });
}
```

The `editor` namespace will be added to the default ones specified in  `DEFAULT_OPTIONS`. This approach is excellent if the translations in the specified JSON file are only added to a specific page.


Adding and updating locales in your Makerkit application


MakerKit uses the popular package `nodemailer` to allow you to send emails.

Normally, you would use a service for sending transactional emails such as SendGrid, Mailjet, MailGun, Postmark, and so on.

These are all valid, and it doesn't really matter what you use. In
fact, as long as you provide the SMTP credentials for your service, you shouldn't be needing any other change.

## Email Configuration

To add your service's configuration, fill the `email` object in your configuration file at `src/configuration.ts`:

```tsx
email: {
  host: '',
  port: 0,
  user: '',
  password: '',
  senderAddress: 'MakerKit Team <test@makerkit.dev>',
}
```

The details above are provided by the service you're using.

<Alert type='warn'>
  When running the emulators, by default, Makerkit uses Ethereal for sending emails, and not your production service. Read below for more info.
</Alert>

## Sending Emails

To send emails, import and use the `sendEmail` function, such as below:

```tsx
interface SendEmailParams {
  from: string;
  to: string;
  subject: string;
  text?: string;
  html?: string;
}

import { sendEmail } from '~/core/email/send-email';

function sendTransactionalEmail() {
  const sender = configuration.email.senderAddress;

  return sendEmail({
    to: `youruser@email.com`,
    from: sender,
    subject: `Achievement Unlocked!`,
    html: `Yay, you unlocked an achievement!`,
  });
}
```

## Using react.email to render emails

Makerkit's newest versions use [react-email](https://react.email) to render emails: this is a great library that allows us to write emails using React components.

By default, Makerkit's only email is the one sent when inviting members to a Makerkit application - but you can leverage this library to write your own emails for your application.

For example, here's the code for the email sent when inviting members:

```tsx title="src/lib/emails/invite.ts"
interface Props {
  organizationName: string;
  organizationLogo?: string;
  inviter: Maybe<string>;
  invitedUserEmail: string;
  link: string;
  productName: string;
}

export default function renderInviteEmail(props: Props) {
  const title = `You have been invited to join ${props.organizationName}`;

  return render(
    <Html>
      <Head>
        <title>{title}</title>
      </Head>
      <Preview>{title}</Preview>
      <Body style={{ width: '500px', margin: '0 auto', font: 'helvetica' }}>
        <EmailNavbar />
        <Section style={{ width: '100%' }}>
          <Column>
            <Text>Hi,</Text>

            <Text>
              {props.inviter} with {props.organizationName} has invited you to
              use {props.productName} to collaborate with them.
            </Text>

            <Text>
              Use the button below to set up your account and get started:
            </Text>
          </Column>
        </Section>

        <Section>
          <Column align="center">
            <CallToActionButton href={props.link}>
              Join {props.organizationName}
            </CallToActionButton>
          </Column>
        </Section>

        <Section>
          <Column>
            <Text>Welcome aboard,</Text>
            <Text>The {props.productName} Team</Text>
          </Column>
        </Section>
      </Body>
    </Html>
  );
}
```

## Using MJML to render emails (deprecated)

**If you're using a newer version of Makerkit, this section is deprecated.**.

Thanks to MJML, we can write emails using handy web components (or HTML tags).

In addition, using `react-mjml`, [we can use React components to compose our emails](https://github.com/wix-incubator/mjml-react). Wonderful, right?

Makerkit provides two MJML emails:

1. The email sent when inviting members
2. The email sent when an asynchronous payment

You can find these emails at `src/lib/emails`.

#### Using MJML with React

Let's assume we want to write a Welcome email using React and the `sendEmail` utility above.

```tsx title="src/lib/emails/welcome.ts"
function renderWelcomeEmail(props: {
  name: string;
  link: string;
}) {
  const title = `Hey, ${props.name}, Welcome!`;

  return render(
    <Mjml>
      <MjmlHead>
        <MjmlTitle>{title}</MjmlTitle>
        <MjmlPreview>{title}</MjmlPreview>
      </MjmlHead>

      <MjmlBody width={500}>
        <EmailNavbar />

        <MjmlSection fullWidth>
          <MjmlColumn>
            <MjmlText>Hi ${props.name}</MjmlText>

            <MjmlText>
              We're super glad to have you with us!
            </MjmlText>
          </MjmlColumn>
        </MjmlSection>

        <MjmlSection>
          <MjmlColumn>
            <CallToActionButton href={props.link}>
              Sign In
            </CallToActionButton>
          </MjmlColumn>
        </MjmlSection>

        <MjmlSection>
          <MjmlColumn>
            <MjmlText>Welcome aboard</MjmlText>
          </MjmlColumn>
        </MjmlSection>
      </MjmlBody>
    </Mjml>,
    { validationLevel: 'soft' }
  );
}
```

Now, let's write a function that renders the MJML email and sends it to our user:

```tsx
function sendTransactionalWelcomeEmail(props: {
  user: string;
  email: string;
}) {
  const { html, errors } = renderInviteEmail({
    link: `https://makerkit.dev/sign-in`,
    name: props.user,
  });

  if (errors.length) {
    throw new Error(
      `Found errors while rendering email: ${JSON.stringify(errors)}`
    );
  }

  return sendEmail({
    to: props.email,
    from: configuration.email.senderAddress,
    subject: `Welcome to Makerkit`,
    html,
  });
}
```

That's it! Learn more about [react-mjml](https://github.com/wix-incubator/mjml-react).

## Testing Emails

By default, when running the Firebase Emulators, Makerkit will use [Ethereal](https://ethereal.email) as an email transport provider. This service allows us to test our emails for free.

To configure Ethereal, subscribe to the service and grab the credentials generated for you. Then, add them as environment variables:

```
ETHEREAL_EMAIL=
ETHEREAL_PASSWORD=
```

Alternatively, **Makerkit will generate these credentials for you**. Every time you send an email, the credentials are printed to the console so that you can grab them and inspect the emails sent: feel free to add these as your environment variables if you haven't added them yet. In this way, you will always reuse the same Ethereal account.


Sending emails with a Makerkit application


Makerkit provides various utilities to reduce the boilerplate needed to write API functions with Next.js.

The simpler API route you could write is the following:

```tsx
export default function handler(
  req: NextApiRequest,
  res: NextApiResponse
) {
  return res.send(`Hello World`)
}
```

Of course, there isn't much in there! But any SaaS will need various checks
before executing an handler, for example:

1. checking if the request is authenticated
2. validating the request isn't from a bot
3. validating the payload matches your expected schema
4. validating the endpoint matches the expected method
5. ...and so on!

Thankfully, Makerkit allows you to do all the above thanks to `middlewares`,
simple function that accept the Next,js `req` and `res` API parameters.

Normally, as you will see in the codebase, we writeAPI handlers
using the conventions below:

```tsx title="/pages/api/members.ts"
import { withAuthedUser } from '~/core/middleware/with-authed-user';
import { withPipe } from '~/core/middleware/with-pipe';
import { withMethodsGuard } from '~/core/middleware/with-methods-guard';
import { withExceptionFilter } from '~/core/middleware/with-exception-filter';
import { withAppCheck } from '~/core/middleware/with-app-check';
import { withAdmin } from '~/core/middleware/with-admin';

const SUPPORTED_METHODS: HttpMethod[] = ['GET', 'POST'];

export default function members(
  req: NextApiRequest,
  res: NextApiResponse
) {
  const handler = withPipe(
    // throw if method is not in SUPPORTED_METHODS array
    withMethodsGuard(SUPPORTED_METHODS),
    // initialize Firebase Admin
    withAdmin,
    // check request is genuine with Firebase AppCheck
    withAppCheck,
    // check user is authenticated
    withAuthedUser,
    // execute API logic
    membersHandler
  );

  // manage exceptions
  return withExceptionFilter(req, res)(handler);
}

async function membersHandler(
  req: NextApiRequest,
  res: NextApiResponse
) {
  const members = await fetchOrganizationMembers();

  res.json(members);
}
```

Let's take a look at these functions individually.

### Piping functions

Piping functions can be useful to augment a function, validate data, or do any other check before getting to the function handler, where we write the bulk of the logic.

The utility we use is `withPipe`, a dead-simple function that iterates over functions until one of them stops (or calls functions such as `req.end()`, `req.send()`, `req.json()`).

```tsx
export default withPipe(
  (req, res) => {
    if (req.method !== 'POST') {
      res.status(409).end();
    }
  },
  (req, res) => {
    // this will never execute!
  }
)
```

### Guarding against unsupported HTTP methods

This utility helps reject requests whose method is not defined in the array.

For example, let's assume we only want to reply to `GET` and `POST` requests:

```tsx title="/api/hello.ts"
import { withMethodsGuard } from '~/core/middleware/with-methods-guard';

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

Alternatively, call it at the top of an API route:

```tsx
export default async function apiHandler() {
  await withMethodsGuard(['PUT']);
}
```

If the API is called with any other HTTP method, this function will throw a 405 error and add an `Allow` HTTP header with the list of allowed methods.

### Initializing the Firebase Admin

To be able to use the Firebase Admin functions in your Next.js API, you need to initialize it before calling its services, such as Firestore, Auth, etc.

```tsx
import { withAdmin } from '~/core/middleware/with-admin';

export default withPipe(
  withAdmin,
);
```

Alternatively, call it at the top of an API route:

```tsx
export default async function apiHandler() {
  await withAdmin();
}
```

### Rejecting requests from non-authenticated users

This is one of the most important functions you will be using, i.e. ensuring the API request is coming from an authenticated user:

```tsx
import { withAuthedUser } from '~/core/middleware/with-authed-user';

export default withPipe(
  withAuthedUser,
);
```

Alternatively, call it at the top of an API route:

```tsx
export default async function apiHandler() {
  await withAuthedUser();
}
```

### Rejecting requests from bots

If you enabled AppCheck in your application, you can disallow requests from bad actors and spammy clients:

```tsx
import { withAppCheck } from '~/core/middleware/with-app-check';

export default withPipe(
  withAdmin,
  withAppCheck,
);
```

Alternatively, call it at the top of an API route:

```tsx
export default async function apiHandler() {
  await withAdmin();
  await withAppCheck();
}
```

### Handling Exceptions

The utility `withExceptionFilter` is useful for managing exceptions from an API handler.

This utility will report the exception to `Sentry.io` (if configured), log the exception so that you can debug it, and return a JSON with some metadata to **avoid leaking information to the clients**: therefore, I highly encourage you to use this utility where possible.

Check out the example below:

```tsx
export default function apiHandler() {
  const handler = withPipe(
    withMethodsGuard(SUPPORTED_METHODS),
    withAuthedUser,
    (req, res) => {
      return await getData();
    }
  );

  // manage exceptions
  return withExceptionFilter(req, res)(handler);
}
```


Makerkit offers utilities to reduce the boilerplate needed to write Next.js API routes. Learn the techniques to write well-coded API handlers.

Writing a Next.js API route with Makerkit


[Zod](https://github.com/colinhacks/zod) is a Typescript library that helps us
secure our API endpoints by validating the payloads sent
from the client and also facilitating the typing of the payloads with
Typescript.

Using Zod is the first line of defense to validate the data sent against our
API: as a result, it's something we recommend you keep doing. It ensures we
write safe, resilient, and valid code.

All Makerkit's API routes are secured with Zod: in this document, we want
to explain the conventions used by the SaaS Boilerplate, and how to use it
for your API endpoints.

When we write an API endpoint, we first define the schema of the payload:

```tsx
function getBodySchema() {
  return z.object({
    displayName: z.string(),
    email: z.string().email(),
  });
}
```

This function represents the schema, which will validate the following
interface:

```tsx
interface Body {
  displayName: string;
  email: Email;
}
```

Now, let's write the body of the API handler that validates the body of the
function, which we expect to be equal to the `Body` interface.

```tsx
import { throwBadRequestException } from `~/core/http-exceptions`;

function inviteMemberHandler(
  req: NextApiRequest,
  res: NextApiResponse,
) {
  try {
     // we can safely use data with the interface Body
    const schema = getBodySchema();
    const { displayName, email } = schema.parse(req.body);

    return sendInvite({ displayName, email });
  } catch(e) {
    return throwBadRequestException(res);
  }
}

export default function apiHandler() {
  const handler = withPipe(
    withMethodsGuard(['POST']),
    withAuthedUser,
    inviteMemberHandler,
  );

  // manage exceptions
  return withExceptionFilter(req, res)(handler);
}
```

You can also use `safeParse` if you prefer not to throw an error when the
validation fails:

```tsx
function inviteMemberHandler(
  req: NextApiRequest,
  res: NextApiResponse,
) {
  const schema = getBodySchema();
  const result = schema.safeParse(req.body);

  // we use result.success as a type guard
  // when false, we throw an exception
  if (!result.success) {
    return throwBadRequestException(res);
  }

  // TS correctly infers result.data now
  return sendInvite(result.data);
}
```

To learn more about validating data with Zod, we suggest you
check out [the Zod official documentation on GitHub](https://github.com/colinhacks/zod).


Zod is a library for validating data with awesome support for Typescript. Learn how to use it within your Makerkit project.

Validating the API inputs with Zod and Typescript


The Makerkit Boilerplate uses `pino` as logging library. Pino is simple and
lightweight, and it's used across the API functions to log important
information that helps you debug your code.

Generally speaking, you will find that we log every function, especially for
asynchronous operations that could fail for a number of reasons: network
issues, API exceptions, and so on.

So, how to log your API functions effectively? Our recommendation is to log
**before executing an operation** and then log the **result of the
operation**, without leaking important data.

Furthermore, we want to log information such as:
- which user is performing the operation?
- which organization is the user part of?
- any other information that can help you understand and debug what is
happening.

Let's assume you're writing an API function to write to your Firestore database:

```tsx
function addIntegrationHandler() {
  return writeToFirestore(data);
}
```

Let's rewrite the above by adding logging to your function:

```tsx
import logger from '~/core/logger';

async function addIntegrationHandler(
  req: NextApiRequest,
  res: NextApiResponse,
) {
  const userId = req.firebaseUser.uid;
  const organizationId = req.cookies.organizationId;
  const integrationId = req.body.integration;

  // this is the context that every log will print out
  const loggingContext = {
    integrationId,
    organizationId,
    userId,
  };

  // Here we log what we're doing
  logger.log(loggingContext, `Adding new integration to organization`);

  try {
    await writeToFirestore(data);

    // Here we log that the result of the operation
    // was successful
    logger.log(loggingContext, `Integration successfully added`);

    // return successful response
    return res.json({
      integrationId,
      success: true
    });
  } catch (e) {
    // Here we log that the operation failed
    logger.error(loggingContext, `Encountered an error while adding integration`);

    // Logging errors can be okay but
    // ensure not to leak important information!
    logger.debug(e);

    // return 500
    return res.status(500).json({
      integrationId,
      success: false
    });
  }
}
```

If you use the filter `withExceptionFilter`, it will automatically
log eventual exceptions thrown by the function, which makes the try/catch
block optional.

NB: If you're using Vercel, logs are not persisted by default! [Check out the
Vercel integrations](https://vercel.com/integrations#logging) for adding persisting logs to your projects.


Logging is a fundamental part for your SaaS to understand and monitor the behavior of your code at runtime. Let's learn how to add logging to your Makerkit application.

Logging


Enabling CORS is required if you want to allow serving HTTP request to
external clients. For example, if you want to expose an API to some
consumers: JS libraries, headless clients, and so on.

To enable CORS, you can use the `with-cors` middleware in two different ways.

You can simply call it in your handler:

```tsx
import withCors from '~/core/middleware/with-cors';

function apiHandler(
  req: NextApiRequest,
  res: NextApiResponse
) {
    withCors(res);

    // your logic
}

export default apiHandler;
```

Alternatively, you can use it with `withPipe`:

```tsx
import withCors from '~/core/middleware/with-cors';

function handler(
  req: NextApiRequest,
  res: NextApiResponse
) {
   // your logic
}

export default withPipe(
  withCors,
  apiHandler
);
```

Additionally, you need to respond to `OPTIONS` request appropriately.

```tsx
export function handler(
  req: NextApiRequest,
  res: NextApiResponse
) {
  withCors(res);

  if (req.method === `OPTIONS`) {
     // add the method you want to allow
     res.setHeader('Access-Control-Allow-Methods', 'GET');

     return res.end();
  }
}
```

Enable CORS


When storing sensitive data, such as API keys, you must ensure to encrypt your data in Firestore.

To use these utilities, you must provide an environment variable named `SECRET_KEY`. This should be provided safely using your CI since it's a secret key.

MakerKit provides some utilities to encrypt and decrypt your data. 

```tsx
import { encrypt, decrypt } from '~/core/generic/crypto';

// storing secrets
function storeApiKey(key: string) {
  const encryptedKey = encrypt(key);

  return storeKeyInFirestore(encryptedKey);
}

// retrieving secrets
function getApiKey(id: string) {
  const encryptedKey = await getApiKeyFromFirestore(id);

  return decrypt(encryptedKey);
}
```


When storing sensitive data, such as API keys, you must ensure to encrypt your data in Firestore. Here is how we can encrypt and decrypt it.

Encrypting Secrets


The MakerKit Starter has three default roles:

```tsx
export enum MembershipRole {
  Member,
  Admin,
  Owner,
}
```

We use an `enum`, but you can convert this to an object if you need more granular permissions.

The permissions are hierarchical, which means that if we had a role with a lower level (`Readonly`), we would add it before `Member`:

```tsx
export enum MembershipRole {
  Readonly,
  Member,
  Admin,
  Owner,
}
```

When writing permissions between users, we can check if the user performing the action has a greater role than the target user.

You can extend the role above easily by adding your own, for example:

```tsx
export enum MembershipRole {
  Readonly,
  AccountManager,
  Owner,
}
```

Afterward, remember to add the name and descriptions of these roles in the translations file `common.json`:

```json
"roles": {
  "owner": {
    "label": "Owner",
    "description": "Can change any setting, invite new members and manage billing"
  },
  "accountmanager": {
    "label": "Account Manager",
    "description": "Can change some settings, invite members, perform disruptive actions"
  },
  "readonly": {
    "label": "Readonly",
    "description": "Can only read information"
  }
}
```

Learn more about [using user roles in your permissions system](/docs/permissions).


Extend User Roles

Learn how to configure Stripe, and start collecting payments from your customers

Payments


MakerKit offers support for subscriptions and payments using [Stripe](https://stripe.com).

To get started with [Stripe Checkout](https://stripe.com/docs/payments/checkout), you will need to create an account using the [Stripe website](https://stripe.com).

If you want, you can get your business details sorted right away. If you
want to continue with the set-up, you can skip it for now and get back to it later.

## Configuration

Visit the [Stripe Checkout Tutorial](https://stripe.com/docs/checkout/quickstart?client=next) where we can copy the
configuration for our development environment.

If you click on the file `.env` of the code editor on the right-hand side,
you will be able to see the variables needed:

- `STRIPE_SECRET_KEY`
- `STRIPE_WEBHOOK_SECRET`

Copy these values to your local `.env.local` file.

<Alert type="warn">
  Make sure to keep your <code>.env.local</code> file private. It should not be committed to your repository. These environment variables should be added using your hosting provider's dashboard.
</Alert>

## Creating your SaaS plans in Stripe

Stripe allows us to create our plans using the UI in the Stripe Dashboard.

To get started, let's add a couple of testing plans that you can use while
developing your application.

Visit [the Stripe Dashboard](https://dashboard.stripe.com/test/products/prod_KpXDAnvbPkXkgp) and add a new product (for example, a one-time purchase or a SaaS subscription).

You can add multiple "prices": for example, if you're defining a
subscription, you could use two plans, "Basic" and "Pro".

## Creating a Webhook endpoint

Stripe allows us to create a webhook endpoint to receive events. To tell Stripe
where to send the events, we need to create a webhook endpoint that points to our application.

After creating a Stripe endpoint, we need to add the "Signing Secret" key in Stripe to the production environment variables. To do so, use the environment variables editor in your hosting provider's dashboard.

<Image src='/assets/images/docs/stripe-webhook-config.webp' width="1670" height="368" />

### Webhook API Endpoint

The API endpoint needs to point to your application's Stripe webhook: the path is `/api/stripe/webhook`. For example, if your application is hosted at `https://myapp.com`, the webhook endpoint would be `https://myapp.com/api/stripe/webhook`.

### Events

The events you want to receive from Stripe are:
- `checkout.session.completed`
- `customer.subscription.updated`
- `customer.subscription.deleted`

If you have any other events you want to receive, you need to add them here.

### Signing Secret

The signing secret is the value of the `STRIPE_WEBHOOK_SECRET` environment variable. 

<Alert type='warn'>
  If you do not follow these steps, you will not be able to receive events from Stripe. This will prevent you from being able to update the subscription status of your users. Please make sure to follow these steps.
</Alert>

### Pricing Table Configuration

Below is the default Pricing Table configuration of the kits. The `PricingTable` component will automatically generate the pricing table based on the Stripe plans you have created and added to the configuration (see below).

We have 3 products (Basic, Pro and Premium), each with 2 plans (monthly, yearly). By default, the Pro plan is set as the recommended plan.

Of course, the below is simply an example. You will need to customize this according to your application's plans.

```tsx
stripe: {
  products: [
    {
      name: 'Basic',
      description: 'Description of your Basic plan',
      badge: `Up to 20 users`,
      features: [
        'Basic Reporting',
        'Up to 20 users',
        '1GB for each user',
        'Chat Support',
      ],
      plans: [
        {
          name: 'Monthly',
          price: '$9',
          stripePriceId: 'price_1LfXGaI1i3VnbZTq7l3VgZNa',
          trialPeriodDays: 0,
        },
        {
          name: 'Yearly',
          price: '$90',
          stripePriceId: 'basic-plan-yr',
          trialPeriodDays: 0,
        },
      ],
    },
    {
      name: 'Pro',
      badge: `Most Popular`,
      recommended: true,
      description: 'Description of your Pro plan',
      features: [
        'Advanced Reporting',
        'Up to 50 users',
        '5GB for each user',
        'Chat and Phone Support',
      ],
      plans: [
        {
          name: 'Monthly',
          price: '$29',
          stripePriceId: 'pro-plan-mth',
          trialPeriodDays: 0,
        },
        {
          name: 'Yearly',
          price: '$200',
          stripePriceId: 'pro-plan-yr',
          trialPeriodDays: 0,
        },
      ],
    },
    {
      name: 'Premium',
      description: 'Description of your Premium plan',
      badge: ``,
      features: [
        'Advanced Reporting',
        'Unlimited users',
        '50GB for each user',
        'Account Manager',
      ],
      plans: [
        {
          name: '',
          price: 'Contact us',
          stripePriceId: '',
          trialPeriodDays: 0,
          label: `Contact us`,
          href: `/contact`,
        },
      ],
    },
  ],
}
```

<Alert type="warn">
  The properties "stripePriceId" are placeholders. You will need to replace them with the IDs of your plans.
</Alert>

### Additional Configuration

You can also configure the following properties on each `product`:

- `recommended` - set to `true` if you want to highlight a plan as recommended
- `badge` - set to a string if you want to display a badge next to the plan name

You can also configure the following properties on each `plan`:

- `price` - any string that you want to display as the price (e.g. `$9.99` or `Free`)
- `label` - set to a custom string if you want to display a button label
- `href` - set to a custom URL if you want to link to a custom page (for example, a contact page)
- `trialPeriodDays` - set to the number of days you want to offer a free trial for

### Install The Stripe CLI

The Stripe CLI is required to help us test our integration.
Please [follow this guide to install the CLI on your system](https://stripe.com/docs/stripe-cli).

The default recommendation is to use Docker, which Makerkit uses by default.

### Connect CLI with your account

To connect the Stripe CLI with your account, run the following command:

```
npm run stripe:listen
```

This command requires Docker, but you can alternatively install Stripe on your OS and change the command to use `stripe` directly.

The CLI should prompt you to connect your account. If you signed in already, visit the link and follow the instructions.

If you followed the instructions, get back to the terminal, and then copy
the webhook secret to your `STRIPE_WEBHOOK_SECRET` environment variables in the
`.env` file.

Restart the next.js server to apply the changes.

## Billing Portal

MakerKit uses the [Stripe Billing Portal](https://dashboard.stripe.com/test/settings/billing/portal) to let your users manage their invoices and subscriptions.

The portal becomes accessible once the organization subscribes to a plan, which creates a `customerId` property, making it possible for the organization to access the portal.

### Enabling the Billing Portal in test mode

Please visit the [Stripe Billing Page](https://dashboard.stripe.com/test/settings/billing/portal) to enable the Billing Portal.

Choose the settings that best apply to your product and save your changes.

The only required fields to get started are `Terms of Service` and
`Privacy` URLs. You can add any URL at this stage. **However, remember to update these pages when you go live**.

For a technical deep-dive, we recommend reading our blog post where we [build the integration between Stripe and Next.js from scratch](/blog/tutorials/guide-nextjs-stripe). Because the result of the blog post is a simplified version of the Makerkit's implementation, it can be beneficial for understanding its code.


Learn how to configure Stripe with your MakerKit application

Set up Stripe Payments for Next.js and Firebase SaaS applications


Makerkit handles five webhooks from Stripe and stores "just enough" data into the organization's entity to function correctly.

The Stripe's webhooks topics are defined here at `src/core/stripe/stripe-webhooks.enum.ts`:

```tsx
export enum StripeWebhooks {
  Completed = 'checkout.session.completed',
  SubscriptionDeleted = 'customer.subscription.deleted',
  SubscriptionUpdated = 'customer.subscription.updated',
}
```

To handle webhooks, we created an API route at `pages/api/stripe/webhook.ts`.

This route is responsible for:

1. Validating that the webhook is coming from Stripe
2. Routing the webhook to its handler

## Validating Stripe's Webhooks

To validate the webhook, we do the following:
1. get the header 'stripe-signature'
2. create a Stripe instance
3. get the raw body
4. call `constructEvent` to validate and build an event object sent by Stripe. When this fails, it will throw an error

```tsx
const signature = req.headers['stripe-signature'];

// verify signature header is not missing
if (!signature) {
  return throwBadRequestException(res);
}

const rawBody = await getRawBody(req);
const stripe = await getStripeInstance();

const event = stripe.webhooks.constructEvent(
  rawBody,
  signature,
  webhookSecretKey
);
```

## Handling Stripe's Webhooks

After validating the webhook, we can now handle the webhook type relative to its topic:

```tsx
switch (event.type) {
  case StripeWebhooks.Completed: {
    // handle completed
  }

  case StripeWebhooks.AsyncPaymentSuccess: {
     // handle async payment success
  }
}
```

As described above, we handle 5 events:

1. `Completed`: the checkout session was completed (but payment may not have arrived yet if it's asynchronous)
2. `SubscriptionDeleted`: the subscription was deleted by the customer
3. `SubscriptionUpdated`: the subscription was updated by the customer

### Checkout Completed

When a user completes the checkout session, we create the `subscription` object on the currently connected user's organization.

<Alert type='warn'>
  The payment may not have yet succeeded when it's "asynchronous", so the payment's status may be "AwaitingPayment" rather than "Paid". You may want to consider the subscription active only when the subscription's status is "active" or "trialing".
</Alert>

The subscription's object has the following interface:

```tsx
export interface OrganizationSubscription {
  id: string;
  priceId: string;

  status: Stripe.Subscription.Status;
  currency: string | null;
  cancelAtPeriodEnd: boolean;

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

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

This interface is added to the `Organization` object.

### Subscription Updated

When a subscription is updated, we rebuild the subscription object and update it in the organization's Firestore entity.

### Subscription Deleted

When a subscription is deleted, we simply remove it from the organization entity.

## Adding additional webhooks

If you want to add additional webhooks, you can do so by adding a new case in the switch statement.

For example, if you want to handle the `customer.subscription.trial_will_end` event, you can do so by adding the following case:

```tsx
case 'customer.subscription.trial_will_end': {
  // handle trial will end
}
```

## Adding additional data to the subscription object

If you want to add additional data to the subscription object, you can do so by adding the data to the `OrganizationSubscription` interface.

For example, if you want to add the `quantity` property to the subscription object, you can do so by adding the following property to the interface:

```tsx
export interface OrganizationSubscription {
  // ...
  quantity: number | null;
}
```

Then, you can add the data to the subscription object using the `buildOrganizationSubscription` function:

```tsx title="lib/stripe/build-organization-subscription.ts"
import type { Stripe } from 'stripe';
import type { OrganizationSubscription } from '~/lib/organizations/types/organization-subscription';

export function buildOrganizationSubscription(
  subscription: Stripe.Subscription,
): OrganizationSubscription {
  const lineItem = subscription.items.data[0];
  const price = lineItem.price;

  return {
    // your props
    quantity: lineItem.quantity,

    // default props
    id: subscription.id,
    priceId: price?.id,
    status: subscription.status,
    cancelAtPeriodEnd: subscription.cancel_at_period_end,
    currency: lineItem.price.currency ?? null,
    interval: price?.recurring?.interval ?? null,
    intervalCount: price?.recurring?.interval_count ?? null,
    createdAt: subscription.created,
    periodStartsAt: subscription.current_period_start,
    periodEndsAt: subscription.current_period_end,
    trialStartsAt: subscription.trial_start ?? null,
    trialEndsAt: subscription.trial_end ?? null,
  };
}
```

Learn how MakerKit handles Stripe Webhooks in your application

Tutorials

Environment Variables

Learn how to use environment variables in your Next.js project.

Adding Environment Variables

Subscribe to our Newsletter