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

How to


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

## What you will learn


1. Setting up your Makerkit Next.js Supabase 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 Supabase documentation.

Introduction to the How to section of the Makerkit Next.js Supabase 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 type { Provider } from '@supabase/gotrue-js/src/lib/types';

const production = process.env.NODE_ENV === 'production';

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,
    siteName: 'Awesomely',
    twitterHandle: '',
    githubHandle: '',
    language: 'en',
    convertKitFormId: '',
    locale: process.env.NEXT_PUBLIC_DEFAULT_LOCALE,
  },
  auth: {
    // ensure this is the same as your Supabase project. By default - it's true
    requireEmailConfirmation:
      process.env.NEXT_PUBLIC_REQUIRE_EMAIL_CONFIRMATION === 'true',
    // NB: Enable the providers below in the Supabase Console
    // in your production project
    providers: {
      emailPassword: true,
      phoneNumber: false,
      emailLink: false,
      oAuth: ['google'] as Provider[],
    },
  },
  production,
  environment: process.env.NEXT_PUBLIC_ENVIRONMENT,
  features: {
    enableThemeSwitcher: true,
  },
  theme: Themes.Dark,
  paths: {
    signIn: '/auth/sign-in',
    signUp: '/auth/sign-up',
    signInMfa: '/auth/verify',
    onboarding: `/onboarding`,
    appPrefix: '/dashboard',
    appHome: '/dashboard',
    authCallback: '/auth/callback',
    settings: {
      profile: 'settings/profile',
      authentication: 'settings/profile/authentication',
      email: 'settings/profile/email',
      password: 'settings/profile/password',
    },
  },
  sentry: {
    dsn: process.env.NEXT_PUBLIC_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/components/Fonts.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/components/Fonts.tsx` to remove the `Apple` font.

```tsx title="src/components/Fonts.tsx" {26-27}
'use client';

import { Inter as SansFont } from 'next/font/google';
import { useServerInsertedHTML } from 'next/navigation';

const sans = SansFont({
  subsets: ['latin'],
  variable: '--font-family-sans',
  fallback: ['system-ui', 'Helvetica Neue', 'Helvetica', 'Arial'],
  preload: true,
  weight: ['300', '400', '500', '600', '700', '800'],
});

// replace with your heading font
// by default, it will use the sans font
const heading = sans;

function Fonts() {
  useServerInsertedHTML(() => {
    return (
      <style
        key={'fonts'}
        dangerouslySetInnerHTML={{
          __html: `
          :root {
            --font-family-sans: ${sans.style.fontFamily}, 'Segoe UI', 'Roboto', 'Ubuntu', 'sans-serif';
            --font-family-heading: ${heading.style.fontFamily};
          }
        `,
        }}
      />
    );
  });

  return null;
}

export default Fonts;
```

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
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 the root layout:

```tsx title="app/layout.tsx"
icons: {
  icon: '/assets/images/favicon/favicon.ico',
  shortcut: '/shortcut-icon.png',
  apple: '/assets/images/favicon/apple-touch-icon.png',
  other: {
    rel: 'apple-touch-icon-precomposed',
    url: '/apple-touch-icon-precomposed.png'
  },
}
```

Update the paths 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 Supabase. These have to be setup
from within the Supabase Dashboard. You can reuse the same SMTP settings.

### 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 to allow you testing your emails without using a real
SMTP service. You can access InBucket at [localhost:54324](http://localhost:54324)

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 `src/app/(site)` directory.

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

As you know already, we can add pages to our Next.js App Router application by creating files within the `src/app` directory named as `page.tsx`.

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

```tsx title="src/app/(site)/about/page.tsx"
function AboutPage() {
  return <div>About page</div>;
}

export default AboutPage;
```

This page will **automatically inherit the site layout** from `src/app/(site)/layout.tsx` - which means it will already display the header and footer.

#### I don't want to use the same layout though?

If you don't want to use the site layout, create a route group inside `src/app`, and add your page there.

### Adding a new page to the marketing site with translations

If you have translations on your marketing site - to ensure the page is translated correctly server-side, we use the `withI18n` HOC:

```tsx title="src/app/(site)/about/page.tsx"
import { withI18n } from '~/i18n/with-i18n';

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

export default withI18n(AboutPage);
```


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

Adding pages to the marketing site of your Makerkit Next.js Supabase 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`.

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 with your color palette.

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


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 (App Router) project. Let's see how.

## Creating an API Route

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

Here's an example of an API route that returns a JSON response as response to a `GET` request.

```ts title="app/hello/route.ts"
import { NextResponse } from "next/server";

export function GET() {
  return NextResponse.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 `requireSession` function.

In the example below, we create a `POST` API route that requires the user to be authenticated. If the user is not authenticated, the user will be redirected away. Additionally, the `requireSession` function will also ensure the level access if the user opted in to multi factor authentication.

```ts title="app/hello/route.ts"
import { NextRequest } from "next/server";

import getSupabaseRouteHandlerClient from '~/core/supabase/route-handler-client';
import requireSession from '~/lib/user/require-session';

export async function POST(req: NextRequest) {
  const client = getSupabaseRouteHandlerClient();
  const session = await requireSession(client);

  // user is authenticated, do something here
}
```

### CSRF Token

By default, all API routes are protected against CSRF attacks if they use a mutation method. This means that you need to send a CSRF token with every request.

To add a CSRF token to your request, you can use the `useCsrfToken` React hook. This function will return a CSRF token that you can use in your request.

POST requests without a CSRF token will return a `403` error. This can be disabled in the middleware `src/middleware.ts`.

API Routes allow you to create server endpoints in your Next.js App that you can call from your client or from external sources

Adding API Routes in your Next.js application


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. For example:

1. When interacting with the Supabase Client (DB, Storage, Auth, etc.)
2. When making requests 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.

### Should I use SWR or Server Actions?

No exact answer - but here is what I do:

1. For pure mutations, I prefer Server Actions.
2. For pulling data from the server-side as a result of user interactions, I use SWR.

Ultimately, you should use what you feel more comfortable with as both approaches are valid.

## 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/route.ts"
import { NextResponse } from "next/server";

export async function GET() {
  return NextResponse.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` table, and return the ID back to the client.

```tsx
import { NextRequest, NextResponse } from "next/server";

export async function POST(
  req: NextRequest
) {
  const client = getSupabaseRouteHandlerClient();
  const session = await requireSession(client);
  const task = req.json();

  const { data } = await client.from('tasks').insert({
    name: task.name,
    done: false,
    user_id: session.user.id,
  })
  .select('id')
  .single();

  return NextResponse.json({ id: data.id });
}
```

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


API Routes and Server Actions can indeed be used in similar ways: ultimately, they both allow you to write server-side code that can be called from the client-side. However, let's look at the use-cases for each of them to understand the differences.

#### TLDR

TLDR; Use API Routes when fetching data, and Server Actions when performing actions/mutations.

## API Routes

API Routes are more generic and a lower-level abstraction than Server Actions. They are a way to write server-side code that can be called from the client-side. They are a great way to expose a REST API, or to write server-side code that can be called from the client-side.

The downside of API Routes is that they need to be called using the Fetch API, which you can use directly, or through a library such as React Query or SWR. This kit uses SWR.

Generally speaking, API Routes should be preferred when fetching data - rather than performing actions/mutations.

## Server Actions

Unlike API Routes, Server Actions are a higher-level abstraction. They are a way to write server-side code that can be called from the client-side as POST requests.

They are particularly useful when you want to perform actions/mutations on the server-side, such as creating a new user, or updating a user's profile.

Thanks to utilities such as `revalidatePath` and `revalidateTag`, you can also use Server Actions to invalidate the cache of a specific page or tag (used with `fetch`).

API routes and Server actions can be used for similar use cases. This guide will help you understand the differences between the two.

API Routes vs Server Actions

API Routes


Makerkit makes extensive use of Next.js Server Actions to mutate data in your Supabase database.

Server Actions are a powerful feature of Next.js that allow you to write server-side code that we can call from the client-side. This is useful for a number of reasons:
1. We don't need to write any API routes to handle our server-side logic
2. We can tell Next.js to revalidate our data after a server action has been called, thus refreshing our data on the client-side
3. We can easily call them just like any other function in our code

<Alert>
  This page is important to explain how we can handle Supabase mutations in the next sections.
</Alert>

## Creating a Server Action

To create a server action, we need to create a separate file marked with the `use server` directive at the top of the file. This tells Next.js that this file contains a server action that we can call from the client-side.

```tsx
'use server';

export async function handleFormSubmit(
  formData: FormData
) {
  // Do something with the form data
}
```

## Calling a Server Action

Calling a server action can be done in several ways

1. Calling it from a form submit handler
2. Calling it from a button click handler
3. Calling it imperatively as a function

### Calling it from a form submit handler

Let's assume we defined our server actions in a file called `actions.ts`:

```tsx
'use server';

export async function createPostAction(
  formData: FormData
) {
  // Do something with the form data
}
```

We can call this server action from a form submit handler like so:

```tsx
<form action={createPostAction}>
  <div className='flex flex-col space-y-4'>
    <h2 className='text-lg font-semibold'>Create a new Post</h2>

    <Label className='flex flex-col space-y-1.5'>
      <span>Title</span>
      <Input name='title' placeholder='Ex. The best Next.js libraries' required />
    </Label>

    <Label className='flex flex-col space-y-1.5'>
      <span>Description</span>
      <Input />
    </Label>

    <SubmitButton />
  </div>
</form>
```

### Calling it from a button click handler

We can also call a server action from a button click handler:

```tsx
<form action={createPostAction}>
  <div className='flex flex-col space-y-4'>
    <h2 className='text-lg font-semibold'>Create a new Post</h2>

    <Label className='flex flex-col space-y-1.5'>
      <span>Title</span>
      <Input name='title' placeholder='Ex. The best Next.js libraries' required />
    </Label>

    <Label className='flex flex-col space-y-1.5'>
      <span>Description</span>
      <Input />
    </Label>

    <button formAction={createPostAction}>Click</button>
  </div>
</form>
```

### Calling it imperatively as a function

Finally, we can call a server action imperatively as a function using `startTransition`:

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

function ClientComponent({ id }) {
  let [isPending, startTransition] = useTransition();

  return (
    <button onClick={() => startTransition(() => createPostAction(id))}>
      Save
    </button>
  );
}
```

## Send CSRF token with server actions

Remember: Makerkit protects by default every POST request with a CSRF token. This is a security measure to prevent CSRF attacks.

It's your job to send this along when you call a server action.

Learn how to write a server action in your Next.js Supabase SaaS application

Server Actions


Makerkit's Middleware ensures that POST requests to your server actions are protected against CSRF attacks. This means that you need to send a CSRF token with every POST request to your server actions. The only instance where you need to manually protect your Actions is when you use forms that send data using `FormData`.

## Getting the CSRF Token

To retrieve the CSRF token to send along with your requests, use the `useCsrfToken` hook. This hook returns the CSRF token as a string.

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

// somehwere in your component
const token = useCsrfToken();
```

## Sending the CSRF Token

When you call a Server Action, simply add the token as `csrfToken` in the parameters object.

For example, assuming this is our Server Action:

```tsx
type CreateTaskParams = {
  task: Omit<Task, 'id'>;
  csrfToken: string;
};

export const createTaskAction = withSession(
  async (params: CreateTaskParams) => {
    const client = getSupabaseServerActionClient();
    const session = await requireSession(client);
    const uid = await parseOrganizationIdCookie(session.user.id);
    const path = `/dashboard/${uid}/tasks`;

    await createTask(client, params.task);

    // revalidate the tasks page
    revalidatePath(path, 'page');

    // redirect to the tasks page
    redirect(path);
  },
);
```

NB: we added `csrfToken` to the `CreateTaskParams` type.

Then, we can call the Server Action like this:

```tsx
import { useTransition } from "react";
import useCsrfToken from '~/core/hooks/use-csrf-token';

function TaskForm() {
  const csrfToken = useCsrfToken();
  const [isMutating, startTransition] = useTransition();

  const onSubmit = (task: Task) => {
    startTransition(async () => {
      await createTaskAction({ task, csrfToken });
    });
  };
}
```

As you can see, we're passing an object with two properties: `task` and `csrfToken`. The `csrfToken` property is the one that will be used to send the CSRF token to the server.

## Using "FormData"

When using plain forms, we can pass the CSRF token as an input field.

```tsx
function TaskForm() {
  const csrfToken = useCsrfToken();

  return (
    <form action={createTaskAction}>
      <input type={'hidden'} name={'csrfToken'} value={csrfToken} />
    </form>
  );
}
```

In your server action, you will manually need to extract the CSRF token from the request body and verify it using the `verifyCsrfToken` function.

```tsx
import verifyCsrfToken from '~/core/verify-csrf-token';

export const createTaskAction = async (data: FormData) => {
  const csrfToken = data.get('csrfToken');

  await verifyCsrfToken(csrfToken);

  // ...
};
```

Learn how to send CSRF tokens to server actions in Makerkit.

Sending CSRF Token to Server Actions


Generally speaking, you can handle Server Action in three ways:

1. You can use the `try/catch` block to catch errors and handle them in the `catch` block.
2. You can use a React `ErrorBoundary` component to catch errors
3. You can also use the special `error.tsx` file to handle errors at layout level.

### Handling errors from a Server Action invoked by a Form

Let's assume we have a Form using a server action that throws an error:

```tsx title='Form.tsx'
async function serverActionWithError() {
  'use server';

  throw new Error(`This is error is in the Server Action`);
}

function FormWithServerAction() {
  return (
    <form action={serverActionWithError}>
      <button>Submit Form</button>
    </form>
  );
}

export default FormWithServerAction;
```

We can wrap our form using the `ErrorBoundary` component we have at `~/core/ui/ErrorBoundary`, and handle the error from there:

```tsx title='FormWithErrorBoundary.tsx'
import ErrorBoundary from '~/core/ui/ErrorBoundary';
import FormWithServerAction from './Form';

function FormWithErrorBoundary() {
  return (
    <ErrorBoundary fallback={<p>Something went wrong</p>}>
      <FormWithServerAction />
    </ErrorBoundary>
  );
}
```

If you click on the button, you'll see the error message rendered.

### Handling errors from an imperatively invoked Server Action

If you are invoking a Server Action imperatively, we can wrap the `useTransition` hook in a `try/catch` block, and handle the error from there.

Let's assume we have a Server Action that throws an error:

```tsx title='actions.tsx'
'use server';

export async function serverActionWithError() {
  throw new Error(`This is error is in the Server Action`);
}
```

We can invoke it imperatively from a client component, and handle the error from there:

```tsx title='ImperativeServerAction.tsx'
'use client';

import { useTransition } from 'react';
import { serverActionWithError } from './actions';

function ImperativeServerAction() {
  const [pending, startTransition] = useTransition();

  return (
    <button
      disabled={pending}
      onClick={() => {
        startTransition(async () => {
          try {
            await serverActionWithError()
          } catch (e) {
            alert('error');
          }
        });
      }}
    >
      Click Button
    </button>
  );
}

export default ImperativeServerAction;
```

If you click on the button, you'll see the `alert` popup with the error message.

Learn how to handle errors in Server Actions in Makerkit.

How to handle errors in Server Actions


To add a new page to the application site of your Next.js project, you can create a new page in the `src/app/dashboard` directory.

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

The vast majority of the "private" pages of your application will be located in the `src/app/dashboard/[organization]` directory.
This directory contains the pages that are **only accessible to authenticated users**, and that are **related to a specific organization**.

### Layout and Sidebar

Pages created within the directory `src/app/dashboard/[organization]` will inherit the layout of the directory and will be displayed together with the Sidebar menu.

### Example - Creating a new page

For example, let's create a `Tasks` application located at `src/app/dashboard/[organization]/tasks`. We will then create a new page at `src/app/dashboard/[organization]/tasks/page.tsx`.

```tsx title="src/app/dashboard/[organization]/tasks/page.tsx"
import {
  RectangleStackIcon,
} from '@heroicons/react/24/outline';

import Trans from '~/core/ui/Trans';
import { withI18n } from '~/i18n/with-i18n';

import AppHeader from '~/app/dashboard/[organization]/components/AppHeader';
import AppContainer from '~/app/dashboard/[organization]/components/AppContainer';

interface TasksPageParams {
  params: {
    organization: string;
  };
}

// we will implement this function later
async function loadTasksData({ organizationUid }: { organizationUid: string}) {
  // ...
}

async function TasksPage({ params }: TasksPageParams) {
  const { tasks } = await loadTasksData({
    organizationUid: params.organization,
  });

  return (
    <>
      <AppHeader>
        <span className={'flex space-x-2'}>
          <RectangleStackIcon className="w-6" />

          <span>
            <Trans i18nKey={'common:tasksTabLabel'} />
          </span>
        </span>
      </AppHeader>

      <AppContainer>
        {/* ... */}
      </AppContainer>
    </>
  );
}

export default withI18n(
  TasksPage
);
```

Let's break down what we did here:

1. We created a new page at `src/app/dashboard/[organization]/tasks/page.tsx`. This page will be accessible at `/dashboard/[organization]/tasks`.
2. We created a `loadTasksData` function that will be used to load the data of the page. This is only a mock function for now, we will implement it later.
3. We created a `TasksPage` component that will be used to render the page. This component is a Next.js Server Page component, so it must be exported as default.
4. We wrapped the `TasksPage` component with the `withI18n` HOC. This HOC will ensure translations are loaded and available in the component.

### Translations

Always add the `withI18n` HOC to your pages to ensure translations are loaded and available in the component when using Server Components (pages or layouts).

### Layout

Layout-wise, we added the following components:

1. An `AppHeader` component that will be used to render the header of the page. This component is located at `src/app/dashboard/[organization]/components/AppHeader.tsx`.
2. An `AppContainer` component that will be used to render the content of the page. This component is located at `src/app/dashboard/[organization]/components/AppContainer.tsx`.

You can omit these components if you don't need them.

### Page Parameters

Because the `TasksPage` component is located at `src/app/dashboard/[organization]/tasks/page.tsx`, it will receive the following parameters:

```tsx
interface TasksPageParams {
  params: {
    organization: string;
  };
}
```

This means we can access the parameter `organization` in the `TasksPage` component:

```tsx
async function TasksPage({ params }: TasksPageParams) {
  const { tasks } = await loadTasksData({
    organizationUid: params.organization,
  });

  return (
    <>
      {/* ... */}
    </>
  );
}
```

The `organization` parameter is the organization UID of the organization the user is currently viewing. You can use this parameter to fetch the data related to the organization.

## Building pages outside of the organization context

If you need to build a page that is not related to a specific organization, you can create it in the `src/app/dashboard` directory.

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

Adding pages to the application of your Makerkit Next.js Supabase 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 = (organization: string) => ({
  items: [
    {
      label: 'common:dashboardTabLabel',
      path: getPath(organization, configuration.paths.appHome),
      Icon: ({ className }: { className: string }) => {
        return <Squares2X2Icon className={className} />;
      },
    },
    {
      label: 'common:tasksTabLabel',
      path: getPath(organization, 'tasks'),
      Icon: ({ className }: { className: string }) => {
        return <Square3Stack3DIcon className={className} />;
      },
    },
    {
      label: 'common:settingsTabLabel',
      path: getPath(organization, 'settings'),
      Icon: ({ className }: { className: string }) => {
        return <Cog8ToothIcon className={className} />;
      },
    },
  ],
});

function getPath(organizationId: string, path: string) {
  const appPrefix = configuration.paths.appPrefix;

  return [appPrefix, organizationId, path].filter(Boolean).join('/');
}

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


As a server-side rendered application, Next.js Supabase will always render the page on the server before sending it to the client.

**We assume you are in the context of a specific organization, as it is the primary use case for the Starter Kit.**

We can use the function `loadAppData` to get data required to load the main layout of the app located at `app/dashboard/[organization]`.

NB: you can call `loadAppData` multiple times because it uses caching.

In the following example, we are loading the user role within the organization **that is currently selected**.

```tsx
import { redirect } from "next/navigation";

import loadAppData from '~/lib/server/loaders/load-app-data';
import MembershipRole from '~/lib/organizations/types/membership-role';

async function OnlyOwnersPage() {
  const data = await loadAppData();
  const userRole = data.role;

  // if the user is not an owner, redirect them to the home page
  if (userRole !== MembershipRole.Owner) {
    redirect('/');
  }

  // render the page
}
```

As you can see above:
1. We are loading the data required to render the page
2. We are checking the user role within the organization
3. If the user is not an owner, we redirect them to the home page (but feel free to change this)

## 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 { redirect } from "next/navigation";
import loadAppData from '~/lib/server/loaders/load-app-data';

async function OnlySubscribersPage() {
  const data = await loadAppData();
  const status = data.organization.subscription?.data?.status;

  // if the subscription is not active, redirect the user to the dashboard
  if (!isSubscriptionActive(status)) {
    redirect('/');
  }

  // render the page
}

function isSubscriptionActive(status: string | undefined) {
  return ['trialing', 'active'].includes(status);
}
```

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

Guarding Pages

Application Pages


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

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

```ts
import type { Provider } from '@supabase/gotrue-js/src/lib/types';

// in your configuration JSON
auth: {
  // ensure this is the same as your Supabase project. By default - it's true
  requireEmailConfirmation:
    process.env.NEXT_PUBLIC_REQUIRE_EMAIL_CONFIRMATION === 'true',
  // NB: Enable the providers below in the Supabase Console
  // in your production project
  providers: {
    emailPassword: true,
    phoneNumber: false,
    emailLink: false,
    oAuth: ['google'] as Provider[]
  },
},
```

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: ['google'] as Provider[],
},
```

### 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: ['google'] as Provider[],
},
```

### 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: ['google'] as Provider[]
},
```

