Recipes to help you get started with the platform and handle common tasks.

How to


The "How to" documentation of Makerkit Next.js Firebase is a collection of tutorials that will help you to build your own web application using Next.js and Firebase using small and practical examples.

## What you will learn

1. Setting up your Makerkit Next.js Firebase project
2. Authentication
3. Updating the marketing pages of your SaaS
4. Interacting with the Database
5. Updating the Marketing pages of your SaaS
6. Updating the Internal pages of your SaaS
7. Setting up Payments
8. Updating Translations
9. ... and a lot more.

This documentation is under development and will be updated regularly. If you have any questions, please contact me.

Here is a brief introduction to the How to section of the Makerkit Next.js Firebase documentation.

Introduction to the How to section of the Makerkit Next.js Firebase documentation


Makerkit stores your project configuration in a Typescript file named `configuration.ts`, in which we store **non-secret** data needed in the client-side bundles of your project.

## What is stored in the configuration file?

In this configuration file, we store data that is safe to be exposed in the client-side bundles of your project.

The configuration file contains the following data:

```tsx
import { LayoutStyle } from '~/core/layout-style';
import { GoogleAuthProvider } from 'firebase/auth';

enum Themes {
  Light = 'light',
  Dark = 'dark',
}

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: '',
    locale: process.env.DEFAULT_LOCALE,
  },
  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,
    // 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],
    },
  },
  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.NODE_ENV === 'production',
  features: {
    enableThemeSwitcher: true,
  },
  theme: Themes.Dark,
  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`,
    },
  },
  navigation: {
    style: LayoutStyle.Sidebar,
  },
  appCheckSiteKey: process.env.NEXT_PUBLIC_APPCHECK_KEY,
  sentry: {
    dsn: process.env.SENTRY_DSN,
  },
  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_id>',
          },
          {
            name: 'Yearly',
            price: '$90',
            stripePriceId: '<price_id>',
          },
        ],
      },
      {
        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: '<price_id>',
          },
          {
            name: 'Yearly',
            price: '$200',
            stripePriceId: '<price_id>',
          },
        ],
      },
      {
        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: '',
            label: `Contact us`,
            href: `/contact`,
          },
        ],
      },
    ],
  },
};

export default configuration;
```

## How should I store my secrets?

You should store your secrets in your **non public** environment variables, and ideally set up from your CI or Hosting Provider (such as Vercel).

Never add secrets to the configuration file, as it is exposed in the client-side bundles of your project.

Please refer to the Next.js official documentation on how to best store your secrets.

Learn how and where to edit your project configuration in your Makerkit SaaS application.

How to edit your Makerkit project configuration


Most of the branding details of your SaaS will be stored in the main configuration file of your application. This file is located at `src/configurations.ts`.

The `site` object contains most of your branding details. You can update the following properties:

```tsx
site: {
  name: 'Awesomely - Your SaaS Title',
  description: 'Your SaaS Description',
  themeColor: '#ffffff',
  themeColorDark: '#0a0a0a',
  siteUrl: process.env.NEXT_PUBLIC_SITE_URL,
  siteName: 'Awesomely',
  twitterHandle: '',
  githubHandle: '',
  language: 'en',
  convertKitFormId: '',
  locale: process.env.NEXT_PUBLIC_DEFAULT_LOCALE,
},
```

1. The `name` and `description` properties will be used in the meta tags of your application
2. The `themeColor` and `themeColorDark` properties will be used to update the color of the browser bar on mobile devices.
3. The `siteName` property is a short version of your SaaS title, without the subtitle.
4. The `twitterHandle` and `githubHandle` properties will be used to link to your social media accounts (if you have any).
5. The `locale` property is the default language of your application
6. The `language` property is deprecated and will be removed in a future version of Makerkit. Please use the `locale` property instead.
7. The `convertKitFormId` property is used to link your application to your ConvertKit account if you use the Newsletter form.

## Design Branding

Please refer to the [Theming](theming) section to learn how to update the design of your application.

A unique branding is essential to any SaaS. Learn how to update your Makerkit application branding.

Update your Makerkit application Branding


Makerkit by default provides an SVG logo with the default Makerkit logo. In addition, we also provide a `mini` version of the logo that is used when the sidebar is collapsed.

You should change both the `LogoImage` and `LogoImageMini` to match your brand.

### Where are the logos defined?

The logos are defined in two files:

1. `src/core/ui/Logo/LogoImage.tsx`
2. `src/core/ui/Logo/LogoImageMini.tsx`

Feel free to replace the default logo with your own logo.

### What sizes should my logo be?

The optimal sizes for the logs are:

1. The logos should be 20px tall to fit well in the header.
2. The logo mini should be 20px tall and 20px wide.

### I like Makerkit's logo! How can I reuse it for my own logo?

[Download the Makerkit Figma file from here](/assets/makerkit.fig) and use the logo from there.

Learn how to update the logos of your Makerkit site

Updating the logo of your Makerkit site


By default, Makerkit defines the site's fonts using the package `next/font/google`.

The fonts are defined at `src/_app.tsx` and you can update them to your liking.

### What fonts are used by default?

By default, **Makerkit uses the system Apple font on Apple devices**, the `Inter` font as fallback.

### Removing Apple font as default

If you want to remove the `Apple` font as default, simply update the `FontsFamily` component at `src/_app.tsx` to remove the `Apple` font.

```tsx title="src/_app.tsx"
function FontFamily() {
  return (
    <style jsx global>
      {`
        html {
          --font-family-sans: ${fontFamilySans.style.fontFamily}, 'Segoe UI', 'Roboto', 'Ubuntu',
            'sans-serif';

          --font-family-heading: ${fontFamilyHeading.style.fontFamily};
        }
      `}
    </style>
  );
}
```

If you compare the above with the version of the file you have in your project, you'll notice that we removed the `--apple-system` fonts.

### Using a different font

If you want to use a different font, you can import it from the `next/font/google` package.

For example, below, we import the font `Manrope` from Google Fonts. It replaces `Inter` as the default font.

```tsx title="src/_app.tsx"
import { Manrope as SansFont } from 'next/font/google';
```

You can use two different fonts for the `--font-family-sans` and `--font-family-heading` variables. One is used an the main body font, the other as the heading font.

Learn how to update the fonts of your Makerkit landing pages

Updating the fonts of your Makerkit site


If you have a logo for your company, you can easily update the favicons of your Makerkit applications. Favicons are the small icons that appear in the browser tab of your website.

### Where to find the favicons

Favicons are stored at `public/assets/images/favicon`. You can replace the existing files with your own images. If you keep the same names and sizes, then you don't need to update the code.

### How to generate favicons

If you do, I suggest to generate them using any o the online favicon generator, and then dropping the resulting images in the `public/assets/images/favicon` folder.

If you have different sizes and names, then you need to update the code to reflect these changes.

## How to update the favicons in Makerkit

This code is stored in `Layout` component at `src/core/ui/Layout.tsx`. This component has many default settings that includes the favicons.

```tsx
<link rel="shortcut icon" href="/assets/images/favicon/favicon.ico" />

<link
  rel="apple-touch-icon"
  sizes="144x144"
  href="/assets/images/favicon/apple-touch-icon.png"
/>

<link
  rel="icon"
  type="image/png"
  sizes="16x16"
  href="/assets/images/favicon/favicon-16x16.png"
/>

<link
  rel="icon"
  type="image/png"
  sizes="32x32"
  href="/assets/images/favicon/favicon-32x32.png"
/>

<link rel="manifest" href="/assets/images/favicon/site.webmanifest" />

<link
  rel="mask-icon"
  href="/assets/images/favicon/safari-pinned-tab.svg"
  color="#000000"
/>
```

Update the code above to match your new favicons.

Learn how to update the favicons of your Makerkit landing pages

Updating the favicons of your Makerkit site


Makerkit ships with some environment variables pre-configured for you.

If you don't have experience with environment variables, you can think of them as a way to store configuration values for your project.

Here are the types of environment variables you can use in your Next.js project:
1. **.env**: This file is used to store environment variables that are common to all environments (development, staging, production). **Only use it for public and shared variables**.
2. **.env.local**: This file is used to store environment variables that are specific to your local development environment. **Do not commit this file to your repository** (this is already ignored by the kit's defaults).
3. **.env.development**: This file is used to store environment variables that are specific to your development environment. As long as you don't use it for sensitive data, you can commit this file to your repository.
4. **.env.production**: This file is used to store environment variables that are specific to your production environment. Do not add sensitive data to this file. Instead, use your CI provider.

## If I set mt variables in Vercel/another hosting provider, do I still need to set them in my project?

No. If you set your environment variables in your hosting provider, you don't need to set them in your project.

## Can I add secrets to my environment variables, like my OpenAI API key?

**No.** You should never add secrets to your environment variables. Instead, you should use your CI provider to set them.

## Does Next.js automatically load my environment variables?

Yes, Next.js automatically loads your environment variables. You can access them in your code using `process.env.VARIABLE_NAME`.

## I added a variable to my .env file, but I can't access it in my code. What's wrong?

Next.js only loads environment variables that start with `NEXT_PUBLIC_` if you are trying to access them from your client-side. If you want to access a variable in your client code, you need to prefix it with `NEXT_PUBLIC_`. **Note**: never add secrets to your client-side code, therefore do not prefix them with `NEXT_PUBLIC_` if it's private data.

Learn how to set environment variables in your Next.js project and how to use them in your code.

Understanding and setting the environment variables in your Next.js project


Sending emails is a critical part of your SaaS application. Makerkit uses emails to send invites to your users only, but it's likely you'll want to send other emails to your users.

To set up emails in your Makerkit application, you should add the following environment variables to your project, using a secure environment:

```bash
EMAIL_HOST=
EMAIL_PORT=587
EMAIL_USER=
EMAIL_PASSWORD=
EMAIL_SENDER='MakerKit Team <info@makerkit.dev>'
```

Makerkit will use these values to send emails on your behalf using the node library `nodemailer`.

NB: this does not refer to emails sent by Firebase.

### Where do I get these values?

These values are normally provided by your service provider.

### Which services are supported?

Any service that supports SMTP should work. We recommend using [Resend](https://resend.com/).

### How do I test emails locally?

Makerkit uses [InBucket](https://inbucket.org) - a platform to testing emails.

InBucket saves time during development since we can test
our emails without setting up a real SMTP service - and works locally and
offline.

To run the InBucket platform, **we need Docker running on our machine**.

To start the InBucket service, run the following command:

```
npm run inbucket:start
```

InBucket will now be running at [localhost:9000](http://localhost:9000). When we send an email using the
`sendEmail` function in the kit, we can visualize it using the InBucket UI.

InBucket is used by default during development. Instead, for production
usage, you will need to set up a real SMTP service.

#### Ethereal

In previous versions Makerkit used Ethereal. If you are running an older version, please refer to the below.

Makerkit used Ethereal to allow you testing your emails without using a real
email account. To use Ethereal, you should add the following environment variables to your project, using a secure environment:

```bash
ETHEREAL_EMAIL=
ETHEREAL_PASSWORD=
```

If not set, Makerkit will automatically create an account for you on-the-fly and print the credentials in the console. You can then use these credentials to log in to Ethereal and see your emails.

How to setup emails in your Makerkit SaaS application

Setup


The navigation menu of your Makerkit SaaS application's landing pages (or marketing side) is defined in the `SiteNavigation` component defined at `src/components/SiteNavigation.tsx`.

### Adding a new menu entry to the navigation menu

To add a new menu entry, simply add a new entry to the `links` object.

The key of the object is the name of the menu entry, and the value is an object with the `label` and `path` properties.

```tsx title="src/components/SiteNavigation.tsx" {22-25}
const links = {
  SignIn: {
    label: 'Sign In',
    path: '/auth/sign-in',
  },
  Blog: {
    label: 'Blog',
    path: '/blog',
  },
  Docs: {
    label: 'Docs',
    path: '/docs',
  },
  Pricing: {
    label: 'Pricing',
    path: '/pricing',
  },
  FAQ: {
    label: 'FAQ',
    path: '/faq',
  },
  NewPage: {
    label: 'New Page',
    path: '/new-page',
  },
};
```

Then, add a new `NavigationMenuItem` component to the `NavigationMenu` component.

```tsx title="src/components/SiteNavigation.tsx" {12}
<NavigationMenu>
  <NavigationMenuItem
    className={'flex lg:hidden'}
    link={links.SignIn}
  />

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

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

Et voilà! Your new menu entry is now available in the navigation menu.

Learn how to update the navigation menu of your Makerkit landing pages

Updating the navigation menu of your Makerkit SaaS application


To add a new page to the marketing site of your Next.js project, you can create a new page in the `pages` directory and using the required `getStaticProps` function.

By "marketing site", we mean the public pages of your project, such as the homepage, the about page, the contact page, etc.

<div>
  <Alert type={'warn'}>
    <div>
      Use the below code only for public pages accessible by everyone, such as the homepage, the about page, the contact page, etc.
    </div>
  </Alert>
</div>

### Adding a new page to the marketing site

For example, if you want to add a page at `/about`, you can create a new file at `pages/about.tsx` with the following content:

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

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

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

The `withTranslationProps` function is required to make sure that the page is translated correctly.

### Adding basic layout components

If you want to add a basic layout to your page, you can use the `SiteHeader` and `Footer` components:

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

import Footer from '~/components/Footer';
import SiteHeader from '~/components/SiteHeader';
import Layout from '~/core/ui/Layout';
import Container from '~/core/ui/Container';

function AboutPage() {
  return (
    <Layout>
      <SiteHeader />
      <Container>
        <div>About page</div>
      </Container>
      <Footer />
    </Layout>
  );
}

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

Learn how to add new pages to the marketing site of your Makerkit Next.js Firebase project.

Adding pages to the marketing site of your Makerkit Next.js Firebase project

Marketing Pages


Makerkit supports by default a dark theme. With that said, you can decide to opt-out of the dark theme and use the light theme only instead using the configuration below.

## Using the dark theme by default

To use the dark theme by default, you need to edit the following configuration to your `src/configuration.ts` file:

```tsx title="src/configuration.ts"
{
  features: {
    enableThemeSwitcher: true,
  },
  theme: Themes.Dark,
}
```

Users can still opt-out of the dark theme by using the theme switcher in the top right corner of the page.

## Using only the dark theme

To switch to the dark theme, you need to edit the following configuration to your `src/configuration.ts` file:

```tsx title="src/configuration.ts"
{
  features: {
    enableThemeSwitcher: false,
  },
  theme: Themes.Dark,
}
```

## Disabling the dark theme

To disable the dark theme and only use the light theme - you need to edit the following configuration to your `src/configuration.ts` file:

```tsx title="src/configuration.ts"
{
  features: {
    enableThemeSwitcher: false,
  },
  theme: Themes.Light,
}
```

In the above, we flipped the `features.enableThemeSwitcher` flag to `false` and
set the `theme` to `Themes.Light`.

## Detecting the current theme

To detect the currently selected theme, you can use the following snippet:

```tsx
import { ThemeContext } from '~/core/contexts/theme';

<ThemeContext.Consumer>
  {(theme) => {
     const isDark = theme === 'dark';
  }
</ThemContext.Consumer>
```

Setting up the dark theme in Makerkit


Makerkit's theming is defined in two places:
1. the `global.css` file
2. the `tailwind.config.js` file.

## Colors

To update the theme's colors, please update the `global.css` file in your project and update the CSS variables.

### Using the ShadCN themes

The ShadCN UI themes are predefined themes that you can use in your Makerkit project too.