### 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
providers: {
  emailPassword: false,
  phoneNumber: false,
  emailLink: false,
  oAuth: ['google', 'facebook'] as Provider[]
},
```

The interface `Provider` is very important as it tells Makerkit which OAuth provider to use. You can find the list of [supported OAuth providers here](https://supabase.io/docs/guides/auth#third-party-logins).

## 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: ['google', 'facebook'] as Provider[]
},
```

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


For oAuth - you can enable multiple providers. For example, you can enable Google and Facebook authentication at the same time by adding the providers to the `auth.providers.oAuth` array in the configuration file at `src/configuration.ts`.

You must configure the oAuth providers in three places:
1. **Supabase** - you need to setup an oAuth application in Supabase.
2. **Provider** - you need to setup an oAuth application in the provider (for example, Google Auth)
3. **Makerkit Configuration** - you need to add the provider to the `auth.providers.oAuth` array in the configuration file at `src/configuration.ts`.

Below is an example of how to enable Google and Facebook authentication:

```tsx title="src/configuration.ts" {5}
providers: {
  emailPassword: false,
  phoneNumber: false,
  emailLink: false,
  oAuth: ['google', 'facebook'] as Provider[]
},
```

The interface `Provider` is very important as it tells Makerkit which OAuth provider to use. You can find the list of [supported OAuth providers here](https://supabase.io/docs/guides/auth#third-party-logins).

By default, Makerkit provides logos for the most famous oAuth providers, but not all of them. To add a logo for an oAuth provider, please update the `src/core/ui/AuthProviderLogo.tsx` file.

You will provide a string or a React node for the logo by specifying the provider name as the key of the object.

```tsx title="src/core/ui/AuthProviderLogo.tsx"
function getOAuthProviderLogos(): Record<string, string | React.ReactNode> {
  return {
    password: <AtSymbolIcon className={'h-[22px] w-[22px]'} />,
    phone: <DevicePhoneMobileIcon className={'h-[22px] w-[22px]'} />,
    google: '/assets/images/google.webp',
    facebook: '/assets/images/facebook.webp',
    twitter: '/assets/images/twitter.webp',
    github: '/assets/images/github.webp',
    microsoft: '/assets/images/microsoft.webp',
    apple: '/assets/images/apple.webp',
  };
}
```

### How to Setup an oAuth Provider

Most of the setup is done in two places:

1. **Supabase** - you need to setup an oAuth application in Supabase.
2. **Provider** - you need to setup an oAuth application in the provider (for example, Google Auth)

To know more about how to setup an oAuth provider, please read the [Supabase documentation](https://supabase.io/docs/guides/auth#third-party-logins).

Learn how to setup oAuth in the Next.js Supabase Starter

How to setup oAuth in the Next.js Supabase Starter

Authentication


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 `requireSession`, which also takes care of redirecting the user to the login page if they are not signed in, and checking the correct MFA access level if the user opted in.

You can use this function in:
- API Routes
- Server Actions
- Server Components

### Using "requireSession" in API Routes

When using API routes, you can retrieve the signed in user using the `requireSession` function.

```tsx
import getSupabaseRouteHandlerClient from '~/core/supabase/route-handler-client';
import requireSession from '~/lib/user/require-session';

export async function POST() {
  const client = getSupabaseRouteHandlerClient();
  const session = await requireSession(client);
}
```

### Using "requireSession" in Server Actions

When using server actions, you can retrieve the signed in user using the `requireSession` function.

```tsx
'use server';

import getSupabaseRouteHandlerClient from '~/core/supabase/route-handler-client';
import requireSession from '~/lib/user/require-session';

export async function yourServerAction() {
  const client = getSupabaseRouteHandlerClient();
  const session = await requireSession(client);

  // use session here
}
```

### Using "requireSession" in Server Components

You can use the `requireSession` function in Server Components as well.

```tsx
async function PageComponent() {
  const client = getSupabaseServerComponentClient();
  const session = await requireSession(client);

  // use session here
}
```

## Fetching the signed in user from the frontend

When in the scope of the `app/dashboard/[organization]` layout, the app automatically injects the user session in the context layout.

This includes the user ID, email, and other authentication data, as well as the user's Supabase DB record.

### 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();
```

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 useCurrentUserRole from '~/core/hooks/use-current-user-role';

const role = useCurrentUserRole();
```

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.

## Getting the selected Organization ID

Getting the selected organization ID is done using different ways depending on the context.

1. If you are in a Server Component under the `[organization]` route, the `organizationUid` is passed as a prop to the component. You can match the `organizationUid` with the `uuid` property of the organization.
2. If you're not, use the cookie utility `parseOrganziationCookie` to get the `organizationUid` from the cookie. This is scoped by user, so you will need to pass the `userId` as well.

### Using "parseOrganizationIdCookie" to get the Organization ID

You can use the `parseOrganizationIdCookie` function in:

- API Routes
- Server Actions
- Server Components

```tsx
import getSupabaseServerActionClient from '~/core/supabase/action-client';
import { parseOrganizationIdCookie } from '~/lib/server/cookies/organization.cookie';
import requireSession from '~/lib/user/require-session';

async function getOrganizationId() {
  const client = getSupabaseServerActionClient();
  const session = await requireSession(client);

  return parseOrganizationIdCookie(session.user.id);
}
```

This can be nullish, so remember to check for that.

## Fetching the selected Organization from the backend

To do so, use the function `getCurrentOrganization`, which also takes care of redirecting the user to the login page if they are not signed in, and checking the correct MFA access level if the user opted in.

You can use this function in:
- API Routes
- Server Actions
- Server Components

This function requires the current user ID and the (optionally) organization UID.

1. Get the current user ID from the session: we use the `requireSession` helper to do so.
2. Get the organization: we use the `getCurrentOrganization` helper to do so using the user ID and the organization UID.

```tsx
const client = getSupabaseRouteHandlerClient();
const session = await requireSession(client);
const userId = session.user.id;

const organizationResponse = await getCurrentOrganization({
  organizationUid,
  userId,
});
```

## Fetching the selected Organization from the frontend

Within the `[organization]` context, the layout loader passes the current organization is passed from the backend to the frontend using the Context API. Therefore, we can require it using the `useCurrentOrganization` hook.

### 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
import useCurrentOrganization from '~/lib/organizations/hooks/use-is-subscription-active';

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


The Makerkit repository adds some seed data by default for running the E2E tests.

To update the seed data, you will update the SQL file `supabase/seed.sql`. This file contains the SQL code that seeds the database everytime you start the Supabase Server using `npm run supabase:start`.

### Adding data to the seed file

If you'd like to extend this data with your own, update the data in your local environment, either by using your application or using the Supabase Studio interface.

Then, you can run the `diff` command:

```
supabase diff
```

This command will output the SQL code with the difference between the seed data and the current local DB data. You can copy and paste the outputted data into your `seed.sql` file.

The next database restarts will use the new data inserted.


Learn how to seed data in your Supabase Database

How to seed data in your Supabase application


Resetting the DB can be useful when updating the schema of your database using the SQL schema files instead of the Supabase Studio UI.

To reflect the new changes, and/or resetting the database to the local seed, run the following command:

```
npm run supabase:db:reset
```

The database is now in the same state as when you started your Supabase server.

**Important**: users created during the session will be reset, which means your application may be in a conflicting state. Log out or delete the cookies to restart from scratch.

Learn how to reset the seed data in your Supabase Database

How to reset your local Database


When you change your Database schema, you need to also remember to update the Typescript types that the Supabase Client can use to strong-type your queries and mutations.

Following a change in the schema, you need to do two things:

1. **Reset the Database**: if you have changed the schema manually, e.g. updating the SQL code, you need to either reset or restart your Supabase instance. You can do so using the command `npm run supabase:db:reset`
2. **Generate the new type definitions**: now, you can run the command `npm run typegen` to generate the types. The generated file will be available at `src/database.types.ts`

That's it! Always remember to update your schema types after changing your database schema.

Learn how to generate your Supabase Database types using the typegen command

How to generate your Supabase Database types

Database


In Makerkit, we define all the queries in their own file (depending on their feature) named `queries.ts`.

Assuming we have a table named `tasks` with the following schema:

```sql
create table tasks (
  id serial primary key,
  name text,
  organization_id integer references organizations not null,
  due_date timestamp,
  description text,
  done boolean default false
);
```

We can define a query to read a single task from the table:

```tsx
import type { SupabaseClient } from '@supabase/supabase-js';
import type { Database } from '~/database.types';

export function getTask(client: SupabaseClient<Database>, id: number) {
  return client
    .from('tasks')
    .select(
      `
      id,
      name,
      organizationId: organization_id,
      dueDate: due_date,
      description,
      done
    `,
    )
    .eq('id', id)
    .single();
}
```

The `single` modifier will return a single record from the database. If no record is found, it will throw an error. If you want to return `null` instead, you can use the `maybeSingle` modifier.

## Usage

You can now use the function above anywhere in the following layers:

1. API routes
2. React Server Components
3. React Client Components
4. Server Actions

In fact, we can import the Supabase client both on the browser and on the client.

### Backend

Assuming we want to read a task from a Server component, such as the Task page, we can do the following:

```tsx
interface Context {
  params: {
    task: string;
  };
}

const TaskPage = async ({ params }: Context) => {
  const data = await loadTaskData(params.task);
  const task = data.task;

  return (
    <>
      <h1>{task.name}</h1>
      <p>{task.description}</p>
    </>
  );
};

async function loadTaskData(taskId: string) {
  const client = getSupabaseServerComponentClient();
  const { data: task } = await getTask(client, Number(taskId));

  if (!task) {
    redirect('/dashboard');
  }

  return {
    task,
  };
}

export default TaskPage;
```

### Frontend

You can also choose to read the task from the frontend. This is useful if you want to use the data in a React component.

To do so, we use the **Supabase Web SDK client** using the hook `useSupabase` and combine it with SWR to fetch the data.

This is useful because you can fetch data directly from the client, which is extremely useful in scenarios such as loading data on-demand resulting from user interactions (click a table row, opening a modal, etc.)

```tsx
import useSWR from "swr";

function useFetchTask({id}: {id: number}) {
  const supabase = useSupabase();
  const key = ['tasks', id];

  return useSWR([key], async () => {
    return getTask(supabase, id);
  });
}
```

We can then use the hook in a React component:

```tsx
function TaskComponent({ id }: { id: number }) {
  const { data: task, isLoading, error } = useFetchTask({ id });

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

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

  return (
    <>
      <h1>{task.name}</h1>
      <p>{task.description}</p>
    </>
  );
}
```

Learn how to read records from Supabase using Next.js Supabase application

Reading Records from Postgres

Reading Data


Creating a record with Supabase is easy. We can use the `insert` method to create a record in a table.

We combine the mutation with Next.js Server Actions so that we get data revalidation on-the-fly - pretty magical! 🧙‍♂️

The Makerkit convention is to store these in files called `mutations.ts` in the `lib` folder of your entity.

For example, here is a mutations file for a `task` entity.

```tsx
import type { SupabaseClient } from '@supabase/supabase-js';
import type { Database } from '~/database.types';

type Task = {
  id: string;
  name: string;
  organizationId: string;
  description: string;
  dueDate: Date;
  done: boolean;
};

export function createTask(
  client: SupabaseClient<Database>,
  task: Omit<Task, 'id'>
) {
  return client.from('tasks').insert({
    name: task.name,
    organization_id: task.organizationId,
    description: task.description,
    due_date: task.dueDate,
    done: task.done,
  });
}
```

Ideally, the `Task` interface is defined externally, but I am showing it here for simplicity and clarity.

### Calling the mutation in a Server Action

We can now export a server action that uses this function to create a task.

```tsx
'use server';

import { revalidatePath } from 'next/cache';
import { redirect } from 'next/navigation';

import { createTask } from '~/lib/tasks/mutations';
import type Task from '~/lib/tasks/types/task';
import { withSession } from '~/core/generic/actions-utils';
import getSupabaseServerActionClient from '~/core/supabase/action-client';
import { parseOrganizationIdCookie } from '~/lib/server/cookies/organization.cookie';
import requireSession from '~/lib/user/require-session';

type CreateTaskParams = {
  task: Omit<Task, 'id'>;
  csrfToken: string;
};

export const createTaskAction = withSession(
  async (params: CreateTaskParams) => {
    const client = getSupabaseServerActionClient();
    const session = await requireSession(client);
    const uid = await parseOrganizationIdCookie(session.user.id);
    const path = `/dashboard/${uid}/tasks`;

    await createTask(client, params.task);

    // revalidate the tasks page
    revalidatePath(path, 'page');

    // redirect to the tasks page
    redirect(path);
  },
);
```

The `withSession` function is a helper that ensures that the user is logged in. If not, it will redirect to the login page. Use it for all server actions that require a user to be logged in.

### Calling the mutation in a React component

Finally, it's a matter of calling the Next.js Server Action within the React component that handles the form submission.

Assuming you have a `form` element, you can do something like this:

```tsx
import { createTaskAction } from '~/lib/tasks/actions';
import useCsrfToken from '~/core/hooks/use-csrf-token';

function TaskForm() {
  const csrfToken = useCsrfToken();

  return (
    <form action={createTaskAction}>
      <input type="text" name="task.name" />
      <input type="text" name="task.description" />
      <input type="date" name="task.dueDate" />
      <input type="hidden" name="csrfToken" value={csrfToken} />
      <button type="submit">Create Task</button>
    </form>
  );
}
```

Adding the CSRF token is required in all POST requests. You can use the `useCsrfToken` hook to get the token and passing it as a hidden input.

You can also call the function imperatively if you don't use a traditional form component.

```tsx
import { useTransition } from "react";
import useCsrfToken from '~/core/hooks/use-csrf-token';

const [isPending, starTransition] = useTransition()

const onSubmit = (task: Task) => {
  startTransition(async () => {
    await createTaskAction({ task, csrfToken });
  })
};
```

In this tutorial we show how you can create a record in Postgres.

Creating a Record

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 Supabase 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-supabase/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 `~/core/ui/Trans`
2. Using the `useTranslation` hook from `react-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 Supabase 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 Supabase application.

Adding a new language


To add a new translation to your application next to the default ones (common, auth, profile, etc.) you need to:

1. create the new JSON file, for example `tasks.json` in the `public/locales/<lang>` folder
2. add the new bundle name to the translations list in the `src/i18n.settings.ts` file:

```typescript
export const defaultI18nNamespaces = [
  'common',
  'auth',
  'organization',
  'profile',
  'subscription',
];
```

We add the `tasks` bundle name to the `defaultI18nNamespaces`:

```typescript {7}
export const defaultI18nNamespaces = [
  'common',
  'auth',
  'organization',
  'profile',
  'subscription',
  'tasks'
];
```

Now, refresh the dev server and your new bundled will be picked up by the i18n module.

How to add a new translation file to your application.

Adding a new translation file


By default, the language switcher is not used within the Next.js Supabase 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 Supabase application.

Using the Language Switcher


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

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

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

  // use language here
}
```

### Detecting the locale from the server

When rendering on the server, you can use the `getLanguageCookie` object to detect the locale. This value represents the locale that was selected by the user.

NB: it can be null if the user has not selected a locale yet or if the user has never selected a locale. In this case, **you should use the default locale**.

```tsx
import getLanguageCookie from '~/i18n/get-language-cookie';
import configuration from '~/configuration';

function ServerComponent() {
  const locale = getCurrentLocale();

  // use locale here
}

function getCurrentLocale() {
  return getLanguageCookie() ?? configuration.site.locale;
}
```



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

Detecting the Currently selected locale

Translations


Sometimes, Supabase may not be able to start. This can happen for a number of reasons, but the most common is that the port you are trying to use is already in use by another application.

## Is Docker running?

To start Supabase in development mode, you need to have Docker running. If you don't have Docker running, Supabase will not be able to start.

Please download any Docker-compatible application (Docker Desktop, Colima, Orbstack) and make sure it is running before starting Supabase.

## Is Supabase already running?

If Supabase is already running, then it will not be able to start again. You can check if Supabase is already running by running the following command in your terminal:

```bash
docker ps
```

If yes, you can kill them all using the following command:

```bash
docker kill $(docker ps -q)
```

NB: this command will shut down **all running Docker containers**.

To shut down Supabase, you can run the following command from your application's root directory:

```bash
npm run supabase:stop
```

If you have 2 different Supabase projects running, you can stop them individually by running the following command:

```bash
npm run supabase:stop
```

If you run this command from a different project, it will not stop the Supabase instance running in your current project. So make sure you are in the right directory before running this command.

Learn why Supabase may not be able to start in certain cases and how to fix it.

How to fix: Supabase is not starting


Sometimes, Supabase may not be able to stop. In most cases, this happens because you have multiple projects running, and are trying to stop it from the wrong project.

Try to run the following command to discover the projects that are running in Docker:

```bash
docker ps
```

If you want to kill them all at once, also making Supabase stop, you can run the following command:

```bash
docker kill $(docker ps -q)
```

NB: this command will shut down **all running Docker containers**.

Learn why Supabase may not be able to stop in certain cases and how to fix it.

How to fix: Supabase is not stopping


When you try to start your Makerkit SaaS and try to navigate to your application, you may hit an error that says that the SQL tables or functions were not found.

This can happen for two reasons:

1. You're running Supabase locally and the migrations were not applied correctly.
2. You're running Supabase remotely and the migrations were not pushed to Supabase.
3. Something else is wrong with your Supabase instance. In case contact me or the Supabase team.

## This is happening when running Supabase locally

If this is happening when running Supabase locally, it means that the migrations weren't applied correctly. In this case, I recommend restarting Supabase and running the migrations again.

```
npm run supabase:stop
npm run supabase:start
```

### This is happening in the Supabase Cloud Instance

Instead - if this is happening in your remote instance, it means you did not push your migrations to the remote instance. In this case, I recommend pushing your migrations to the remote instance.

To push our database to Supabase, we need to link the Supabase CLI to our project.

You'll need to grab your project's reference ID from the URL: it's the part that comes after `app.supabase.io/` in the URL or the segment that comes before `supabase.co/` in the URL, such as `*******.supabase.co`.

We can do this by running the following command:

```bash
./node_modules/.bin/supabase link --project-ref **************
```

When prompted for the database password, enter the password you created when creating your project.

At this point, we can proceed to push our database to Supabase. Run the following command to push our database to Supabase:

```bash
./node_modules/.bin/supabase db push
```

The output should look like this:

```bash
Applying migration 20230705082911_schema.sql...
Finished supabase db push.
```

To verify that our database was pushed successfully, navigate to your project's dashboard and verify the tables were created.

How to fix the error: Tables/Functions not found when running Supabase locally or remotely.

How to fix: Supabase tables not found


A small percentage of customers have reported issues when starting the kit because [Contentlayer](https://contentlayer.dev) gets stuck.

The only known possible fix is to downgrade both the packages `contentlayer` and `next-contentlayer` to version `0.3.1`:

```bash
npm i contentlayer@0.3.1 next-contentlayer@0.3.1
```

If it keeps happening, please contact me and I'll help you out.

Contentlayer gets stuck when starting the Makerkit application


If you encounter the following error when starting the Makerkit application:

```
[ERROR] Dynamic server usage Page couldn't be rendered statically because it used `cookies`.
```

You can fix it by adding the following line to the nearest layout of the page that is causing the error:

```ts
export const dynamic = 'force-dynamic';
```

If it keeps happening, try to see if it is happening in yet another layout and add the line there as well. Do it until the error goes away.

The error Dynamic server usage Page couldn't be rendered statically because it used `cookies` is a common issue in Next.js. Here is the fix.

How to fix the Next.js error Dynamic Server Usage


If you're encountering a 403 error on Server Actions and API Routes, it is possible that your requests lack a CSRF Token.

By default, the Makerkit middleware at `src/middleware.ts` will automatically try to validate a CSRF token for HTTP methods such as `POST`, `PUT` and `DELETE`: failing to send a valid CSRF token will result in these requests being forbidden.

To fix this error, check out these pages:

1. **Server Actions**: [Add a CSRF token to your Server Actions](server-actions-csrf)
2. **API Routes**: [Add a CSRF token to your API Routes](api-routes)

### The CSRF Token is sent, but it's not defined

If the CSRF Token is being sent but it's null/undefined, it's likely a bug. In that case, please open a support ticket in our Discord channel.

One of the reasons why you're hitting a 403 error in your Server Actions is omitting a CSRF token. Let's see how to fix it

How to fix a 403 Error on Actions and API Routes

Troubleshooting

Tutorials


This tutorial is a comprehensive guide to getting started with the Next.js and
Supabase 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. Home Page and marketing pages (blog, pricing, FAQ)
2. Authentication (sign in, sign up, password reset)
3. Payments with Stripe
4. Profile Settings
5. Organization Settings
6. Tasks management with paginated Table and CRUD operations
7. Super Admin

## Prerequisites

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

1. Git
2. Node.js version (LTS or greater)
3. npm 7 or greater
4. Docker - up and running
5. Your favorite code editor (VSCode, WebStorm, Zed, etc.)
6. To deploy your application, we recommend Vercel (but you can use any other provider)
7. A Stripe Account

Experience with React, TypeScript/JavaScript, and Supabase 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, let's get started!

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

Building a SaaS tasks application with Makerkit


You have two ways to initialize the project:

1. Forking it from GitHub, or
2. Cloning it using Git, or
3. Using the Makerkit CLI (coming soon!)

### 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. Please be aware that by forking the repository, the Makerkit organization has read-only access to your forked repository.

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

### 3. Using the Makerkit CLI (coming soon!)

You can use the Makerkit CLI to create a new project based on this template. The CLI will ask you a few questions, and then it will create a new repository for you, and it will clone it locally.

Run the following command to run the CLI:

```
npx @makerkit/cli new
```

The CLI will ask you a few questions, and then it will create a new repository for you, and automatically install the Node modules.

### Reinitialize Git

As the Git repository's remote points to Makerkit's original repository, you can re-initialize (optionally!) the Git repository by running the following commands:

```
git remote rm origin
```

Now you have a clean Git repository.

### Setting the Upstream Repository

Then, we set the Makerkit repository as `upstream` - so we can pull updates when needed:

```
git remote add upstream git@github.com:makerkit/next-supabase-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
```

If you have any conflicts, you can resolve them manually and then commit the changes. If the merge conflicts are too complex, accept your changes and discard the Makerkit's changes - then, you can manually merge the changes by looking at the diff in GitHub.

#### Remember to keep your forked repository up-to-date!

NB: as updates are released almost daily, remember to pull updates often!

---

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 Supabase SaaS template, from forking the repository to installing the Node modules

Initial Setup


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. **Supabase**: We need to run the Supabase local environment using Docker
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.

**Cost Efficiency:** Supabase offers a generous free tier, including two free projects. However, if you need more than two, local development comes into play. You can create countless local projects and establish links with live projects at your convenience for launch.

**Code-Based Configuration:** Any modifications to your tables 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-supabase/going-to-production-overview).

Fore more information, check out the [Supabase documentation](https://supabase.com/docs/guides/cli/local-development).

## Install and Run Docker

Before we can run the Supabase local environment, we need to run Docker, as Supabase uses it for running its local environment.

You can use Docker Desktop, Colima, OrbStack, or any other Docker-compatible solution.

### 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 Supabase Local environment

To run the Supabase local environment, **we need to first run Docker**. If you don't have Docker installed, you can download and install Docker Desktop or alternatives such as Colima or Orbstack.

Then, open a new terminal (or, better, from your IDE) and run the following
commands:

```
npm run supabase:start
```

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

```
> supabase start

Applying migration 20221215192558_schema.sql...
Seeding data supabase/seed.sql...
Started supabase local development setup.

         API URL: http://localhost:54321
          DB URL: postgresql://postgres:postgres@localhost:54322/postgres
      Studio URL: http://localhost:54323
    Inbucket URL: http://localhost:54324
      JWT secret: super-secret-jwt-token-with-at-least-32-characters-long
        anon key: ****************************************************
service_role key: ****************************************************
```

Now, we need to copy the `anon key` and `service_role key` values and add
them to the `.env.local` file:

```
NEXT_PUBLIC_SUPABASE_ANON_KEY=****************************************************
SUPABASE_SERVICE_ROLE_KEY=****************************************************
```

When you need to stop the development environment, you can run the following command:

```
npm run supabase:stop
```

#### Supabase Studio UI

To access the Supabase Studio UI, open a new tab in your browser and navigate to [http://localhost:54323](http://localhost:54323).

<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 project.
</Alert>

### Running the Stripe CLI (optional)

Optionally, if you want to run Stripe locally (e.g., sending webhooks to your local server), we need two more steps.

1. Have a Stripe account
2. Run the Stripe CLI (or install Stripe on your OS)

To run the CLI, run the following command:

```
npm run stripe:listen
```

When running the command above for the first time, **Stripe will ask you to login**. You can do so by following the instructions in the terminal.

After signing in, run the command again.

```
npm run stripe:listen
```

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

#### Adding the Stripe Webhook Secret

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.

### Signing In for the first time

You should now be able to sign in. To quickly get started, use the following credentials:

```
email = test@makerkit.dev
password = testingpassword
```

### Email Confirmations for Testing with InBucket

When signing up, Supabase sends an email confirmation to a testing account.

You can access the InBucket testing emails [at http://localhost:54324/monitor](http://localhost:54324/monitor), and can follow the links to complete the sign up process.

InBucket is started automatically when you run `npm run supabase:start`.

## More about developing locally with Supabase

For more information about developing locally with Supabase, check out the [Supabase documentation](https://supabase.com/docs/guides/cli/local-development).

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.

Here is what the configuration file looks like:

```tsx title="src/configuration.ts"
import type { Provider } from '@supabase/gotrue-js/src/lib/types';

const production = process.env.NODE_ENV === 'production';

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,
    siteName: 'Awesomely',
    twitterHandle: '',
    githubHandle: '',
    language: 'en',
    convertKitFormId: '',
    locale: process.env.NEXT_PUBLIC_DEFAULT_LOCALE,
  },
  auth: {
    // ensure this is the same as your Supabase project. By default - it's true
    requireEmailConfirmation:
      process.env.NEXT_PUBLIC_REQUIRE_EMAIL_CONFIRMATION === 'true',
    // NB: Enable the providers below in the Supabase Console
    // in your production project
    providers: {
      emailPassword: true,
      phoneNumber: false,
      emailLink: false,
      oAuth: ['google'] as Provider[],
    },
  },
  production,
  environment: process.env.NEXT_PUBLIC_ENVIRONMENT,
  features: {
    enableThemeSwitcher: true,
  },
  theme: Themes.Dark,
  paths: {
    signIn: '/auth/sign-in',
    signUp: '/auth/sign-up',
    signInMfa: '/auth/verify',
    onboarding: `/onboarding`,
    appPrefix: '/dashboard',
    appHome: '/dashboard',
    authCallback: '/auth/callback',
    settings: {
      profile: 'settings/profile',
      authentication: 'settings/profile/authentication',
      email: 'settings/profile/email',
      password: 'settings/profile/password',
    },
  },
  email: {
    host: 'smtp.ethereal.email',
    port: 587,
    user: 'fabian96@ethereal.email',
    password: 'puBhygwkTP7DtTSCSz',
    senderAddress: 'MakerKit Team <info@makerkit.dev>',
  },
  sentry: {
    dsn: process.env.NEXT_PUBLIC_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;
```

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 two different environment variables files:
1. **.env**: the main environment file - use this for variables that are common to all environments - and that are not secrets.
2. **.env.development**: the development environment file (used when running the project locally in development mode) - when they're specific to the development environment.
3. **.env.production**: the production environment file (used when deploying or running the build command) - when they're specific to the production environment.
4. **.env.local**: this environment file is loaded when running the project locally. It won't be committed to Git. Useful for adding secrets that you don't want to commit to Git.
5. **.env.test**: this environment file is loaded when running the Cypress E2E tests. You would rarely need to use this.


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

Environment Variables


This SaaS template uses Tailwind CSS for styling the application.

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

```js title="tailwind.config.js"
extend: {
  colors: {
    primary: {
      ...colors.indigo,
      contrast: '#fff',
    },
    dark: colors.gray
  },
},
```

1. The `primary` color is the main color of your application. It is used for the background of the navigation bar, the background of the sidebar, the background of the buttons, etc.
2. The `dark` color is the background color of the dark theme. You can use other types of dark colors in the Tailwind CSS Color palette (such as `slate`, `zinc`), or define your own colors.

### Updating the Primary color of your app

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

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

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

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

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


### Dark Mode

Makerkit also ships with a dark theme.

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

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

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

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

## Installing Animations (optional)

If you want to use animations in your application, you can install the `tailwindcss-animate` library:

```bash
npm i tailwindcss-animate
```

Then, open the file `tailwind.config.js` and add the library as a plugin:

```js title="tailwind.config.js"
plugins: [
  require('tailwindcss-animate')
]
```

## Caveats

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

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

Tailwind CSS and Styling


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

The kit supports the following strategies:

1. Email/Password
2. All the oAuth Providers supported by Supabase Auth (Google, GitHub, etc.)
3. Phone Number
4. Magic Link

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

By default, the Makerkit SaaS Starter uses Email/Password and Google Auth. If you plan on using more than one together, it would be wise to adjust the UI so they play well together.

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

### Authentication Strategies

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

```tsx title="src/configuration.ts"
auth: {
  // NB: Enable the providers below in the Supabase Console
  // in your production project
  providers: {
    emailPassword: true,
    phoneNumber: false,
    emailLink: false,
    oAuth: ['google'] as Provider[],
  },
},
```

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"
auth: {
  // NB: Enable the providers below in the Supabase Console
  // in your production project
  providers: {
    emailPassword: false, // set this to false
    phoneNumber: false,
    emailLink: true, // set this to true
    oAuth: ['google', 'twitter'] as Provider[],
  },
},
```

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" />

### 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, Supabase requires users to verify their email address before being able to access the application.

To disable this behavior, besides **doing it in your Supabase console**, you also need to set the `requireEmailVerification` flag to `false` using the following environment variable:

```bash title=".env"
REQUIRE_EMAIL_VERIFICATION=false
```

This will let the application know that you don't want to require email verification.

NB: this may not work with the latest Supabase versions - so please double check with the Supabase support team if you are having issues.

## Emails sent by Supabase

Supabase spins up an [InBucket](http://localhost:54324/) instance where all the emails are sent: this is where you can find emails related to password reset, sign-in links, and email verifications.

To access the InBucket instance, you can go to the following URL: [http://localhost:54324/](http://localhost:54324/). Save this URL, you will use it very often.


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 receive the request and:

1. create the user Supabase record in the `users` table
2. create the organization Supabase record in the `organizations` table
3. create a membership between the user and the organization in the
`memberships` table and assign the user the role `owner`

I encourage you to visit the [Local Supabase Studio UI](http://localhost:54323) 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). It is for the Firebase version, but the same principles apply.

Alternatively - you can use the Lite Kit - which doesn't have an onboarding flow and organizations.

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

Onboarding Flow



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

This involves a couple of steps:

1. We need to define, on paper, what the data model of the Supabase tables
looks like
2. We need to update the SQL schema of the database to match the data model
and write the required RLS policies to secure the data
3. We need to write the hooks to fetch data from Supabase

### Learning about RLS

Learning RLS is fundamental to understanding how to secure data in Supabase. The best resource (other than checking Makerkit's code) is the [Supabase RLS docs](https://supabase.com/docs/guides/auth/row-level-security).

Please check it out - and if you have any questions, please ask in the Makerkit Discord.

##### How is the data structured?

We can place tasks as our own Postgres table `tasks`. Let's create an SQL
table that defines the following columns:

```sql
create table tasks (
  id bigint generated always as identity primary key,
  organization_id bigint not null references public.organizations,
  name text not null,
  description text,
  done bool not null,
  due_date timestamptz not null
);
```

Because tasks belong to an
organization, we need to ensure that only users of that organization can read
and write those tasks by adding a foreign key to each `task` named
`organization_id`.

##### Replicating the tasks table as a Type

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

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

NB: this may not be necessary if you generate the types from the SQL schema.
Up to you.

##### How do we protect the data with RLS?

We can add an RLS policy to the `tasks` table to ensure that only users of the same organization can read and write tasks.

We know that a user belongs to an organization using the `memberships` table.

The `memberships` table has two foreign keys: `user_id` and
`organization_id`: we can use these foreign keys to ensure that only users
of the same organization can read and write tasks.

First, we enable RLS on the `tasks` table:

```sql
alter table tasks enable row level security;
```

Then, we can add a policy to the `tasks` table:

```sql
create policy "Tasks can be read by users of the organizations to which it belongs" on tasks
  for all
    using (
      exists (
        select
          1
        from
          memberships
        where
          user_id = auth.uid () and
          tasks.organization_id = memberships.organization_id
      )
    );
```

#### Generating the types from the SQL schema

We can generate the types from the SQL schema using the Supabase CLI.

To run this command, you need to ensure Supabase is running locally using
`npm run supabase:start`.

You can generate the types by running the following command:

```bash
npm run typegen
```

The types will be generated at `src/database-types.ts`.

We will import the types whenever we use the Supabase client to ensure that it is typed correctly, which helps us write type-safe queries with the Supabase client.

For example:

```tsx
import type { SupabaseClient } from '@supabase/supabase-js';
import type { Database } from '../../database.types';

type Client = SupabaseClient<Database>;
```


Learn how to get started developing new features from the database schema in your Makerkit Next.js Supabase project.

Database Schema


With our tables and RLS in place, we can finally start writing our queries
using the Supabase Postgres client.

My convention (used throughout the boilerplate) is to **write
functions that inject the Supabase SDK Client as a parameter**: this allows us to
reuse these functions in both the browser and the server.

## Fetching a list of tasks

First, we want to write a function that is responsible for fetching the
paginated list of tasks using the Supabase Postgres client.

Below, we will write the query necessary to fetching the tasks for a given project:

- paginated using the `pageIndex` and `perPage` parameters
- filtered by the `query` parameter that is matched against the `name` column.

```tsx title="lib/tasks/queries.ts"
import type { SupabaseClient } from '@supabase/supabase-js';
import type { Database } from '~/database.types';
import { TASKS_TABLE } from '~/lib/db-tables';
import Task from '~/lib/tasks/types/task';

type Client = SupabaseClient<Database>;

const TASKS_PAGE_SIZE = 10;

export function getTasks(
  client: Client,
  params: {
    organizationUid: string;
    pageIndex: number;
    perPage?: number;
    query?: string;
  },
) {
  const { organizationUid, perPage, pageIndex } = params;
  const { startOffset, endOffset } = getPaginationOffsets(pageIndex, perPage);

  let query = client
    .from(TASKS_TABLE)
    .select<string, Task>(
      `
      id,
      name,
      organizationId: organization_id,
      dueDate: due_date,
      done,
      description,
      organization: organization_id !inner (
        id,
        uuid
      )
    `, { count: 'exact' }
    )
    .eq('organization.uuid', organizationUid)
    .range(startOffset, endOffset);

  if (params.query) {
    query = query.textSearch('name', params.query);
  }

  return query;
}

function getPaginationOffsets(pageIndex: number, perPage?: number) {
  const pageSize = perPage || TASKS_PAGE_SIZE;
  const startOffset = pageIndex * pageSize;
  const endOffset = startOffset + pageSize;

  return {
    startOffset,
    endOffset,
  };
}
```

## Fetching a single task

Next, we want to write a function that is responsible for fetching a single task when viewing the task details page. We can place this function in the same file as the `getTasks` function.

```tsx title="lib/tasks/queries.ts"
export function getTask(client: Client, id: number) {
  return client
    .from(TASKS_TABLE)
    .select(
      `
      id,
      name,
      organizationId: organization_id,
      dueDate: due_date,
      description,
      done
    `,
    )
    .eq('id', id)
    .single();
}
```

---

We now have all the queries we need to fetch tasks from Supabase, both as a paginated list and as a single task. In the next section, we will learn how to use these queries from the React Server Components.

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

Supabase: Data Fetching


In the section above, we saw how to fetch data from the Supabase Postgres.
Now, let's see how to write data to the Supabase database.

#### Creating a Task

First, we want to add a file named `mutations.ts` at `lib/tasks/`. Here, we
will add all the mutations that we will need to create, update, and delete
tasks.

In our mutations file, we will add all the mutations we want to perform on
the `tasks` table. In this case, we will add a `createTask` mutation.

```ts
import type { SupabaseClient } from '@supabase/supabase-js';
import type { Database } from '../../database.types';
import type Task from '~/lib/tasks/types/task';
import { TASKS_TABLE } from '~/lib/db-tables';

type Client = SupabaseClient<Database>;

export function createTask(
  client: Client,
  task: Omit<Task, 'id'>
) {
  return client.from(TASKS_TABLE).insert({
    name: task.name,
    organization_id: task.organizationId,
    due_date: task.dueDate,
    description: task.description,
    done: task.done,
  });
}
```

You now have 2 alternatives to call the `createTask` mutation:

1. Use a Server Action (recommended)
2. Use an SWR Mutation

Let's explain the differences between the two:

1. **Server Actions** are functions executed server side - and allow us to revalidate the page after a mutation, so we can see the changes immediately.
2. **SWR** is a client-side library that allows us to fetch data and mutate it. Since the Supabase Client allows us to perform queries/mutations client-side, we can use it in conjunction with SWR to use it within client-side React components. There are times where you may not need to revalidate the page after a mutation, and in those cases, SWR is also a good option.

Most of the time, you will want to use a Server Action, but we will show both alternatives.

### 1. Using a Server Action

Using server actions is the simplest and most straightforward way to perform mutations in Next.js, which is why I recommend it. With that said, it's worth keeping in mind they're marked as experimental and may change in the future.

#### Creating a Server Action

First, we create a file `actions.ts` from which we can export all our server actions. In this case, we will create a `createTask` server action.

The utility `withSession` is used to ensure the user is authenticated before performing the mutation.

```ts title="lib/tasks/actions.ts"
'use server';

import { revalidatePath } from 'next/cache';

import { createTask } from '~/lib/tasks/mutations';
import type Task from '~/lib/tasks/types/task';
import { withSession } from '~/core/generic/actions-utils';
import getSupabaseServerActionClient from '~/core/supabase/action-client';

type CreateTaskParams = {
  task: Omit<Task, 'id'>;
  csrfToken: string;
};

export const createTaskAction = withSession(
  async (params: CreateTaskParams) => {
    const client = getSupabaseServerActionClient();

    await createTask(client, params.task);

    revalidatePath('/dashboard/[organization]/tasks', 'page');
  });
```

#### Using the Server Action

We will show how to use the server action in the `forms` section.

### 2. Using SWR

If you want to use SWR, we can use the `createTask` mutation in our `useCreateTask` hook.

We will be using the `useMutation` hook from `react-query` to create our hook.

```tsx title="lib/tasks/hooks/use-create-task.ts"
import useSWRMutation from 'swr/mutation';
import { useRouter } from 'next/navigation';

import useSupabase from '~/core/hooks/use-supabase';
import { createTask } from '~/lib/tasks/mutations';
import type Task from '~/lib/tasks/types/task';

function useCreateTaskMutation() {
  const client = useSupabase();
  const router = useRouter();
  const key = 'tasks';

  return useSWRMutation(key, async (_, { arg: task }: { arg: Omit<Task, 'id'> }) => {
    return createTask(client, task);
  }, {
    onSuccess: () => router.refresh()
  });
}

export default useCreateTaskMutation;
```

And now, we could use this hook within a component. Below is a very simple example:

```tsx
function Component() {
  const createTaskMutation = useCreateTaskMutation();

  return <MyForm onSubmit={task => createTaskMutation.trigger(task)} />
}
```

#### Updating a Task

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

We will write another mutation function to update a task:

```ts title="lib/tasks/mutations.ts"
import type { SupabaseClient } from '@supabase/supabase-js';
import type { Database } from '../../database.types';
import type Task from '~/lib/tasks/types/task';
import { TASKS_TABLE } from '~/lib/db-tables';

type Client = SupabaseClient<Database>;

export function updateTask(
  client: Client,
  task: Partial<Task> & { id: number }
) {
  return client
    .from(TASKS_TABLE)
    .update({
      name: task.name,
      done: task.done,
      description: task.description,
    })
    .match({
      id: task.id,
    })
    .throwOnError();
}
```

### Updating a task using server actions

In addition to what we have written before, add the following code:

```ts title="lib/tasks/actions.ts"
import { revalidatePath } from 'next/cache';
import { createTask, updateTask } from '~/lib/tasks/mutations';

type UpdateTaskParams = {
  task: Partial<Task> & Pick<Task, 'id'>;
};

export const updateTaskAction = withSession(
  async (params: UpdateTaskParams) => {
    const client = getSupabaseServerActionClient();

    await updateTask(client, params.task);

    const path = `/dashboard/[organization]/tasks`;

    // revalidate the tasks page and the task page
    revalidatePath(path, 'page');
    revalidatePath(`${path}/[task]`, 'page');
  },
);
```

### Updating a task using SWR

And we can write a hook to use this mutation:

```tsx title="lib/tasks/hooks/use-update-task.ts"
import useSWRMutation from 'swr/mutation';
import useSupabase from '~/core/hooks/use-supabase';
import type Task from '~/lib/tasks/types/task';
import { updateTask } from '~/lib/tasks/mutations';

type TaskPayload = Partial<Task> & { id: number };

function useUpdateTaskMutation() {
  const client = useSupabase();
  const key = ['tasks'];

  return useSWRMutation(key, async (_, { arg: task }: { arg: TaskPayload }) => {
    return updateTask(client, task);
  });
}

export default useUpdateTaskMutation;
```

#### Deleting a Task

We will write another mutation function to delete a task:

```ts title="lib/tasks/mutations.ts"
import type { SupabaseClient } from '@supabase/supabase-js';
import type { Database } from '../../database.types';
import { TASKS_TABLE } from '~/lib/db-tables';

type Client = SupabaseClient<Database>;

export function deleteTask(
  client: Client,
  taskId: number
) {
  return client.from(TASKS_TABLE).delete().match({
    id: taskId
  }).throwOnError();
}
```

### Deleting a task using server actions

In addition to what we have written before, add the following code:

```ts title="lib/tasks/actions.ts"
import { createTask, deleteTask, updateTask } from '~/lib/tasks/mutations';
import revalidatePath from 'next/cache';

type DeleteTaskParams = {
  taskId: number;
};

export const deleteTaskAction = withSession(
  async (params: DeleteTaskParams) => {
    const client = getSupabaseServerActionClient();

    await deleteTask(client, params.taskId);

    revalidatePath('/dashboard/[organization]/tasks', 'page')
  });
```

Finally, we write a mutation to delete a task:

```tsx title="lib/entities/hooks/use-delete-task.ts"
import useSWRMutation from 'swr/mutation';

import useSupabase from '~/core/hooks/use-supabase';
import { deleteTask } from '~/lib/tasks/mutations';

function useDeleteTaskMutation() {
  const client = useSupabase();
  const taskId = ['tasks'];

  return useSWRMutation(
    taskId,
    async (_, { arg: taskId }: { arg: number }) => {
      return deleteTask(client, taskId);
  });
}

export default useDeleteTaskMutation;
```

---

We're done with the data writing section. In the next section, we will see how to use these functions in our pages and components.

Learn how to write data to the Supabase database in your React applications.

Supabase: Data Writing


Before getting started with building our Tasks Pages, let's take a look at the default page structure of the boilerplate:

```txt
├── app
  └── layout.tsx

  └── onboarding

  (site)
    └── faq
    └── pricing

  └── auth
    └── link
    └── password-reset
    └── sign-in
    └── sign-up

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

  └── dashboard
    └── [organization]
      └── page.tsx

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

        └── profile
          └── index
          └── email
          └── password
          └── authentication

        └── subscription

  └── page.tsx
```

The routes are split in the following way:

1. The website's pages are placed under `(site)`
2. The auth pages are placed under `auth`
3. The internal pages (behind auth) that are specific to organizations are placed under `dashboard/[organization]`
4. Some pages in the "middle" are placed outside `dashboard/[organization]`, such as the invites page and the onboarding flow.

### Setting the application's Home Page

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

The path `dashboard` is also defined as `appPrefix` in the configuration file `src/configuration.tsx`: you can update this and rename the folder if you want to change the path.

To update the application's home page, you can update the `configuration.paths.appHome` variable in `src/configuration.tsx`.

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

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

1. **Tasks List**: A page to list all our tasks
2. **Task Detail**: A page specific to the selected task

To create these two pages, we will create a folder named `tasks` at `src/app/dashboard/[organization]/tasks`.

In the folder `src/app/dashboard/[organization]/tasks` we will create three `Page Components`:

1. The tasks list page at `tasks/page.tsx`
2. The task's own detail page at `tasks/[task]/page.tsx`.

```
├── app
  └── dashboard/[organization]
    └── tasks
      └── page.tsx

      └── [task]
        └── page.tsx
```

### 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. **Data Model**: first, we want to define the data model of the feature you want to add
2. **Supabase Queries/Mutations**: once we're happy with the data model, we can create our Supabase DB queries/mutations
3. **Build Feature components**: then we can build the components of the feature (forms, lists, etc.)
4. **Add feature components into the pages**: finally, we add the components to the pages

### Adding page links to the Navigation Menu

#### Updating the Top header Navigation

To update the navigation menu, we need to update the `NAVIGATION_CONFIG` object in `src/navigation-config.tsx`. This object contains the links to the pages that are displayed in the top header menu.

1. The `label` is the text that will be displayed in the menu - it's a translation key that you can find in `locales/[lang]/common.json`
2. The `path` is the path to the page

```ts
const NAVIGATION_CONFIG = (organization: string) => ({
  items: [
    {
      label: 'common:dashboardTabLabel',
      path: getPath(organization, ''),
      Icon: ({ className }: { className: string }) => {
        return <Squares2X2Icon className={className} />;
      },
      end: true,
    },
    {
      label: 'common:tasksTabLabel',
      path: getPath(organization, 'tasks'),
      Icon: ({ className }: { className: string }) => {
        return <RectangleStackIcon className={className} />;
      },
    },
    {
      label: 'common:settingsTabLabel',
      path: getPath(organization, 'settings'),
      Icon: ({ className }: { className: string }) => {
        return <Cog8ToothIcon className={className} />;
      },
    },
  ],
});

function getPath(organizationId: string, path: string) {
  const appPrefix = configuration.paths.appPrefix;

  return [appPrefix, organizationId, path].filter(Boolean).join('/');
}
```

To add a new link to the header menu, follow the same convention:

1. Add a new item to the `items` array
2. Add the `label` and `path` properties
3. Make sure the `label` is a translation key that you can find in `locales/[lang]/common.json`
4. Add the `Icon` property if you want to display an icon next to the label
5. Make sure the `path` is correct

The result will be similar to the images below:

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

---

In the next sections we will go into more detail about how to use and configure Application Pages.

Learn the basics of routing in the Next.js Supabase SaaS Boilerplate

Routing

Let's build the page that lists all the tasks for a given organization.

Building the Tasks page


The Task Detail page is the page that shows the details of a specific task. It is a child page of the Tasks page.

As you may know, we can define a dynamic path in Next.js by using square brackets. For example, we can define a dynamic path for the Tasks page by creating a file called `app/dashboard/[organization]/tasks/[task]/page.tsx`. This will create a dynamic path for the Tasks page that will be available at `/dashboard/:organization/tasks/:task`.

## Building the Task Detail Container

Before we build the page, we define a client component named `TaskItemContainer` that will be used by the page. This component will be responsible for rendering the form that will be used to update the task.

```tsx title="app/dashboard/[organization]/tasks/components/TaskItemContainer.tsx"
'use client';

import { FormEventHandler, useCallback, useTransition } from 'react';
import { ChevronLeftIcon } from '@heroicons/react/24/outline';

import Textarea from '~/core/ui/Textarea';
import Label from '~/core/ui/Label';
import Button from '~/core/ui/Button';
import Heading from '~/core/ui/Heading';
import { TextFieldInput, TextFieldLabel } from '~/core/ui/TextField';

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

const TaskItemContainer: React.FC<{
  task: Task;
}> = ({ task }) => {
  const [isMutating, startTransition] = useTransition();

  const onUpdate: FormEventHandler<HTMLFormElement> = useCallback(
    (e) => {
      e.preventDefault();

      const data = new FormData(e.currentTarget);
      const name = data.get('name') as string;
      const description = data.get('description') as string;

      startTransition(async () => {
        await updateTaskAction({
          task: {
            name,
            description,
            id: task.id,
          },
          csrfToken,
        });
      });
    },
    [csrfToken, task.id],
  );

  return (
    <form onSubmit={onUpdate}>
      <div className={'flex flex-col space-y-4 max-w-xl'}>
        <Heading type={2}>{task.name}</Heading>

        <TextFieldLabel>
          Name
          <TextFieldInput required defaultValue={task.name} name={'name'} />
        </TextFieldLabel>

        <Label>
          Description
          <Textarea
            className={'h-32'}
            name={'description'}
            defaultValue={task.description || ''}
          />
        </Label>

        <div className={'flex space-x-2 justify-between'}>
          <Button href={'../tasks'} color={'transparent'}>
            <span className={'flex space-x-2 items-center'}>
              <ChevronLeftIcon className={'w-4'} />
              <span>Back to Tasks</span>
            </span>
          </Button>

          <Button loading={isMutating}>Update Task</Button>
        </div>
      </div>
    </form>
  );
};

export default TaskItemContainer;
```

## Building the Task Detail page

Now that we have the `TaskItemContainer` component, we can build the Task Detail page. The page will be responsible for fetching the task data and passing it to the `TaskItemContainer` component.

First, we define the function `loadTaskData` - responsible for fetching the task data - and then we use it in the `TaskPage` component.

If the task does not exist, we redirect the user back to the dashboard page. This is done by using the `redirect` function from the `next/navigation` module.

```tsx title="app/dashboard/[organization]/tasks/[task]/page.tsx"
async function loadTaskData(taskId: string) {
  const client = getSupabaseServerComponentClient();
  const { data: task } = await getTask(client, Number(taskId));

  if (!task) {
    redirect('/dashboard');
  }

  return {
    task,
  };
}
```

Below is the full code for the Task Detail page.

```tsx title="app/dashboard/[organization]/tasks/[task]/page.tsx"
import React, { use } from 'react';
import { redirect } from 'next/navigation';

import ArrowLeftIcon from '@heroicons/react/24/outline/ArrowLeftIcon';

import Button from '~/core/ui/Button';
import getSupabaseServerComponentClient from '~/core/supabase/server-component-client';
import { getTask } from '~/lib/tasks/queries';
import AppHeader from '~/app/dashboard/[organization]/components/AppHeader';
import AppContainer from '~/app/dashboard/[organization]/components/AppContainer';
import TaskItemContainer from '~/app/dashboard/[organization]/tasks/components/TaskItemContainer';
import { withI18n } from '~/i18n/with-i18n';

interface Context {
  params: {
    task: string;
  };
}

export const metadata = {
  title: `Task`,
};

const TaskPage = ({ params }: Context) => {
  const data = use(loadTaskData(params.task));
  const task = data.task;

  return (
    <>
      <AppHeader>
        <TaskPageHeading />
      </AppHeader>

      <AppContainer>
        <TaskItemContainer task={task} />
      </AppContainer>
    </>
  );
};

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

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

async function loadTaskData(taskId: string) {
  const client = getSupabaseServerComponentClient();
  const { data: task } = await getTask(client, Number(taskId));

  if (!task) {
    redirect('/dashboard');
  }

  return {
    task,
  };
}

export default withI18n(TaskPage);
```

---

Perfect, our Tasks App is now complete! 🎉

In the next steps, we take a look at some things you should now while keeping working on your app.

Building the Task Detail page


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.

### Calling API functions from the client

In Next.js App Router, the API functions are defined using the special file conventions named `route.ts`. You can add these anywhere in your app directory.

When the API functions are "standalone" and not tied to a specific page, it makes sense to add them to `app/api`.

First, we define a function using the utility `useApiRequest` and SWR's `useSWRMutation` hook.

```tsx
import useSWRMutation from 'swr/mutation';

import configuration from '~/configuration';
import useApiRequest from '~/core/hooks/use-api';
import useRefresh from '~/core/hooks/use-refresh';

interface Params {
  membershipId: number;
}

const path = configuration.paths.api.organizations.transferOwnership;

function useTransferOrganizationOwnership() {
  const fetcher = useApiRequest<void, Params>();
  const refresh = useRefresh();
  const key = ['organizations', 'transfer-ownership'];

  return useSWRMutation(
    key,
    (_, { arg }: { arg: Params }) => {
      return fetcher({
        path,
        method: `PUT`,
        body: {
          membershipId: arg.membershipId,
        },
      });
    },
    {
      onSuccess: refresh,
    }
  );
}

export default useTransferOrganizationOwnership;
```

Then, we can define a route function in the file `app/api/organizations/owner/route.ts`.

```tsx
export async function PUT(req: Request) {
  // logic to transfer ownership
}
```

#### Sending the CSRF Token

When you use the hook `useApiRequest`, you don't need to worry about sending the CSRF token. The hook will automatically send the token.

Instead, if you use `fetch` directly, you need to send the CSRF token.
To retrieve the page's CSRF token, you can use the `useCsrfToken` hook:

```tsx
const csrfToken = useCsrfToken();

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

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

### CSRF Token check

The middleware will automatically check that the CSRF Token is present and is valid in the request header for requests that require it.

### 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
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`
  );
}
```

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.


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 components AppHeader and AppContainer

These components are used to wrap the content of the pages.

They are responsible for displaying the header and the container of the page.

```tsx
import { Squares2X2Icon } from '@heroicons/react/24/outline';

import Trans from '~/core/ui/Trans';
import AppHeader from '~/app/dashboard/[organization]/components/AppHeader';
import AppContainer from '~/app/dashboard/[organization]/components/AppContainer';

function DashboardPage() {
  return (
    <>
      <AppHeader>
        <span className={'flex space-x-2'}>
          <Squares2X2Icon className="w-6" />

          <span>
            <Trans i18nKey={'common:dashboardTabLabel'} />
          </span>
        </span>
      </AppHeader>

      <AppContainer>
        Your content goes here
      </AppContainer>
    </>
  );
}
```

## Guarding Application Pages for Authenticated Users

One of the ways we can use to protect application pages, we can use the `requireSession` function. This function also verifies that the user is authenticated using MFA.

```tsx
import { redirect } from "next/navigation";

async function MyPage() {
  const session = await requireSession();

  if (!session) {
    redirect('/');
  }
}
```

If you don't want to redirect users away, you can simply display an error message instead.

```tsx
import { redirect } from "next/navigation";

async function MyPage() {
  const session = await requireSession();

  if (!session) {
    return <div>You are not authenticated</div>;
  }

  return <div>Your content goes here</div>;
}
```

## Using Dynamic Parameters

Every page and layout can access dynamic parameters from the URL.

For example, if you have a page with the following URL:

```
https://myapp.com/dashboard/[organization]/[project]
```

You can access the `organization` and `project` parameters from the page.

```tsx
interface PageData {
  params: {
    organization: string;
    project: string;
  }
}

function Page(data: PageData) {
  // data.params.organization
}
```

## Using Search Parameters

Similarly to dynamic parameters, you can also access search parameters from the URL.

For example, if you have a page with the following URL:

```
https://myapp.com/dashboard/[organization]/[project]?page=1&limit=10
```

You can access the `page` and `limit` parameters from the page.

```tsx
interface PageData {
  params: {
    organization: string;
    project: string;
  }

  searchParams: {
    page: string;
    limit: string;
  }
}

function Page(data: PageData) {
  // data.searchParams.page
}
```

## Internationalization

To enable i18n for a layout or a route, simply wrap them using the `withI18n` HOC.

This component makes sure that the i18n is initialized before the page is rendered.

```tsx
import { withI18n } from '~/i18n/with-i18n';


function TaskPage() {
  // ...
}

export default withI18n(TaskPage);
```

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


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

export async function PUT(req: Request) {
  const result = await getBodySchema().safeParseAsync(await req.json());

  // validate the form data
  if (!result.success) {
    throw throwBadRequestException();
  }
}

function getBodySchema() {
  return z.object({
    membershipId: z.coerce.number(),
  });
}
```

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 Supabase application.

API Routes Validation


Most strings in the Makerkit template's application use `i18next`, 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 i18n
configuration at `src/i18n/i18next.settings.ts`.

Simply add your new language's code to the `locales` array.

The configuration will look like the below:

```js title="app/i18n/i18next.settings.ts"
const fallbackLng = process.env.DEFAULT_LOCALE ?? 'en';
const languages: string[] = [fallbackLng, 'es', 'fr', 'it'];
```

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

### Translating Server Components strings

To translate the server components strings, you need to initialize i18n in your Server Component using the following function:


```tsx
const i18n = await initializeServerI18n(getLanguageCookie());
```

You can find examples of how we do it in every `layout` file.

### Translating Client Components strings

When translating client components, you need to ensure you:

1) Import the `i18nProvider` component and set the language provided from the server component
2) Use the `Trans` component from `~/core/ui/Trans`. An eslint rule will ensure you do not import it from `react-i18next`

For example, here is the `SiteLayout` layout:

```tsx
function SiteLayout(props: React.PropsWithChildren) {
  const data = use(loadUserData());

  return (
    <I18nProvider lang={data.language}>
      <AuthChangeListener accessToken={data.accessToken}>
        <SiteHeaderSessionProvider data={data} />

        {props.children}

        <Footer />
      </AuthChangeListener>
    </I18nProvider>
  );
}
```


Learn how to easily translate your Next.js Supabase 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 Supabase kit effectively.

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

## Client-Side Functions

### Supabase Hooks

The Next.js Supabase kit uses the client Supabase SDK extensively throughout the kit. You can find the full documentation of the Supabase SDK [here](https://supabase.io/docs/reference/javascript/supabase-client).

To interact with the client-side Supabase SDK, you can use the hook `useSupabase`.

```tsx
import useSupabase from '~/core/hooks/use-supabase';

function Component() {
  // This is the Supabase client
  const supabase = useSupabase();
}
```

Using the `useSupabase` hook, you can access the Supabase client anywhere in your application, and it will be initialized with the correct Supabase URL and Supabase key that you have set in your environment variables.

#### Server Side Supabase Clients
There are other variations for use on the server-side, but of course these are not hooks since you will be using them outside of React components.

We will take a look at server-side Supabase functions in the next sections.

### 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 `dashboard/[organization]` layout, 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 Supabase Auth
- `data`: the data that comes from the user's Supabase 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

### 1. Supabase Server clients

Supabase provides different server clients depending on where they are used. This is because the cookie handling is usually different.

1. `getSupabaseServerComponentClient`: getting the server-side Supabase client for use in Server Components
2. `getSupabaseRouteHandlerClient`: getting the server-side Supabase client for use in API Route Handlers
3. `getSupabaseServerActionClient`: getting the server-side Supabase client for use in Server Actions

This function will return a server-side Supabase client, which you can use to interact with Supabase server-side.

```ts
import getSupabaseRouteHandlerClient from '~/core/supabase/route-handler-client';

export function  GET() {
  const supabase = getSupabaseRouteHandlerClient();

  // Do something with the supabase client
}
```

if you want to use a Service Role key and use admin permissions, you can pass the `admin` option to the `getSupabaseRouteHandlerClient` function:

```ts
import getSupabaseRouteHandlerClient from '~/core/supabase/route-handler-client';

export function  GET() {
  const supabase = getSupabaseRouteHandlerClient({
    admin: true
  });

  // Do something with the supabase client
}
```

If you want to use the client in a Server Component:

```tsx
import getSupabaseServerComponentClient from '~/core/supabase/server-component-client';

function PageComponent() {
  const client = getSupabaseServerComponentClient();
}
```

If you want to use the Supabase client in a Server Action:

```tsx
'use server';

import getSupabaseServerActionClient from '~/core/supabase/server-action-client';

export async function serverAction() {
  const client = getSupabaseServerActionClient();
}
```

### 2. "requireSession": Getting (and requiring) the current user session

This function will return the current user session data, and will also require the user to be logged in.

- If the user is not logged in: they will be redirected to the sign-in page.
- If the user is signed in, but requires MFA: they will be redirected to the MFA verification page.

It returns a Supabase Auth `Session` instance:

```ts
import getSupabaseRouteHandlerClient from '~/core/supabase/route-handler-client';

export async function GET() {
  const supabase = getSupabaseRouteHandlerClient();
  const session = await requireSession(supabase);

  //
}
```

Use it across layouts, route handlers, etc. every time you want to validate the user is signed in.

### 3. "getCurrentOrganization": getting the current user organization

This function returns the current user organization. It accepts two optional fields:
- `userId`: the user ID to get the organization for. If not provided, it will use the current user ID.
- `organizationId`: the organization ID to get. If not provided, it will use the current organization ID. If neither is found, it will fetch the first organization for the user.

And returns the organization data:

```tsx title="src/lib/organizations/database/queries.ts"
export type UserOrganizationData = {
  role: MembershipRole;
  organization: Organization & {
    subscription?: {
      customerId: Maybe<string>;
      data: OrganizationSubscription;
    };
  };
};
```

Usage:

```ts
import getCurrentOrganization from '~/lib/server/organizations/get-current-organization';

export async function GET() {
  const response = await getCurrentOrganization();

  //
}
```

Using a user ID:

```ts
import getCurrentOrganization from '~/lib/server/organizations/get-current-organization';

export async function GET() {
  const response = await getCurrentOrganization({
    userId: '123'
  });
}
```

Using an organization ID:

```ts
import getCurrentOrganization from '~/lib/server/organizations/get-current-organization';

export async function GET() {
  const response = await getCurrentOrganization({
    userId: '123',
    organizationId: '456'
  });
}
```

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

Functions you need to know

Adding pages to the Marketing Site is easy.

The marketing/site pages are placed under the `app/(site)` directory, and are part of the `site` layout.

```tsx title="app/(site)/about/page.tsx"
import Hero from '~/core/ui/Hero';
import Container from '~/core/ui/Container';
import SubHeading from '~/core/ui/SubHeading';

export const metadata = {
  title: 'About',
};

const AboutPage = () => {
  return (
    <div>
      <Container>
        <div className={'flex flex-col space-y-14'}>
          <div className={'flex flex-col items-center'}>
            <Hero>About us</Hero>

            <SubHeading>
              We are a team of passionate developers and designers who love to
              build great products.
            </SubHeading>
          </div>
        </div>

        <div>
          
        </div>
      </Container>
    </div>
  );
};

export default AboutPage;
```

### Adding the page to the site's 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 Supabase application, and how to add them to the navigation menu.

Tutorials

Onboarding Flow

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

What happens when the user submits the form?

What is an "Organization"?

Can I remove this step?

Subscribe to our Newsletter