You can [copy/paste the ShadCN themes](https://ui.shadcn.com/themes) into your `global.css` file and update the CSS variables to use the Makerkit color palette.

Next - you need to update the `tailwind.config.js` file in your project and update the `colors` object. These should match the CSS variables you have defined in the `global.css` file.

### Updating the Tailwind configuration

Additionally, we need to update the Tailwind configuration: since Makerkit uses a color palette based on Tailwind's palette system, we need to update the `tailwind.config.js` file in your project and update the `colors` object.

For example, since the default color for the `primary` color is `violet.500`, we need to update the `colors` object to:

```js
primary: {
  DEFAULT: 'hsl(var(--primary))',
  foreground: 'hsl(var(--primary-foreground))',
  ...colors.violet,
}
```

The code above spreads the `violet` color palette into the `primary` object, which means that the `primary` color will be the `violet.500` color.

The variable `--primary` is the hsl value of the `violet.500` color.

Additionally, we can access other colors of the `primary` palette using `primary-500`, `primary-600`, etc. This helps us to access the color palette in a more semantic way.

### Dark Mode

We need to do the same for the dark mode. Makerkit has historically used the `dark` color palette convention to define the dark mode colors.

By default, Makerkit uses `slate` as the dark mode color palette, so we need to update the `colors` object to:

```js
dark: {
  ...colors.slate,
  DEFAULT: colors.slate[950],
  foreground: colors.slate[100],
}
```

As you can see, we spread the `slate` color palette into the `dark` object, which means that the `dark` color will be the `slate.950` color.

If you were to use another color such as `zinc`, you would need to update the `colors` object to:

```js
dark: {
  ...colors.zinc,
  DEFAULT: colors.zinc[950],
  foreground: colors.zinc[100],
}
```

## Icons

While ShadCN UI uses `lucide` as their icons library, Makerkit has historically used `heroicons`. We have configured ShadCN UI to use `heroicons` instead of `lucide` in all Makerkit projects, but for new components, you will need to use `lucide` instead if you don't want to make changes. As such, please install `lucide` as a dependency in your project.

Discover how to apply the ShadCN UI theme to your Makerkit project.

Theming

User Interface


To add a new page to the application site of your Next.js project, you can create a new page in the `pages` directory and using the required `getServerSideProps` function.

By "application", we mean the private pages of your project behind the authentication wall, such as the dashboard, the settings page, etc.

As such - we need to make sure to protect these pages from being accessed by unauthorized users. To do so, we can use the `withAppProps` function, which will redirect the user to the login page if they are not authenticated.

### Adding a new page to the app

For example, if you want to add a page at `/tasks`, you can create a new file at `pages/about.tsx` with the following content:

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

const Tasks = () => {
  return (
    <RouteShell title={'Tasks'}>
     Tasks...
    </RouteShell>
  );
};

export default Tasks;

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

<div>
  <Alert type={'warn'}>
    <Alert.Heading>Always use "withAppProps"</Alert.Heading>

    <div>
      It is important to always use the <code>withAppProps</code> function in your <code>getServerSideProps</code> function, as it will make sure that the user is authenticated before accessing the page.
    </div>
  </Alert>
</div>

---

Let's break down what's happening here:

1. **withAppProps**: This function will retrieve all the required data and send it to the page as props. It will also redirect the user to the login page if they are not authenticated.
2. **RouteShell**: This component is a wrapper that will add the required layout to the page, including the navigation bar, the sidebar, the footer, etc. It will also initialize Firebase Firestore.

Learn how to add new pages to the application of your Makerkit Next.js Firebase project.

Adding pages to the application of your Makerkit Next.js Firebase project


The Sidebar of your Makerkit SaaS application is defined in the `src/navigation.config.tsx` configuration file.

This allows you to easily add, remove, or update the menu entries of your application and automatically generate a responsive sidebar menu for your users.

### Adding a new menu entry to the Sidebar

To add a new menu entry to the sidebar, simply add a new entry to the `NAVIGATION_CONFIG.items` array in the `src/navigation.config.tsx` file.

A menu entry is defined by the following properties:
```tsx
{
  label: string;
  path: string;
  Icon: (props: { className: string }) => JSX.Element;
}
```

- `label`: The label of the menu entry. This label will be displayed in the sidebar of your application. This can be either a reference to a translation key or a string.
- `path`: The path of the menu entry. This path will be used to generate the `href` attribute of the menu entry.
- `Icon`: The icon of the menu entry. This icon will be displayed in the sidebar of your application.

Consider the default schema below:

```tsx
import configuration from '~/configuration';

import {
  Cog8ToothIcon,
  Square3Stack3DIcon,
  Squares2X2Icon,
} from '@heroicons/react/24/outline';

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

export default NAVIGATION_CONFIG;
```

Now, let's add a new menu entry to the sidebar:

```tsx {32-37}
import configuration from '~/configuration';

import {
  Cog8ToothIcon,
  Square3Stack3DIcon,
  Squares2X2Icon,
} from '@heroicons/react/24/outline';

const NAVIGATION_CONFIG = {
  items: [
    {
      label: 'common:dashboardTabLabel',
      path: configuration.paths.appHome,
      Icon: ({ className }: { className: string }) => {
        return <Squares2X2Icon className={className} />;
      },
    },
    {
      label: 'common:tasksTabLabel',
      path: '/tasks',
      Icon: ({ className }: { className: string }) => {
        return <Square3Stack3DIcon className={className} />;
      },
    },
    {
      label: 'common:settingsTabLabel',
      path: '/settings',
      Icon: ({ className }: { className: string }) => {
        return <Cog8ToothIcon className={className} />;
      },
    },
    {
      label: 'common:myNewTabLabel',
      path: '/my-new-tab',
      Icon: ({ className }: { className: string }) => {
        return <Cog8ToothIcon className={className} />;
      },
    },
  ],
};
```

As you can see, we added a new menu entry to the `NAVIGATION_CONFIG.items` array. The change will be automatically reflected in the sidebar of your application.

Learn how to update the sidebar menu of your Makerkit landing pages

Updating the sidebar menu of your Makerkit SaaS application


Passing data from the server to a client during SSR is a common task.

In Makerkit, you can use the following pattern to pass data from the server to the client.

1. We use `withAppProps` to initialize the data on the server and making the required checks.
2. We augment the `props` property returned by `withAppProps` with the data we want to pass to the client.

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

type Data = {
  // ...
}

function Page({ data }: { data: Data }) {
  // you can use the data here
}

export async function getServerSideProps(
  ctx: GetServerSidePropsContext
) {
  const { props } = await withAppProps(ctx);

  // We augment the props with the data we want
  // to pass to the client
  // replace the below with your own logic
  const data = await getDataFromServer();

  return {
    props: {
      ...props,
      data,
    }
  };
}
```

As you can see - we augment the `props` property returned by `withAppProps` with the data we want to pass to the client.

The property `data` will then be available in the `props` property of the page component `Page`.

```tsx
type Data = {
  // ...
}

interface PageParams {
  data: Data
}

function Page({ data }: { data: Data }) {
  // you can use the data here
}

export default Page;
```

Being a server-side rendered app, we can pass data from the server to the client whenever the user visits the page. Here is how

Passing data from the server to the client in your Next.js Pages


As a server-side rendered application, Next.js Firebase will always render the page on the server before sending it to the client. This means that you can use the `getServerSideProps` function to guard pages from being accessed by unauthorized users.

As shown before, we will reuse the `withAppProps` function to make sure that we initialize the required data before rendering the page.

In the example below:
1. We use the `withAppProps` function to initialize the required data
2. We check if the user can access the page
3. If the user can't access the page, we redirect them to the dashboard

This is a common pattern that you can use to guard pages in your application and redirect users to the dashboard if they are not authorized to access the page.

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

function Page() {
  // render the page
}

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

  // We augment the props with the data we want
  // to pass to the client
  // replace the below with your own logic
  const canAccessPage = await checkUserCanAccessPage();

  if (!canAccessPage) {
    return {
      redirect: {
        destination: '/dashboard',
        permanent: false,
      },
    }
  }

  return appProps;
}
```

## Guarding Application Pages with User Roles

Let's make a more complete example by checking the user role and redirecting them to the dashboard if they are not an admin.

```tsx
import { GetServerSidePropsContext } from "next";
import { withAppProps } from '~/lib/props/with-app-props';
import { MembershipRole } from '~/lib/organizations/types/membership-role';

function Page() {
  // render the page
}

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

  // get user role within the organization
  const userRole = appProps.organization.members[appProps.user.id].role;

  if (!canAccessPage(userRole)) {
    return {
      redirect: {
        destination: '/dashboard',
        permanent: false,
      },
    }
  }

  return appProps;
}

function canAccessPage(role: MembershipRole) {
  return role >= MembershipRole.Admin;
}
```

## Guarding Application Pages with Organization Subscriptions

In this example, we want to make sure the Organization is subscribed to a plan before allowing the user to access the page.

To do so, we check the `subscription` property of the `Organization` object and redirect the user to the dashboard if the subscription is `active` or `trialing`.

```tsx
import { GetServerSidePropsContext } from "next";
import { withAppProps } from '~/lib/props/with-app-props';
import { OrganizationSubscription } from '~/lib/organizations/types/organization-subscription';

function Page() {
  // render the page
}

export async function getServerSideProps(
  ctx: GetServerSidePropsContext
) {
  const appProps = await withAppProps(ctx);
  const subscription = appProps.organization.subscription;

  if (!canAccessPage(subscription)) {
    return {
      redirect: {
        destination: '/dashboard',
        permanent: false,
      },
    }
  }

  return appProps;
}

function canAccessPage(subscription: OrganizationSubscription) {
  return ['active', 'trialing'].includes(subscription.status);
}
```


Learn how to guard pages in your Next.js Firebase application

Guarding Pages

Application Pages


Makerkit supports various authentication strategies supported by Firebase. We can customize these using the global configuration at `src/configurationt.ts`.

In the configuration file, you can find the following code:

```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: 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],
  },
},
```

We will need to edit this file to change the authentication strategy.

### Enabling Email and Password Authentication

This is the default authentication strategy. It allows users to sign up and sign in using their email and password.

To enable this strategy, set `providers.emailPassword` to `true`.

```tsx
providers: {
  emailPassword: false,
  phoneNumber: true,
  emailLink: false,
  oAuth: [GoogleAuthProvider],
},
```

### Enabling Phone Number Authentication

This strategy allows users to sign up and sign in using their phone number.

To enable this strategy, set `providers.phoneNumber` to `true`.

```tsx
providers: {
  emailPassword: false,
  phoneNumber: true,
  emailLink: false,
  oAuth: [GoogleAuthProvider],
},
```

### Enabling Email Link Authentication

This strategy allows users to sign up and sign in using their email address. A link will be sent to their email address to verify their identity.

To enable this strategy, set `providers.emailLink` to `true`.

```tsx
providers: {
  emailPassword: false,
  phoneNumber: trfalseue,
  emailLink: true,
  oAuth: [GoogleAuthProvider],
},
```

### Enabling OAuth Authentication

This strategy allows users to sign up and sign in using their social media accounts. You can enable multiple OAuth providers.

To enable this strategy, set `providers.oAuth` to an array of OAuth providers.

```tsx
import { GoogleAuthProvider, FacebookAuthProvider } from 'firebase/auth';

providers: {
  emailPassword: false,
  phoneNumber: false,
  emailLink: false,
  oAuth: [GoogleAuthProvider, FacebookAuthProvider],
},
```

## Can I use multiple authentication strategies?

Yes, you can use multiple authentication strategies. For example, you can enable email and password authentication and phone number authentication at the same time.

```tsx
providers: {
  emailPassword: true,
  phoneNumber: true,
  emailLink: false,
  oAuth: [GoogleAuthProvider],
},
```

With that said, the UI is not designed to support multiple authentication strategies. *You will need to customize the UI to support multiple authentication strategies**.


Learn how to change the authentication strategy in Makerkit. Choose between email and password, phone number, email link, and OAuth.

How to change Authentication strategy


By default, Firebase does not enforce email verification. However, we added support for this feature in the Firebase kit by using server-side checks.

### Can I require email verification for my users using the Firebase kit?

**Yes** - you can.

If you decide to enable this functionality, we will check server-side if the user has verified their email address before allowing them to view the protected pages.

To enable this functionality, you need to set the environment variable `NEXT_PUBLIC_REQUIRE_EMAIL_VERIFICATION` to `true` in your `.env` file.

```tsx
NEXT_PUBLIC_REQUIRE_EMAIL_VERIFICATION=true
```

Feel free to add this variable to the chosen environment file (`.env.development`, `.env.production`, etc) or to the `.env` file if you want to enable it for all environments.


Learn how to require email verification for your users using the Firebase kit.

How to require email verificatio

Authentication


API routes are a way to create a custom API endpoint for your application. You can use API routes to create RESTful endpoints that return JSON data.

Adding an API route to a Makerkit application is no different than any other Next.js (Pages Router) project. Let's see how.

## Creating an API Route

To create an API route, create a file inside the `pages/api` directory. The file name will be the path name of the API route. For example, if you create a file called `hello.ts` inside the `pages/api` directory, it will be accessible at `/api/hello`.

Here's an example of an API route that returns a JSON response:

```ts title="pages/api/hello.ts"
import { NextApiRequest, NextApiResponse } from "next";

export default (req: NextApiRequest, res: NextApiResponse) => {
  res.status(200).json({ text: 'Hello' })
}
```

This is kinda simple, right? Let's see how we can use this API route in our application.

### Protecting API Routes

It's very likely that you want to ensure only authenticated users can access your API routes. To do that, you can use the `withAuthedUser` utility to wrap your API route handler.

```ts title="pages/api/hello.ts"
import { NextApiRequest, NextApiResponse } from "next";
import { withAuthedUser } from '~/core/middleware/with-authed-user';

function helloWorldHandler(req: NextApiRequest, res: NextApiResponse) {
  res.status(200).json({ text: 'Hello' })
}

export default withAuthedUser(
  helloWorldHandler
);
```

When using the `withAuthedUser` HOC, the `req.firebaseUser` object will be available in your API route handler. This object contains the user's information from their Firebase Auth account.

You can use this object to retrieve data from your database, or to perform other actions, based on the user's information.

#### Using a Pipe for API Routes

We can pipe multiple middlewares together to create a pipeline for our API routes. For example, we can use the `withAuthedUser` middleware to ensure only authenticated users can access our API routes, and then use the `withCsrf` middleware to ensure only users with a specific role can access the API route.

```ts title="pages/api/hello.ts" {14-18}
import { NextApiRequest, NextApiResponse } from "next";

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

function helloWorldHandler(
  req: NextApiRequest,
  res: NextApiResponse
) {
  res.status(200).json({ text: 'Hello' })
}

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

### Checking CSRF Tokens

You can use the `withCsrf` HOC to ensure only users with a valid CSRF token can access your API routes.

The CSRF token must be sent in the `x-csrf-token` header of the request. If the token is not present, or if it's invalid, the request will be rejected.

```ts title="pages/api/hello.ts" {18}
import { NextApiRequest, NextApiResponse } from "next";

import { withAuthedUser } from '~/core/middleware/with-authed-user';
import { withMethodsGuard } from '~/core/middleware/with-methods-guard';
import { withPipe } from '~/core/middleware/with-pipe';
import withCsrf from "./with-csrf";

function helloWorldHandler(
  req: NextApiRequest,
  res: NextApiResponse
) {
  res.status(200).json({ text: 'Hello' })
}

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

If you pass the CSRF token in different ways, you can pass a function to the `withCsrf` HOC to retrieve the token from the request.

```tsx title="pages/api/hello.ts" {12}
import { NextApiRequest, NextApiResponse } from "next";

import { withAuthedUser } from '~/core/middleware/with-authed-user';
import { withMethodsGuard } from '~/core/middleware/with-methods-guard';
import { withPipe } from '~/core/middleware/with-pipe';
import withCsrf from "./with-csrf";

function helloWorldHandler(
  req: NextApiRequest,
  res: NextApiResponse
) {
  await withCsrf(req, () => req.body.csrfToken);

  res.status(200).json({ text: 'Hello' })
}

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

Adding API Routes


It's very likely that you want to ensure only authenticated users can access your API routes. To do that, you can use the `withAuth` HOC to wrap your API route handler.

```ts title="pages/api/hello.ts"
import { NextApiRequest, NextApiResponse } from "next";
import { withAuthedUser } from '~/core/middleware/with-authed-user';

function helloWorldHandler(req: NextApiRequest, res: NextApiResponse) {
  res.status(200).json({ text: 'Hello' })
}

export default withAuthedUser(
  helloWorldHandler
);
```

When using the `withAuthedUser` HOC, the `req.firebaseUser` object will be available in your API route handler. This object contains the user's information from their Firebase Auth account.

You can use this object to retrieve data from your database, or to perform other actions, based on the user's information.

## Guarding an API Route with a Custom Middleware

If you want to use a custom middleware to guard your API route, you can do so fairly easily by using a function that accepts a handler function and returns a handler function.

### Example: Guarding an API Route based on the User's Role

Let's say we want to create a function that guards an API route based on the user's role. We can do that by creating a function that accepts a role as an argument, and returns a handler function that checks the user's role before executing the handler function.

**Important**: this middleware requires that the `withAuthedUser` middleware is used before it - otherwise, the `req.firebaseUser` object will not be available.

```ts title="core/middleware/with-role.ts"
import { NextApiRequest,NextApiResponse } from "next";
import { MembershipRole } from '~/lib/organizations/types/membership-role';
import { getCurrentOrganization } from '~/lib/server/organizations/get-current-organization';

export function withRole(role: MembershipRole) {
  return async function(req: NextApiRequest, res: NextApiResponse) {
    const userId = req.firebaseUser.uid;
    const currentOrganizationId = req.cookies.organizationId;

    const organization =
      await getCurrentOrganization(userId, currentOrganizationId);

    const currentUserRole = organization.members[userId].role;

    if (currentUserRole !== role) {
      return res.status(403).json({
        error: 'You do not have permission to access this resource.'
      });
    }
  };
}
```

Now, we can use this middleware in our API route handler.

```ts title="pages/api/hello.ts"
import { NextApiRequest, NextApiResponse } from "next";
import { MembershipRole } from '~/lib/organizations/types/membership-role';

import { withAuthedUser } from '~/core/middleware/with-authed-user';
import { withRole } from '~/core/middleware/with-role';
import { withPipe } from '~/core/middleware/with-pipe';

function helloWorldHandler(req: NextApiRequest, res: NextApiResponse) {
  res.status(200).json({ text: 'Hello' })
}

export default withPipe(
  withAuthedUser,
  withRole(MembershipRole.Admin),
  helloWorldHandler,
);
```

### Example: Guarding an API Route based on the Organization's Status

Let's say we want to create a function that guards an API route based on the organization's status.

**Important**: this middleware requires that the `withAuthedUser` middleware is used before it - otherwise, the `req.firebaseUser` object will not be available.

```ts title="core/middleware/with-active-subscription.ts"
import { NextApiRequest,NextApiResponse } from "next";
import { getCurrentOrganization } from '~/lib/server/organizations/get-current-organization';

export function withActiveSubscription() {
  return async function(req: NextApiRequest, res: NextApiResponse) {
    const userId = req.firebaseUser.uid;
    const currentOrganizationId = req.cookies.organizationId;
    const organization =
      await getCurrentOrganization(userId, currentOrganizationId);

    const status = organization.subscription?.status;
    const isActive = ['active', 'trialing'].includes(status);

    if (!isActive) {
      return res.status(403).json({
        error: 'You do not have permission to access this resource.'
      });
    }
  };
}
```

Now, we can use this middleware in our API route handler.

```ts title="pages/api/hello.ts"
import { NextApiRequest, NextApiResponse } from "next";

import { withAuthedUser } from '~/core/middleware/with-authed-user';
import { withActiveSubscription } from '~/core/middleware/with-active-subscription';
import { withPipe } from '~/core/middleware/with-pipe';

function helloWorldHandler(req: NextApiRequest, res: NextApiResponse) {
  res.status(200).json({ text: 'Hello' })
}

export default withPipe(
  withAuthedUser,
  withActiveSubscription,
  helloWorldHandler,
);
```


Guarding an API Route


Makerkit includes the library SWR, a data-fetching React utility written by Vercel, the creators of Next.js.

This library is useful for making asynchronous requests from your React components - primarily to API Routes.

Why is it useful? SWR makes it simpler to fetch and mutate data, caching and revalidating. Let's see how we can use it to make requests to our endpoints.

## Using SWR for fetching data from an API Route Handler

Let's assume we have a very simple API Route at `/api/data`:

```tsx title="app/api/data.ts"
import { NextApiRequest, NextApiResponse } from "next";

export default async function apiHandler(
  req: NextApiRequest,
  res: NextApiResponse
) {
  return res.json({
    hello: "world"
  });
}
```

As you may know, we can call the endpoint `/api/data` using a GET request and will receive the JSON response `{ "hello": "world" }`.

Now, we want to call this from our Next.js application using SWR, and use it within a React component.

We proceed building a React Hook with SWR which is able to fetch the data from our endpoint `/api/data`:

```tsx
import useSWR from 'swr';

export function useFetchData() {
  const key = '/api/data';

  return useSWR<{ hello: string }>([key], async () => {
    return fetch(key).then(res => res.json());
  });
}
```

Now, we can call this endpoint from any React component:

```tsx
function MyComponent() {
  const { data, isLoading, error } = useFetchData();

  if (isLoading) {
    return <p>Loading...</p>;
  }

  if (error) {
    return <p>Error...</p>;
  }

  return <div>{data.hello}</div>
}
```

## Mutating data with SWR

When it comes to mutating data, we can use the `swr/mutation` utility, designed to make mutations simple.

As you may know, mutations will likely use the method `POST`, `PUT`, `PATCH`, or `DELETE`. In these cases, the middleware in the kit will require us to send a CSRF token for security reasons.

As such, we provide a handy wrapper around `fetch`.

Let's write a very simple API Route that makes a mutation: we add a new record in the `tasks` collection, and return the ID back to the client.

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

import getRestFirestore from '~/core/firebase/admin/get-rest-firestore';
import { withPipe } from '~/core/middleware/with-pipe';
import { withCsrf } from '~/core/middleware/with-csrf';
import { withAuthedUser } from '~/core/middleware/with-authed-user';

async function apiHandler(
  req: NextApiRequest,
  res: NextApiResponse
) {
  const firestore = getRestFirestore();
  const collection = firestore.collection('tasks');

  const data = await collection.add({
    name: req.body.name
  });

  return res.json({ id: data.id });
}

export default withPipe(
  withAuthedUser,
  withCsrf,
  apiHandler,
);
```

Now, let's write a React Hook that calls this endpoint using SWR.

```tsx
import useMutation from 'swr/mutation';
import { useApiRequest } from '~/core/hooks/use-api';

interface Task {
  name: string;
}

function useInsertTask() {
  const fetcher = useApiRequest();
  const path = '/api/task';

  return useMutation(
    path, async (_, data: { arg: Task }) => {
      return fetcher({
        path,
        body: data.arg,
        method: 'POST'
      });
    }
  );
}
```

What does `useApiRequest` do? This hook automatically inserts the CSRF token in our fetch requests, so that you don't have to.

If you prefer not using it, you can manually add the CSRF token instead:

```tsx
import useMutation from 'swr/mutation';
import useCsrfToken from '~/core/hooks/use-csrf-token';

interface Task {
  name: string;
}

function useInsertTask() {
  const csrfToken = useCsrfToken();
  const path = '/api/task';

  return useMutation(
    path, async (_, data: { arg: Task }) => {
      return fetch(path, {
        body: JSON.stringify(data.arg),
        method: 'POST',
        headers: {
          'x-csrf-token': csrfToken
        }
      });
    }
  );
}
```

We can now call the mutation from a React component:

```tsx
function TaskForm() {
  const insertTaskMutation = useInsertTask();

  const onSubmit: React.FormEventHandler<HTMLFormElement> = (event) => {
    const name = new FormData(event.currentTarget).get('name') ?? 'No Name';
    const task = { name };

    return insertTaskMutation.trigger(task);
  };

  return (
    <form onSubmit={onSubmit}>
      <input type={'name'} required />

      <button disabled={insertTaskMutation.isLoading}>
        Submit
      </button>
    </form>
  );
}
```


Learn how to use SWR to call your API route handlers from React components

Calling API Routes from the client-side using SWE


You can use the `withCsrf` HOC to ensure only users with a valid CSRF token can access your API routes.

The CSRF token must be sent in the `x-csrf-token` header of the request. If the token is not present, or if it's invalid, the request will be rejected.

```ts title="pages/api/hello.ts" {18}
import { NextApiRequest, NextApiResponse } from "next";

import { withAuthedUser } from '~/core/middleware/with-authed-user';
import { withMethodsGuard } from '~/core/middleware/with-methods-guard';
import { withPipe } from '~/core/middleware/with-pipe';
import withCsrf from "./with-csrf";

function helloWorldHandler(
  req: NextApiRequest,
  res: NextApiResponse
) {
  res.status(200).json({ text: 'Hello' })
}

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

If you pass the CSRF token in different ways, you can pass a function to the `withCsrf` HOC to retrieve the token from the request.

```tsx title="pages/api/hello.ts" {12}
import { NextApiRequest, NextApiResponse } from "next";

import { withAuthedUser } from '~/core/middleware/with-authed-user';
import { withMethodsGuard } from '~/core/middleware/with-methods-guard';
import { withPipe } from '~/core/middleware/with-pipe';
import withCsrf from "./with-csrf";

async function helloWorldHandler(
  req: NextApiRequest,
  res: NextApiResponse
) {
  await withCsrf(req, () => req.body.csrfToken);

  res.status(200).json({ text: 'Hello' })
}

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

How to check CSRF tokens in your Next.js Firebase API routes using the "withCsrf" HOC.

Checking CSRF Tokens

API Routes


There are several ways to fetch the signed in user, depending on the use-case.

## Fetching the signed in user from the backend

To do so, use the function `getLoggedInUser` where you have access to the request object, such as in a Next.js API route, or `getServerSideProps` function.

```tsx
import { GetServerSidePropsContext } from "next";
import { getLoggedInUser } from '~/core/firebase/admin/auth/get-logged-in-user';

async function getServerSideProps(ctx: GetServerSidePropsContext) {
  const user = await getLoggedInUser(ctx);

  return {
    props: {
      user,
    },
  };
}
```

Alternatively, you can use the `withAuthedUser` middleware to make sure that the API handler is only called when the user is signed in:

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

async function handler(req: NextApiRequest, res: NextApiResponse) {
  const user = req.firebaseUser;
  // ...
}

export default withPipe(withAuthedUser, handler);
```

The `firebaseUser` property is added to the request object by the `withAuthedUser` middleware. If the user is not signed in, the middleware will return a 401 response.

## Fetching the signed in user from the frontend

The `withAppProps` middleware used in the gated app pages makes sure that the current signed in user is passed from the backend to the frontend.

### Getting the user Session with "useUserSession"

To retrieve the signed in user from the frontend, you can use the `useUserSession` hook:

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

const userSession = useUserSession();
```

The `userSession` objects contains the following properties:

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

1. **Auth State**: The `auth` property contains the user's authentication data, such as the user ID, email, and so on.
2. **Firestore Data**:  The `data` property contains the user's Firestore record. By default, we do not add any data to the user's Firestore record - but it's assumed you will allow users to store additional data in their Firestore record.

This is a React hook and can only be used inside a React component.

### Getting the user ID with "useUserId"

To retrieve the signed in user ID from the frontend, you can use the `useUserId` hook:

```tsx
import { useUserId } from '~/core/hooks/use-user-id';

const userId = useUserId();
```

This is a React hook and can only be used inside a React component.

### Getting the user role within the organization with "useUserRole"

To retrieve the signed in user role of the current organization from the frontend, you can use the `useUserRole` hook:

```tsx
import { useUserRole } from '~/core/hooks/use-user-role';

const role = useUserRole();
```

This is a React hook and can only be used inside a React component.


Learn how to fetch the signed in user from the backend and frontend.

Fetching the signed in User


There are several ways to fetch the current selected organization, depending on the use-case.

## Fetching the selected Organization from the backend

You will use this function fairly often for fetching the current organization from the backend.

```tsx
import { NextApiRequest,NextApiResponse } from "next";
import { getCurrentOrganization } from '~/lib/server/organizations/get-current-organization';
import { withPipe } from '~/core/middleware/with-pipe';
import { withAuthedUser } from '~/core/middleware/with-authed-user';

async function handler(req: NextApiRequest, res: NextApiResponse) {
  const user = req.firebaseUser;
  const organization = await getCurrentOrganization(user.uid);
  // ...
}

export default withPipe(withAuthedUser, handler);
```

## Fetching the selected Organization from the frontend

The `withAppProps` middleware used in the gated app pages makes sure that the current organization is passed from the backend to the frontend.

### Getting the Organization with "useCurrentOrganization"

To retrieve the signed in user from the frontend, you can use the `useUserSession` hook:

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

const organization = useCurrentOrganization();
```

This is a React hook and can only be used inside a React component.

### Getting if the Organization subscription status is set to "active" on the frontend

You can use the `useIsSubscriptionActive` hook to get the subscription status of the current organization. You may want to use this function to gate access to certain parts of the app.

```tsx
const isActive = useIsSubscriptionActive();
```

This is a React hook and can only be used inside a React component.




Learn how to fetch the selected organization from the backend and frontend.

Fetching the selected Organization

Contextual Data


There is an important distinction to be made when using the Firebase SDK. Indeed, the SDK can be used in two different ways:

1. **Client SDK** - On the client, with minimal permissions (using the Firebase Security Rules), that allows clients to read and write data directly to the database only if they have the right permissions.
2. **Admin SDK** - On the server, with full permissions, that allows the server to read and write data directly to the database without any restriction.

Depending on the use case, you will need to use one or the other.

## Reading a Document with the Client SDK

The client SDK uses Reactfire to make it easier to fetch data directly from React components using React Hooks.

### Reading a Document with "useFirestoreDocData"

To read a single document, we can use the React Hook `useFirestoreDocData` from Reactfire. This hook takes a `DocumentReference` as a parameter and returns the data of the document as well as the status of the request.

In the example below, we fetch the data of a user document from the Firestore database. We can do so because we have the right permissions to read this document and the User ID is available in the React Context.

```tsx
import { doc, DocumentReference } from 'firebase/firestore';
import { useFirestore, useFirestoreDocData } from 'reactfire';
import { UserData } from '~/core/session/types/user-data';
import { useUserId } from '~/core/hooks/use-user-id';
import { USERS_COLLECTION } from '~/lib/firestore-collections';

function useFetchUser() {
  const firestore = useFirestore();
  const userId = useUserId() as string;

  const ref = doc(
    firestore,
    USERS_COLLECTION,
    userId
  ) as DocumentReference<UserData>;

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

export default useFetchUser;
```

### Breaking Down the Code

Let's break down the code above to understand what is happening.

#### 1. Importing the Reactfire Hooks

First, we import the Reactfire Hooks that we need to fetch the data from the Firestore database.

```tsx
import { doc, DocumentReference } from 'firebase/firestore';
import { useFirestore, useFirestoreDocData } from 'reactfire';
```

#### 2. Importing the User ID

We also import the User ID from the React Context. This is the ID of the user that is currently logged in.

```tsx
import { useUserId } from '~/core/hooks/use-user-id';
```

#### 3. Creating a Document Reference

We create a `DocumentReference` to the user document in the Firestore database. We use the `useFirestore` hook to get access to the Firestore instance.

```tsx
const firestore = useFirestore();
const userId = useUserId() as string;

const ref = doc(
  firestore,
  USERS_COLLECTION,
  userId
) as DocumentReference<UserData>;
```

The `USERS_COLLECTION` is a constant that contains the name of the collection in the Firestore database where the user documents are stored.

This would be `users` in Makerkit.

#### 4. Fetching the Data

Finally, we use the `useFirestoreDocData` hook to fetch the data of the user document. We pass the `DocumentReference` as a parameter and we specify the name of the field that contains the ID of the document.

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

### Reading a Document with "useFirestore"

Let's now see how we can read a document using the `useFirestore` hook from Reactfire from within a React component.

The `useFirestoreDocData` hook will return three values:
- `data` - The data of the document.
- `status` - The status of the request

We can use these values to display the data of the document in the React component in a reactive way.

```tsx
function UserComponent() {
  const { data, status } = useFetchUser();

  if (status === 'loading') {
    return <p>Loading...</p>;
  }

  if (status === 'error') {
    return <p>Error: {error.message}</p>;
  }

  return (
    <div>
      <p>{data.name}</p>
    </div>
  );
}
```

## Reading a document using the Firebase Admin SDK

While the API is similar, the Admin SDK is used in a different way. Indeed, the Admin SDK is used on the server, not on the client. This means that we can't use Reactfire to fetch data from the Firestore database.

The Admin SDK is used only in two cases:
1. When using an API Route
2. When using `getServerSideProps`

**Remember: The Admin SDK is not used in React components**. Similarly, the Web SDK is not used in API Routes or `getServerSideProps`.

### Reading the user from an API Route

Let's see how we can read a user document from an API Route.

Assuming we have a query parameter `userId` in the API Route, we can use the following code to read the user document from the Firestore database.

```ts
import { NextApiRequest, NextApiResponse } from 'next';
import { withAdmin as withFirebaseAdmin } from '~/core/middleware/with-admin';
import getRestFirestore from '~/core/firebase/admin/get-rest-firestore';

export default async function handler(
  req: NextApiRequest,
  res: NextApiResponse
) {
  await withFirebaseAdmin();

  const { userId } = req.query;
  const firestore = getRestFirestore();
  const usersCollection = firestore.collection('users');
  const user = await usersCollection.doc(userId).get();

  res.status(200).json(user);
}
```

Let's break down the code above to understand what is happening.

#### 1. Importing the Firebase Admin SDK

First, we import the Firebase Admin SDK.

```ts
import { withAdmin as withFirebaseAdmin } from '~/core/middleware/with-admin';
import getRestFirestore from '~/core/firebase/admin/get-rest-firestore';
```

The function `getRestFirestore` returns a Firebase Admin Firestore instance that uses `REST` instead of `gRPC`, because it's much faster in a serverless environment.

#### 2. Using the Firebase Admin SDK

We then use the Firebase Admin SDK to read the user document from the Firestore database.

```ts
await withFirebaseAdmin();

const { userId } = req.query;

const firestore = getRestFirestore();
const usersCollection = firestore.collection('users');
const user = await usersCollection.doc(userId).get();
```

We use the `withFirebaseAdmin` middleware to initialize the Firebase Admin SDK. This middleware must be called before using the Firebase Admin SDK.

We then use the `getRestFirestore` function to get a Firestore instance that uses `REST` instead of `gRPC`.

Finally, we use the Firestore instance to read the user document from the Firestore database.

#### 3. Returning the Data

Finally, we return the data of the user document as JSON.

```ts
res.status(200).json(user);
```

---

To learn more about the above, check out both the Firebase and Reactfire respective documentations.

Learn how to read a document from Firebase using both the Web SDK and the Admin SDK in your Next.js Firebase application

Reading a Document


## Reading a List of Documents with the Client SDK

The client SDK uses Reactfire to make it easier to fetch data directly from React components using React Hooks.

### Reading a List of Documents with "useFirestoreCollectionData"

In the example below, we will fetch a list of user organizations using the Firebase client SDK and Reactfire.

To do so, we use the React hook `useFirestoreCollectionData`, which allows us to stream real-time changes from a collection based on the filters provided.

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

import { useFirestore, useFirestoreCollectionData } from 'reactfire';
import { Organization } from '~/lib/organizations/types/organization';
import { ORGANIZATIONS_COLLECTION } from '~/lib/firestore-collections';

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

  const organizationsCollection = collection(
    firestore,
    ORGANIZATIONS_COLLECTION
  ) as CollectionReference<WithId<Organization>>;

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

  // we query Firestore for all the organizations
  // where the user is a member, therefore where he path
  // members.<user_id> is not null
  const constraint = where(userPath, operator, null);
  const organizationsQuery = query(organizationsCollection, constraint);

  return useFirestoreCollectionData(organizationsQuery, {
    idField: `id`,
    initialData: [],
  });
}
```

Breaking down the code above:

- We first import the `useFirestoreCollectionData` hook from `reactfire` and the `collection`, `where` and `query` functions from `firebase/firestore`.
- We then use the `useFirestore` hook to get access to the Firestore instance.
- We then create a reference to the `organizations` collection.
- We then create a query to fetch all the organizations where the user is a member.
- Finally, we use the `useFirestoreCollectionData` hook to fetch the data from Firestore.

### Using the Data

The `useFirestoreCollectionData` hook returns an object with the following properties:
- `data`: the data returned from Firestore
- `status`: the status of the request

```tsx
function UserOrganizations({
  userId,
}: React.PropsWithChildren<{
  userId: string;
}>) {
  const { data, status } = useFetchUserOrganizations(userId);

  if (status === 'loading') {
    return <p>Loading...</p>;
  }

  if (status === 'error') {
    return <p>Error</p>;
  }

  return (
    <ul>
      {data.map((organization) => (
        <li key={organization.id}>{organization.name}</li>
      ))}
    </ul>
  );
}
```

## Using the Admin SDK

The Admin SDK is used to read data from the server-side.

### Reading a List of Documents with "getDocs"

In the example below, we will fetch a list of user organizations using the Firebase Admin SDK.

```tsx
import getRestFirestore from '~/core/firebase/admin/get-rest-firestore';

export async function getOrganizationsForUser(userId: string) {
  const firestore = getRestFirestore();
  const organizationsCollection = firestore.collection('organizations');

  const result = await organizationsCollection
    .where(`members.${userId}`, '!=', null)
    .get();

  return result.docs.map((doc) => {
    return {
      ...doc.data(),
      members: [],
      id: doc.id,
      role: doc.data().members[userId].role,
    };
  });
}
```

You can use the function above in an API route or in a `getServerSideProps` function.

---

To learn more about the above, check out both the Firebase and Reactfire respective documentations.

Learn how to read a list of documents from Firebase using both the Web SDK and the Admin SDK in your Next.js Firebase application

Reading a list of Documents

Reading Data


Creating a document in Firestore can be achieved using both the Web (Client) and the Admin SDK (Server). Depending on the use-case, you will use one or the other.

1. **Client SDK**: When you want to create a document from the browser, you will use the Client SDK. This is the most common use-case, and can be done when the user has the permissions required to create a document based on their security rules.
2. **Admin SDK**: When you want to create a document from a server, you will use the Admin SDK. This is useful when you want to create a document from a server, or when you want to create a document that the user does not have permission to create.

## Client SDK

To create a document, we will use the `addDoc` function from the Web Firebase SDK.

We can use hooks to make sure we have access to the Firestore instance, and the collection we want to add the document to.

```tsx
import { useFirestore } from 'reactfire';
import { useCallback } from 'react';
import { addDoc, collection } from 'firebase/firestore';

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

  return useCallback(
    (task: {
      title: string;
      description: string;
      completed: boolean;
    }) => {
      return addDoc(tasksCollection, task);
    },
    [tasksCollection]
  );
}
```

We can then use this hook in our component to create a new task.

```tsx
import { useCallback } from "react";

const CreateTaskForm = () => {
  const createTask = useCreateTask();

  // ... other code

  const onSubmit = useCallback(async (task: {
    title: string;
    description: string;
    completed: boolean;
  }) => {
    await createTask(task);
  }, [createTask]);

  // ... other code
};
```

## Admin SDK

To create a document, we will use the `add` function from the Admin Firebase SDK.

We can use the Admin SDK only in API Route handlers and the `getServerSideProps` function. For two reasons:

1. The Admin SDK is for Node.js environments, and cannot be used in the browser.
2. The Admin SDK requires a service account, which should not be exposed to the browser.

```tsx
import getRestFirestore from '~/core/firebase/admin/get-rest-firestore';

async function addTaskFromServer(task: {
  title: string;
  description: string;
  completed: boolean;
}) {
  const firestore = getRestFirestore();
  const tasksCollection = firestore.collection(firestore, `tasks`);

  await tasksCollection.add(task);

  return task;
}
```

You can now use the function `addTaskFromServer` in your API Route handlers and `getServerSideProps` functions.

In this tutorial we show how you can create a document in Firestore using the Web and Admin SDKs.

Creating a Document


Updating a document in Firestore can be achieved using both the Web (Client) and the Admin SDK (Server). Depending on the use-case, you will use one or the other.

1. **Client SDK**: When you want to update a document from the browser, you will use the Client SDK. This is the most common use-case, and can be done when the user has the permissions required to update a document based on their security rules.
2. **Admin SDK**: When you want to update a document from a server, you will use the Admin SDK. This is useful when you want to update a document from a server, or when you want to update a document that the user does not have permission to update.

## Client SDK

To update a Firestore document, we will use the `addDoc` function from the Web Firebase SDK.

We can use hooks to make sure we have access to the Firestore instance, and the collection we want to add the document to.

```tsx
import { useFirestore } from 'reactfire';
import { useCallback } from 'react';
import { updateDoc, doc } from "firebase/firestore";

function useUpdateTask(id: string) {
  const firestore = useFirestore();
  const tasksDoc = doc(firestore, `/tasks`, id);

  return useCallback(
    (task: {
      title: string;
      description: string;
      completed: boolean;
    }) => {
      return updateDoc(tasksDoc, task);
    },
    [tasksDoc]
  );
}
```

We can then use this hook in our component to create a new task.

```tsx
import { useCallback } from "react";

const UpdateTaskForm = ({ id }: { id: string }) => {
  const updateTask = useUpdateTask(id);

  // ... other code

  const onSubmit = useCallback(async (task: {
    title: string;
    description: string;
    completed: boolean;
  }) => {
    await updateTask(task);
  }, [updateTask]);

  // ... other code
};
```

## Admin SDK

To create a document, we will use the `update` function from the Admin Firebase SDK.

We can use the Admin SDK only in API Route handlers and the `getServerSideProps` function. For two reasons:

1. The Admin SDK is for Node.js environments, and cannot be used in the browser.
2. The Admin SDK requires a service account, which should not be exposed to the browser.

```tsx
import getRestFirestore from '~/core/firebase/admin/get-rest-firestore';

async function updateTaskFromServer(task: {
  id: string;
  title: string;
  description: string;
  completed: boolean;
}) {
  const firestore = getRestFirestore();
  const taskRef = firestore.collection(firestore, `tasks`).doc(task.id);

  await taskRef.update(task);

  return task;
}
```

You can now use the function `updateTaskFromServer` in your API Route handlers and `getServerSideProps` functions.

Learn how to update a document in Firestore in your Next.js Firebase app

Updating a Document


Deleting a document in Firestore can be achieved using both the Web (Client) and the Admin SDK (Server). Depending on the use-case, you will use one or the other.

1. **Client SDK**: When you want to update a document from the browser, you will use the Client SDK. This is the most common use-case, and can be done when the user has the permissions required to delete a document based on their security rules.
2. **Admin SDK**: When you want to update a document from a server, you will use the Admin SDK. This is useful when you want to delete a document from a server, or when you want to delete a document that the user does not have permission to delete.

## Client SDK

To delete a document, we will use the `deleteDoc` function from the Web Firebase SDK.

We can use hooks to make sure we have access to the Firestore instance, and the collection we want to delete the document from.

```tsx
import { useFirestore } from 'reactfire';
import { useCallback } from 'react';
import { deleteDoc, doc } from "firebase/firestore";

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

  return useCallback(
    (taskId: string) => {
      const tasksDoc = doc(firestore, `/tasks`, taskId);

      return deleteDoc(tasksDoc);
    },
    [firestore]
  );
}
```

We can then use this hook in our component to create a new task.

```tsx
import { useCallback } from "react";

const DeleteTask = ({ id }: { id: string }) => {
  const deleteTask = useDeleteTask(id);

  // ... other code

  const onSubmit = useCallback(async (taskId: string) => {
    await deleteTask(taskId);
  }, [deleteTask]);

  // ... other code
};
```

## Admin SDK

To delete a Firestore document, we will use the `delete` function from the Admin Firebase SDK.

We can use the Admin SDK only in API Route handlers and the `getServerSideProps` function. For two reasons:

1. The Admin SDK is for Node.js environments, and cannot be used in the browser.
2. The Admin SDK requires a service account, which should not be exposed to the browser.

```tsx
import getRestFirestore from '~/core/firebase/admin/get-rest-firestore';

async function deleteTaskFromServer(task: {
  id: string;
}) {
  const firestore = getRestFirestore();
  const taskRef = firestore.collection(firestore, `tasks`).doc(task.id);

  await taskRef.delete();

  return task;
}
```

You can now use the function `deleteTaskFromServer` in your API Route handlers and `getServerSideProps` functions.

Learn how to delete a document in Firestore in your Next.js Firebase app

Deleting a Document

Writing Data


When taking payments from Stripe, you're required to configure your subscription's plans.

Your plans need to be configured in two places:

1. **Stripe** - first, you need to define your **products** and **plans** in Stripe itself. This requires you to have an account in Stripe.
2. **Configuration**: - then, you will copy your plans data in the Makerkit configuration, which is used to render the Pricing table and display the prices metadata

### 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_id>',
          trialPeriodDays: 7,
        },
        {
          name: 'Yearly',
          price: '$90',
          stripePriceId: '<price_id>',
          trialPeriodDays: 7,
        },
      ],
    },
    {
      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: 7,
        },
        {
          name: 'Yearly',
          price: '$200',
          stripePriceId: 'pro-plan-yr'
        },
      ],
    },
    {
      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: '',
          label: `Contact us`,
          href: `/contact`,
        },
      ],
    },
  ],
}
```

#### Update the Stripe Price IDs values!

Please replace the property `stripePriceId` with the real price ID from the
Stripe Dashboard.

<div>
  <Alert type="warn">
    <Alert.Heading>Update your real Stripe Price IDs</Alert.Heading>

    <div>
      The properties "stripePriceId" are placeholders. You will need to replace them with the IDs of your plans.
    </div>
  </Alert>
</div>

### 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


Learn how to configure the Stripe plans in your SaaS application with Makerkit

Configuring your SaaS Stripe Plans in your Makerkit Next.js Firebase App


When testing webhooks sent by Stripe, it's useful to redirect them to our local webhook endpoint so that we can test them locally.

Makerkit has a built-in NPM script that starts the Stripe CLI and redirects webhooks to our local endpoint.

## Prerequisites

The only prerequisite is to have Docker installed and running on your machine.

## Running the Stripe Webhook locally

To run the Stripe Webhook locally, run the following command:

```bash
npm run stripe:listen
```

The first time you run this command, it will ask you to login to your Stripe account. Follow the instructions on the screen to do so.

Once you're logged in, run the command again:

```bash
npm run stripe:listen
```

This time, the Stripe CLI will start and redirect webhooks to our local endpoint.

You can now test your webhooks locally when testing your Stripe integration with Makerkit 🎉


Want to test and run the Stripe Webhook locally? This guide will show you how to do it.

Running the Stripe Webhook locally


To use Lemon Squeezy instead of Stripe, you should use the branch `main-ls` to develop your SaaS.

The Lemon Squeezy configuration is slightly different from the Stripe configuration as it accepts a variant ID instead of a price ID.

```tsx
subscriptions: {
  plans: [
    {
      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',
          variantID: '<your variant ID>',
        },
        {
          name: 'Yearly',
          price: '$90',
           variantID: '<your variant ID>',
        },
      ],
    },
    {
      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',
           variantID: '<your variant ID>',
        },
        {
          name: 'Yearly',
          price: '$200',
          variantID: '<your variant ID>',
        },
      ],
    },
    {
      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',
          label: `Contact us`,
          href: `/contact`,
        },
      ],
    },
  ]
}
```

Please refer to the [complete Lemon Squeezy documentation](/docs/next-fire/lemon-squeezy) for more details.

How to use Lemon Squeezy instead of Stripe in your Makerkit application

Using Lemon Squeezy instead of Stripe in your Makerkit application

Payments


The translations of the application are stored at `public/locales/<en>`.

We have various translations languages JSON files by default (only in English):
- `public/locales/en/common.json` - where we store the common translations
- `public/locales/en/auth.json` - where we store the auth translations
- `public/locales/en/profile.json` - where we store the profile settings translations
- `public/locales/en/organization.json` - where we store the organization settings translations
- `public/locales/en/subscription.json` - where we store the subscription settings translations

You can keep adding translations to these files if you wish, or create new bundles for your translations.

## Adding a new translation string

Let's say we want to add a new translation string to the `common.json` file.

1. Open the `public/locales/en/common.json` file and add the new translation string:

```json
{
  "new_translation_string": "This is a new translation string"
}
```

You can then reference this key in your application like this:
1. Using the `Trans` component from `next-i18next`
2. Using the `useTranslation` hook from `next-i18next`

For example, using the `Trans` component:

```tsx
<Trans i18nKey="common:new_translation_string" />
```

or using the `useTranslation` hook:

```tsx
const { t } = useTranslation();
const newTranslationString = t('common:new_translation_string');
```


Adding new translations to your application is easy. This guide will show you how to add a new translation string to your application.

Adding a new translation string


Setting a default language in your Next.js Firebase application is easy.

Simply set the environment variable `DEFAULT_LOCALE` to the language code you want to use as the default language.

By default, we use `en` as the default language. If you want to change it, simply add the following line to your `.env` file. For example, if you want to use Spanish as the default language, you would add the following line to your `.env` file:

```bash
DEFAULT_LOCALE=es
```

Learn how to set a default language for your Makerkit application.

Setting a Default Language


To add a new locale to your application, you need to create a new file in the `public/locales` directory.

For example, to add a new language called `fr` (French), you would create a new file called `fr.json` in the `public/locales` directory.

```json
{
  "hello": "Bonjour"
}
```

That's it! Now you can use the `hello` key in your application and it will be translated to `Bonjour` when the locale is set to `fr`.

How to add a new language to your Next.js Firebase application.

Adding a new language


By default, the language switcher is not used within the Next.js Firebase starter. To use it, you will need to import it into your application and add it to your layout.

To do so, import the `LanguageSwitcher` component from the `components` directory and add it to any component you want to display it in.

```tsx
import { LanguageSwitcher } from '~/components/LanguageSwitcher';

export const YourComponent = ({ children }) => {
  return (
    <div>
      <LanguageSwitcher />
      {children}
    </div>
  );
};
```

The language switcher will automatically display the current language and a list of available languages. When a user clicks on a language, the language will be updated in the user's profile and the page will be reloaded.

Import and use the LanguageSwitcher component in your Next.js Firebase application.

Using the Language Switcher


To detect the currently selected locale from the client or the server, you can use the `useTranslation` hook from `next-i18next`.

```tsx
import { useTranslation } from 'next-i18next';

function Component() {
  const { i18n } = useTranslation();
  const { language } = i18n;

  // use language here
}
```


How to detect the currently selected locale so that you can use it in your React components.

Detecting the Currently selected locale

Translations

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 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`:

```
git remote rm origin
```

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.

### Why do we need to run the Supabase local environment?

The guide below will show you how to run the application locally. But why locally? Developing locally has many advantages over developing on a remote server:

**Speedy Development:** Local development lets you work without the hindrance of network latency or internet disruptions.

**Simplified Collaboration:** It's typically easier to collaborate with teammates when developing locally on the same project.

**Code-Based Configuration:** Any modifications to your collections via the Dashboard aren't reflected in code. Adopting local development workflows allows you to maintain all table schemas in code.

Once you are ready to deploy your application, you can do so by following the [production checklist guide](/docs/next-fire/going-to-production-overview).

### 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: '',
  },
  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

SERVICE_ACCOUNT_CLIENT_EMAIL=
GCLOUD_PROJECT=

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

STRIPE_SECRET_KEY=
STRIPE_WEBHOOK_SECRET=
```

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

Environment Variables


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.


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 { toast } from 'sonner';
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 toast.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 toast.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 { toast } from 'sonner';

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,
      };

      const promise = createTask(task).then(() => {
        return router.push(`/tasks`);
      });

      await toast.promise(promise, {
        success: `Task created!`,
        error: `Ops, error!`,
        loading: `Creating task...`,
      });
    },
    [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


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.


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.


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 internal 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.

### 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 CSS

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, Radix 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 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. Adding the remote to your own Git repository (if you haven't created a Git repository yet, you can do it later on)
3. Adding the original Makerkit repository as "upstream" so we can fetch updates from the main repository:

```
cd my-saas
git remote rm origin
git remote add origin <your-git-repository>
git remote add upstream git@github.com:makerkit/next-firebase-saas-kit.git
```

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

```
git pull upstream main
```

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

If you want to use the Lemon Squeezy branch, you'll need to switch to the `main-ls` branch:

```
git checkout main-ls
```

Of course, when pulling updates, you'll need to pull from the `main-ls` branch:

```
git pull upstream main-ls
```

### 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, and only needed when interacting with Stripe)

## About this Documentation

This documentation complements the Firebase one and is not meant to be a replacement. We recommend reading the Firebase documentation to get a better understanding of the Firebase concepts and how to use it.

### 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
npm 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
npm 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_SECRET=<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,
  theme: Themes.Light,
  features: {
    enableThemeSwitch: true,
    enableAccountDeletion: true,
    enableOrganizationDeletion: true,
  },
  navigation: {
    style: NavigationStyle.TopHeader,
  },
  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

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

SERVICE_ACCOUNT_CLIENT_EMAIL=
SERVICE_ACCOUNT_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=

SERVICE_ACCOUNT_CLIENT_EMAIL=

## SECRET KEYS ARE BEST ADDED TO YOUR CI
SERVICE_ACCOUNT_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=

# EMAIL
EMAIL_HOST=
EMAIL_PORT=587
EMAIL_USER=
EMAIL_PASSWORD=
EMAIL_SENDER='MakerKit Team <info@makerkit.dev>'
```

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.

## 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

Tutorials

Environment Variables

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

Adding Environment Variables

Subscribe to our Newsletter