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

How to


The "How to" documentation of Makerkit Next.js Supabase Lite 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 Lite 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 Remix Firebase 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](https://inbucket.org) - a platform to testing emails.

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

InBucket will run automatically when starting the local Supabase environment.

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

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

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: true,
  },
  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.

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

Adding API Routes


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

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 path = `/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/(app)` 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/(app)` directory.
This directory contains the pages that are **only accessible to authenticated users**.

### Layout and Sidebar

Pages created within the directory `src/app/(app)` 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/(app)/tasks`. We will then create a new page at `src/app/(app)/tasks/page.tsx`.

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

import AppHeader from '~/app/(app)/components/AppHeader';
import AppContainer from '~/app/(app)/components/AppContainer';

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

async function TasksPage() {
  const client = getSupabasServerComponentClient();
  const session = await requireSession();

  const { tasks } = await loadTasksData({
    userId: session.user.id,
  });

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

          <span>
            Tasks
          </span>
        </span>
      </AppHeader>

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

export default TasksPage;
```

Let's break down what we did here:

1. We created a new page at `src/app/(tasks)/page.tsx`. This page will be accessible at `/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.

### Layout

Layout-wise, we added the following components:

1. An `AppHeader` component that will be used to render the header of the page.
2. An `AppContainer` component that will be used to render the content of the page.

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

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

export default NAVIGATION_CONFIG;
```

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

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

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

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

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

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

Updating the sidebar menu of your Makerkit SaaS application


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

We can use the function `loadAppData` to get data required to load the main layout of the app located at `app/(app)`.

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

## Guarding Application Pages with User Subscriptions

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

To do so, we check the `subscription` property 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.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 getSupabaseServerActionClient from '~/core/supabase/server-action-client';
import requireSession from '~/lib/user/require-session';

export async function yourServerAction() {
  const client = getSupabaseServerActionClient();
  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/(app)` 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.


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

Fetching the signed in User

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,
  user_id uuid references public.users 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,
      userId: user_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;
  userId: 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,
    user_id: task.userId,
    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';

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

export const createTaskAction = withSession(
  async (params: CreateTaskParams) => {
    const client = getSupabaseServerActionClient();
    const path = `/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.

How to run the Stripe CLI to test the Stripe Webhooks locally in localhost


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


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

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

Getting Started


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

The MakerKit kit is a fully-featured Next.js application that uses Supabase for
authentication, database (with Postgres), and storage.

This version of the kit uses the new App Router introduced with Next.js 13, which is built on top of the new React Server Components.

## What does the boilerplate provide?

### Tech Stack

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

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

### Template Features

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

- **User Authentication** with Supabase Auth
- **Payments** with Stripe, and support for **subscriptions**
- **MDX-powered Blog and Documentation** generators - already **SEO-optimized** for you [Coming Soon]

### Marketing

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

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

### Debugging and Testing

Never waste time chasing bugs again.

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

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

### After you buy

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

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

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

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


Introduction to MakerKit: a SaaS starter built with Next.js and Supabase (Lite)

Introduction to MakerKit: a SaaS boilerplate for Next.js and Supabase (Lite)


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

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

### 1) A Scalable Next.js Application
The codebase is entirely built with [Next.js](https://nextjs.org) using the experimental app directory and React Server Components.

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

### 2) Built on top of Supabase

[Supabase](https://supabase.com) is an open source Firebase alternative,
 a great choice for a backend for a SaaS application.

MakerKit uses Supabase for Authentication, Database (Postgres) for storing data and Storage for storing files.

This kit **does not use Prisma**. We use Supabase's own client library.

### 3) Theme built with Tailwind CSS 3

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

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

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

### 4) Radix UI Components

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

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

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

### 5) Fully and Strictly Typed with Typescript

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

### 6) Payload validation with Zod

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

### 7) E2E testing with Cypress

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

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

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

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

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

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

### 9) Logging with Pino

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

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

### 10) SWR for data fetching and mutations

MakerKit uses Vercel's SWR for data fetching and mutations when used from the client-side, which is in very few places, as we mostly use Server Actions.

MakerKit uses Next.js, Supabase, Tailwind CSS, Zod, React Query, Pino, Radix UI, Typescript and Cypress to build wonderful SaaS applications

The technologies that make up a MakerKit application


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

### Requirements

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

- Node.js
- Git
- Docker

### Getting Started with MakerKit

#### Clone the repository

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

```
git clone git@github.com:makerkit/next-supabase-saas-kit-lite.git my-saas
```

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

#### Initializing Git

Now, run the following commands for:

1. Moving into the folder
2. Add the remote repository

```
cd my-saas
git remote rm origin
git remote add origin <your-git-repository>
```

If you haven't created a Git repository yet, you can do it later on.

### Setting the Upstream repository, and fetching updates

Now, we can add the original Makerkit repository as "upstream" so we can fetch updates from the main repository:

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

To fetch updates, you can run the following command:

```
git pull upstream main
```

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

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

```
git checkout main-ls
```

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

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

### Installing the Node dependencies

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

```
npm i
```

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

So let's jump on to the next step!


Learn how to clone the MakerKit repository

Clone the MakerKit SaaS boilerplate repository


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

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

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

## About this Documentation

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

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

First, let's run the Supabase environment, which will spin up a local
instance using Docker. We can do this by running the following command:

```bash
npm run supabase:start
```

Additionally, it imports the default seed data. We use it this data to
populate the database with some initial data and execute the E2E tests.

After running the command above, you will be able to access the Supabase
Studio UI at [http://localhost:54323/](http://localhost:54323/).

### Adding the Supabase Keys to the Environment Variables

If this is the first time you run this command, we will need to get the
Supabase keys and add them to our local environment variables configuration
file `.env`.

When running the command, we will see a message like this:

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

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

### Running the Next.js Server

And now, the Next.js server:

```bash
npm run dev
```

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

### Running the Stripe CLI

Run the Stripe CLI with the following command:

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

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

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

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

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

When signing up, Supabase sends an email confirmation to a testing account. You can access the InBucket testing emails [using the following link](http://localhost:54324/monitor), and can follow the links to complete the sign up process.




Learn how to run a Next.js and Supabase MakerKit application

How to run a Next.js and Supabase MakerKit application

Configuration


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

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

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

The configuration has the following structure:

```typescript title="app/configuration.ts"
export default {
  site: {
    name: '',
    description: '',
    themeColor: '#ffffff',
    themeColorDark: '#0a0a0a',
    siteUrl: process.env.NEXT_PUBLIC_SITE_URL,
    siteName: '',
    twitterHandle: '',
    githubHandle: '',
    language: 'en',
    convertKitFormId: '',
    locale: process.env.NEXT_PUBLIC_DEFAULT_LOCALE,
  },
  paths: {
    signIn: '/auth/sign-in',
    signUp: '/auth/sign-up',
    emailLinkSignIn: '/auth/link',
    appHome: '/tasks',
    settings: {
      profile: '/settings/profile',
      authentication: '/settings/profile/authentication',
      email: '/settings/profile/email',
      password: '/settings/profile/password',
    },
  },
  auth: {
    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'],
    },
  },
  email: {
    host: '',
    port: 0,
    user: '',
    password: '',
  },
  environment: process.env.NEXT_PUBLIC_ENVIRONMENT,
  production: process.env.NODE_ENV === 'production',
  features: {
    enableThemeSwitcher: true,
  },
  theme: Themes.Light,
  stripe: {
    products: [
      {
        name: 'Basic',
        description: 'Describe your basic plan',
        plans: [
          {
            price: '$249/year',
            stripePriceId: '<STRIPE_PRICE_ID>',
          }
        ],
      },
      {
        name: 'Pro',
        description: 'Describe your pro plan',
        plans: [
          {
            price: '$249/year',
            stripePriceId: '<STRIPE_PRICE_ID>',
          }
        ],
      },
    ],
  },
};
```

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

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


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

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


The starter project comes with three different environment variables files:

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

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

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

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


## Environment Variables

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

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

The production environment variables set your application up for the Supabase environment:

```
DEFAULT_LOCALE=en
SITE_URL=http://localhost:3000

# SUPABASE
NEXT_PUBLIC_SUPABASE_URL=http://localhost:54321
NEXT_PUBLIC_SUPABASE_ANON_KEY=
SUPABASE_SERVICE_ROLE_KEY=

# STRIPE
STRIPE_WEBHOOK_SECRET=
STRIPE_SECRET_KEY=
NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY=

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

<Alert type="warn">
  <Alert.Heading>
    You must add these variables to your production environment.
  </Alert.Heading>

  <span>
    You can safely add public or non-secret variables to your <code>.env.production</code> file for your production environment. Instead, add your secrets using your Vercel Console, or use the <code>.env.local</code> file during development.
  </span>
</Alert>

#### Use your CI/CD to set environment variables for your production environment

Some of the variables above are secret. You must add these from your CI/CD environment:

```
# SUPABASE
SUPABASE_SERVICE_ROLE_KEY=

# STRIPE
STRIPE_WEBHOOK_SECRET=
STRIPE_SECRET_KEY=

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

You can safely add public or non-secret variables to your `.env.production` file for your production environment.


## Website Configuration

The following variables are used to configure your website:

### DEFAULT_LOCALE

The default locale for your application. This is used by the `i18next` library to set the default locale for your application.

### SITE_URL

The URL of your application. This is used across the application to generate links to your application.

## Supabase Configuration

The following variables are used to configure your Supabase project:

### NEXT_PUBLIC_SUPABASE_URL

The URL of your Supabase project. This is used by the Supabase client to connect to your Supabase project. It is a public variable.

### NEXT_PUBLIC_SUPABASE_ANON_KEY

The anonymous key of your Supabase project. This is used by the Supabase client to connect to your Supabase project. It is a public variable.

### SUPABASE_SERVICE_ROLE_KEY

The service role key of your Supabase project. This is used by the Supabase client to connect to your Supabase project. It is a secret variable - so please add it to your CI/CD environment and never add it to Git.

## Stripe Configuration

The following variables are used to configure your Stripe project:

### STRIPE_WEBHOOK_SECRET

The webhook secret of your Stripe project (also referred to as Signing Secret within the Stripe dashboard). This is used by the Stripe client to connect to your Stripe project. It is a secret variable - so please add it to your CI/CD environment and never add it to Git.

### STRIPE_SECRET_KEY

The secret key of your Stripe project. This is used by the Stripe client to connect to your Stripe project. It is a secret variable - so please add it to your CI/CD environment and never add it to Git.

### NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY

The publishable key of your Stripe project. This is used by the Stripe client to connect to your Stripe project. It is a public variable and it's used to create the embedded checkout with the Stripe SDK.

## Email Configuration

The following variables are used to configure your email provider:

### EMAIL_HOST

The SMTP host of your email provider. This is used by the email client to connect to your email provider. It is a secret variable - so please add it to your CI/CD environment and never add it to Git.

### EMAIL_PORT

The SMTP port of your email provider. This is used by the email client to connect to your email provider. It is a secret variable - so please add it to your CI/CD environment and never add it to Git.

### EMAIL_USER

The SMTP user of your email provider. This is used by the email client to connect to your email provider. It is a secret variable - so please add it to your CI/CD environment and never add it to Git.

### EMAIL_PASSWORD

The SMTP password of your email provider. This is used by the email client to connect to your email provider. It is a secret variable - so please add it to your CI/CD environment and never add it to Git.

### EMAIL_SENDER

The sender of your emails. This is used by the email client to send emails to your users. It is a public variable. Use the format `Sender Name <email@app.com>`.

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

Environment Variables

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

Architecture


MakerKit's primary goals are:

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

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

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

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

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

### Framework Architecture

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

```
- app
  - (site)
  - (app)
    - dashboard
  - auth
  - invite
- lib
- components
```

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

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

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

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

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

### Lib and Shared Components

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

- `lib`: here is where we write most domain-related business logic (hooks, contexts, queries, mutations, etc.)
- `components`: here is where we write components shared across the application

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

### Routes

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

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

The kit splits the routes into three separate layouts:
- `(site)`: the routes that are accessible to everyone, even if they are not logged in
- `(app)`: internal routes that are only accessible to authenticated users
- `auth`: they auth routes, only accessible to unauthenticated users

#### Websites routes - (site)

If you are building a SaaS, you will probably have a marketing website. This is the place where you can put your landing page, pricing, and other marketing-related pages.

#### Auth routes - auth

The auth routes are the routes that are accessible to unauthenticated users. This is where your users can sign up, log in, and reset their password.

If a user is already logged in, they will be redirected to the dashboard.

#### App routes - (app)

The `(app)` routes are the routes that are only accessible to authenticated users. This is where you can put your dashboard, settings, and other internal pages.

#### Domain Components

Domain components are co-located together with their routes. This means that you can easily find the components that are used in a particular route.

For example, you find the authentication components at `/app/auth/components`.

## Import Flow

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

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



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

Architecture and Folder Structure for your Next.js SaaS application


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

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

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

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

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

```txt title="Structure"
- app
  - lib
    - events
      - types
        - event-model.ts
        - ...
      - hooks
        - use-fetch-events.ts
        - use-create-event.ts
        - ...
      - utils
        - create-event-model.ts

  - app
    - dashboard
    - events
      components
        - events
          - EventsContainerComponent.tsx
          - ...
      - page.tsx
      - [event].tsx
```

NB: In the Next.js App Directory, you can also add the `lib` folders within the `app` folder. For example, you can add `app/dashboard/[organization]/events/lib` instead of `lib/events`.

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

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

#### Types

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

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

#### Custom Hooks

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

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

```tsx title="src/lib/events/hooks/use-fetch-events.ts"

export function useFetchEvents(
  organizationId: number
) {
  const client = useSupabase();
  const key = [`events`, organizationId];

  return useQuery(key, async () => {
    const { data, error } client
      .from('events')
      .select('*')
      .eq('organization_id', organizationId);

    if (error) {
      throw error;
    }

    return data;
  })
}
```

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

<Alert type='warn'>
  NB: remember to update add the required Row Level Security policies to protect your tables.
</Alert>

### 2) Components

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

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

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

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

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

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

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

export default EventsListContainer;
```

### 3) Routes

Finally, we can add the events component `EventsListContainer` to a page. To
do so, let's create a page component at `app/dashboard/[organization]/events/page.tsx`:

```tsx title="app/dashboard/[organization]/events/page.tsx"
import EventsListContainer from '~/app/dashboard/[organization]/events/components/EventsListContainer';

const EventsPage: React.FC = () => {
  return (
     <EventsListContainer />
  );
};

export default EventsPage;
```

🎉 That's it! We have now built a nicely structured "events" domain.

Learn how to structure your application with additional entities and business logic

Structure your Makerkit Application


MakerKit's data model is voluntarily as simple as possible, with a limited set of assumptions.

MakerKit is not supposed to be a finite product but a solid foundation on which it is quick to get started and build your SaaS product.

To summarize, the Postgres Database model contains the following tables: `users`, `subscriptions` and `users_subscriptions`.

## Users

Users are, of course, foundational to any application.

If a user signed in using Supabase Authentication, it merely means we have
verified their credentials, not that they have an account.

We have to create an additional collection to store a user's data, such as:
- names (first name, last name)
- profile photo
- settings
- any other information which is not possible to update using their Authentication record (email, and sign-in providers)

Below is the `users` table:

```sql
create table users (
  id uuid references auth.users not null primary key,
  photo_url text,
  display_name text
);
```

## Subscriptions

When users complete the Stripe checkout, the application will store some information from the subscription object sent by Stripe. 

Below is the schema of the information stored in the Database:

```sql
create table subscriptions (
  id text not null primary key,
  price_id text not null,
  status subscription_status not null,
  currency text,
  interval text,
  interval_count int,
  created_at timestamptz,
  period_starts_at timestamptz,
  period_ends_at timestamptz,
  trial_starts_at timestamptz,
  trial_ends_at timestamptz
);
```

To link a `customer_id` from Stripe with an organization, we use a join table `organizations_subscriptions`:

```sql
create table users_subscriptions (
  user_id uuid not null references public.users (id) on delete cascade,
  subscription_id text unique references public.subscriptions (id) on delete set null,
  customer_id text not null unique,
  primary key (user_id)
);
```

We store the `customer_id` property so that, when a user is first linked to a Stripe customer, can access their Stripe data using the Billing Portal.

When a subscription is active, the `subscription_id` field will be populated with the subscription ID. Otherwise, the field will be `null`.

## Storage

By default, the kit also creates one Storage bucket: the user's `avatars`:

```sql
insert into storage.buckets (id, name, PUBLIC)
  values ('avatars', 'avatars', true);
```

Learn how MakerKit defines the model of your SaaS application with Next.js and Supabase

The MakerKit Data Model for your SaaS project built with Next.js and Supabase

Learn how MakerKit authenticates your users, and how to set-up Supabase Auth


MakerKit uses Supabase to manage authentication within your application.

By default, every kit comes with the following built-in authentication methods:
- **Email/Password** - we added, by default, the traditional way of signing in
- **Third Party Providers** - we also added by default Google Auth sign-in
- **Email Links**
- **Phone Number**

You're free to add (or remove) any of the methods supported by Supabase's
Authentication: we will see how.

This documentation will help you with the following:
 - **Setup** - setting up your Supabase project
 - **SSR** - use SSR to persist your users' authentication, adding new
providers
 - **Customization** - an overview of how MakerKit works so that you can adapt
it to your own application's needs

## Configuration

The way you want your users to authenticate can be driven via configuration.

If you open the global configuration at `src/configuration.ts`, you'll find
the `auth` object:

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

auth: {
  requireEmailConfirmation: false,
  providers: {
    emailPassword: true,
    phoneNumber: false,
    emailLink: false,
    oAuth: ['google'] as Provider[],
  },
}
```

As you can see, the `providers` object can be configured to only display the
auth methods we want to use.

1. For example, by setting both `phoneNumber` and `emailLink` to `true`, the
authentication pages will display the `Email Link` authentication
 and the `Phone Number` authentication forms.
2. Instead, by setting `emailPassword` to `false`, we will remove the
`email/password` form from the authentication and user profile pages.

<Alert type={'warn'}>
  Remember that you will always need to enable and configure the authentication
  methods you want to use in your Supabase project.
</Alert>

## Requiring Email Verification

This setting needs to match what you have set up in Supabase. If you require email confirmation before your users can sign in, you will have to flip the following flag in your configuration:

```ts
auth: {
  requireEmailConfirmation: false,
}
```

When the flag is set to `true`, the user will not be redirected to the onboarding flow, but will instead see a successful alert asking them to confirm their email. After confirmation, they will be able to sign in.

When the flag is set to `false`, the application will redirect them directly to the onboarding flow.

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

MakerKit uses Supabase Authentication to allow access to your Next.js application using oAuth providers and email/password.

Setting up Supabase and Next.js authentication with MakerKit


Supabase needs a few settings to be configured in their Dashboard to work correctly. This guide will walk you through the steps to get your Supabase authentication setup.

<Alert type={'warn'}>
  Skipping this step will result in your users not being able to login or sign up.
</Alert>

## Authentication URLs

The first thing you need to do is to set the authentication URLs in the Supabase Dashboard. These URLs are used to redirect users to the correct page after they have logged in or signed up.

1. Go to the [Supabase Dashboard](https://app.supabase.io/).
2. Click on the project you want to use.
3. Go to the **Authentication** tab.
4. Click on **URL Configuration**.
5. Add your Site URL to the **Site URL** field. This is the URL of your MakerKit site (e.g. `https://my-site.com`).
6. Add your Redirect URLs to the **Redirect URLs** field. You need to add at least two URLs: This is the URL of your MakerKit site with `/auth/callback` appended to it (e.g. `https://my-site.com/auth/callback`) and another for redirecting users to their password reset page (e.g. `https://my-site.com/settings/profile/password`).

### Troubleshooting

If you are having issues with authentication, ensure that the Site URL and Redirect URLs are correct. If you are using a custom domain, ensure that you are using the correct domain in the Site URL and Redirect URLs.

<Alert type="warn">
  NB: if your domain includes "www", ensure you include it in the Site URL and Redirect URLs. If your domain does not
  include "www", ensure you do not include it in the Site URL and Redirect URLs. If these do not match, your users will
  not be able to login.
</Alert>

If something is still not working, please open a support ticket with any useful information (such as server logs).

## Custom SMTP (optional, but recommended)

If you want to send emails from your own domain, you can configure your SMTP settings in the Supabase Dashboard.

This is optional, but recommended if you want to send emails from your own domain.

1. Go to the [Supabase Dashboard](https://app.supabase.io/).
2. Click on the project you want to use.
3. Go to the **Project Settings** tab.
4. Click on **Auth**.
5. Tweak the `SMTP Settings` settings to your liking according to your provider's documentation.

Learn how to setup Supabase authentication with MakerKit.

Setting up Supabase authentication with MakerKit

Learn how to extend and customize the UI of your application.


All the Makerkit kits use Tailwind CSS for styling. Tailwind is a utility-first CSS framework that allows you to build custom designs without leaving your HTML. It's a great choice for Makerkit because it allows you to customize the look and feel of your project without having to write any CSS.

The Tailwind CSS configuration file is located at `tailwind.config.js` in the root of your project.

By default, it looks like this:

```js title="tailwind.config.js"
const colors = require('tailwindcss/colors');

/** @type {import('tailwindcss').Config} */
module.exports = {
  content: ['./app/**/*.{ts,tsx,jsx,js}'],
  darkMode: 'class',
  theme: {
    extend: {
      fontFamily: {
        serif: ['serif'],
        heading: ['system-ui', 'Helvetica Neue', 'Helvetica', 'Arial'],
        sans: [
          'system-ui',
          'BlinkMacSystemFont',
          'Inter',
          'Segoe UI',
          'Roboto',
          'Ubuntu',
        ],
        monospace: [`SF Mono`, `ui-monospace`, `Monaco`, 'Monospace'],
      },
      colors: {
        border: 'hsl(var(--border))',
        input: 'hsl(var(--input))',
        ring: 'hsl(var(--ring))',
        background: 'hsl(var(--background))',
        foreground: 'hsl(var(--foreground))',
        dark: {
          ...colors.slate,
          DEFAULT: colors.slate[950],
          foreground: colors.slate[100],
        },
        primary: {
          DEFAULT: 'hsl(var(--primary))',
          foreground: 'hsl(var(--primary-foreground))',
          ...colors.violet,
        },
        secondary: {
          DEFAULT: 'hsl(var(--secondary))',
          foreground: 'hsl(var(--secondary-foreground))',
        },
        destructive: {
          DEFAULT: 'hsl(var(--destructive))',
          foreground: 'hsl(var(--destructive-foreground))',
        },
        muted: {
          DEFAULT: 'hsl(var(--muted))',
          foreground: 'hsl(var(--muted-foreground))',
        },
        accent: {
          DEFAULT: 'hsl(var(--accent))',
          foreground: 'hsl(var(--accent-foreground))',
        },
        popover: {
          DEFAULT: 'hsl(var(--popover))',
          foreground: 'hsl(var(--popover-foreground))',
        },
        card: {
          DEFAULT: 'hsl(var(--card))',
          foreground: 'hsl(var(--card-foreground))',
        },
      },
      borderRadius: {
        lg: 'var(--radius)',
        md: 'calc(var(--radius) - 2px)',
        sm: 'calc(var(--radius) - 4px)',
      },
      keyframes: {
        'accordion-down': {
          from: { height: 0 },
          to: { height: 'var(--radix-accordion-content-height)' },
        },
        'accordion-up': {
          from: { height: 'var(--radix-accordion-content-height)' },
          to: { height: 0 },
        },
      },
      animation: {
        'accordion-down': 'accordion-down 0.2s ease-out',
        'accordion-up': 'accordion-up 0.2s ease-out',
      },
    },
  },
  plugins: [require('tailwindcss-animate')],
};
```

The Tailwind configuration gets extended with two additional colors:
`primary` and `dark`.

1. `primary` is the main color of your project. It's used for buttons, links, and other interactive elements. It's also used for some backgrounds of the dark mode.
2. `dark` is the color palette for the dark mode. It's used for the background of the dark mode.

By updating these colors, you can customize the look and feel of your project.

For example:
1. If you want to change the primary color, you can update the `primary` color in the Tailwind configuration. Try changing it to `blue` and see what happens.
2. If you want to change the dark mode background color, you can update the `dark` color in the Tailwind configuration. Try changing it to `slate` and see what happens.

Of course - you can also pass your own palette as the `primary` and `dark` colors.

## Usage in practice

Let's say you want to change the primary color of your project to `indigo`. and the dark mode background color to `zinc`.

```js title="tailwind.config.js"
const colors = require('tailwindcss/colors');

extend: {
  colors: {
    dark: {
      ...colors.zinc,
      DEFAULT: colors.zinc[950],
      foreground: colors.zinc[100],
    },
    primary: {
      DEFAULT: 'hsl(var(--primary))',
      foreground: 'hsl(var(--primary-foreground))',
      ...colors.indigo,
    }
  },
},
```

Additionally, please update the CSS variables of your global CSS file `globals.css` to match the new colors by updating the `--primary` color to match using the `hsl` value of the `indigo` color.

To have a reference of the Tailwind palette as `hsl` values, you can use [this reference from the ShadcnUI repository](https://github.com/shadcn-ui/ui/issues/669).

When you want to use the primary color in your project, you can use the `primary` color class.

```tsx title="src/components/PrimaryButton.tsx"
import React from 'react';

export const PrimaryButton = () => {
  return (
    <button className="bg-primary text-white dark:bg-primary/10 dark:text-primary px-4 py-2 rounded">
      Click me
    </button>
  );
};
```

Learn how to customize Tailwind CSS in your Makerkit project.

Tailwind CSS


ShadCN UI is a template library based on Radix UI and Tailwind CSS. It provides a set of high-quality React components out of the box that are fully accessible, customizable, and themable.

Makerkit was an early adopter of ShadCN UI, and we use it to build our own UI components. With that, we used very different styling conventions early on, which means copy/pasting components from our docs to your project might not work as expected.

ShadCN UI is **configured** in all Makerkit projects as of the latest versions, while versions released before 28 September 2023 will not work seamlessly.

Makerkit only ships the components it uses in the core kit: to use other components, you will need to either use the CLI or import them manually.

## Theming

### Updating the Colors in CSS

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

For examples, check out the [ShadCN UI Themes Page](https://ui.shadcn.com/themes).

### Updating the Colors in Tailwind

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 `violette.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.


Learn how to add new components from Shadcn UI to your project.

Shadcn UI


By default, the Makerkit kits come with a light and a dark theme, and we provide a toggle to let users switch between them.

## Changing the default theme

To change the default theme, you need to update the theme in your `src/configuration.ts` file.

```ts title="src/configuration.ts" {2}
const configuration = {
  theme: Themes.Dark,
  ...
}
```

## Disabling the theme toggle

To disable the theme toggle, you need to update the `src/configuration.ts` file.

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

This will prevent the theme toggle from appearing in the application.

Learn how to configure the default theme of your application.

Themes

Learn the MakerKit best practices for building and shipping your app

Data Fetching


Similarly to reading data, we may want to create a `custom
hook` also when we write, update or delete data to our Supabase database.

Assuming we have an entity called `tasks`, and we want to create a hook to
create a new `Task`, we can do the following.

1. First, we create a new hook at `lib/tasks/hooks/use-create-task.ts`
2. We add the `tasks` table name to `lib/db-tables.ts`
3. We create a `mutations.ts` file within `lib/tasks`

```ts
export const TASKS_TABLE = `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,
    done: task.done,
  });
}
```

### Calling mutation using a Server Action

The best way to call a mutation is to use a Next.js Server Action. This way, we can use the `revalidatePath` function to revalidate the page that we want to revalidate after the mutation is completed.

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

Then, we call the action from a form:

```tsx
'use client';

import type { FormEventHandler } from 'react';
import { useCallback, useTransition } from 'react';
import { toast } from 'sonner';
import { useRouter } from 'next/navigation';

import TextField from '~/core/ui/TextField';
import Button from '~/core/ui/Button';
import If from '~/core/ui/If';
import useCurrentOrganization from '~/lib/organizations/hooks/use-current-organization';
import { createTaskAction } from '~/lib/tasks/actions';
import useCsrfToken from '~/core/hooks/use-csrf-token';

const CreateTaskForm = () => {
  const [isMutating, startTransition] = useTransition();
  const organization = useCurrentOrganization();
  const organizationId = organization?.id as number;
  const csrfToken = useCsrfToken();
  const router = useRouter();

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

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

      if (name.trim().length < 3) {
        toast.error('Task name must be at least 3 characters long');

        return;
      }

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

      startTransition(async () => {
        await createTaskAction({ task, csrfToken });

        router.push('../tasks');
      });
    },
    [csrfToken, organizationId, router]
  );

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

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

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

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

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

  return date.toDateString();
}

export default CreateTaskForm;
```

### Calling mutation using SWR

Alternatively, we can use the `createTask` mutation in our `useCreateTask` hook.

We will be using the `useSWRMutation` hook from `swr` 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;
```

Let's take a look at a complete example of a form that makes a request using
the hook above:

```tsx title="components/tasks/CreateTaskForm.tsx"
import { useRouter } from 'next/router';
import type { FormEventHandler } from 'react';
import { useCallback } from 'react';
import { toast } from 'sonner';

import TextField from '~/core/ui/TextField';
import Button from '~/core/ui/Button';
import useCreateTaskMutation from '~/lib/tasks/hooks/use-create-task';

import useCurrentOrganization from '~/lib/organizations/hooks/use-current-organization';

const CreateTaskForm = () => {
  const createTaskMutation = useCreateTaskMutation();
  const router = useRouter();
  const organization = useCurrentOrganization();
  const organizationId = organization?.id as number;

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

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

      if (name.trim().length < 3) {
        toast.error('Task name must be at least 3 characters long');

        return;
      }

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

      // create task
      await createTaskMutation.trigger(task);

      // redirect to /tasks
      return router.push(`/tasks`);
    },
    [router, createTaskMutation, organizationId]
  );

  return (
    <form onSubmit={onCreateTask}>
      <div>
        <TextField.Label>
          Name
          <TextField.Input
            required
            name={'name'}
            placeholder={'ex. Launch on IndieHackers'}
          />
          <TextField.Hint>Hint: whatever you do, ship!</TextField.Hint>
        </TextField.Label>

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

        <div>
          <Button>Create Task</Button>
        </div>
      </div>
    </form>
  );
};

export default CreateTaskForm;

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

  return date.toDateString();
}
```


Learn how to write, update and delete data using the Supabase Database in Makerkit

Writing data to Database


When fetching data from the Supabase Postgres Database, we use the Supabase
JS client.

To make data-fetching from Supabase more reusable, our convention is to
create a custom React hook for each query we make.

For example, let's take a look at the hook to fetch an organization from
Supabase.

First, we want to write a query that receives two parameters:
1. a Supabase client interface
2. an organization ID

```tsx title="organizations/queries.ts"
export function getOrganizationById(
  client: Client,
  organizationId: number
) {
  return client
    .from('organizations')
    .select(`
      id,
      name,
      logoURL: logo_url
    `)
    .eq('id', organizationId)
    .throwOnError()
    .single();
}
```

It's important that we pass the client as a parameter so that we can use the
function in both the browser and the server.

Now, if we want to use a React Hook to fetch the organization from one of
our components, we can use the `useSWR` hook from `swr`:

```tsx
import useSupabase from '~/core/hooks/use-supabase';
import { getOrganizationById } from '~/lib/organizations/database/queries';
import useSWR from 'swr';

function useOrganizationQuery(
  organizationId: number
) {
  const client = useSupabase();
  const key = ['organization', organizationId];

  return useSWR(key, async () => {
    return getOrganizationById(client, organizationId).then(
      (result) => result.data
    );
  });
}

export default useOrganizationQuery;
```
---

There are two ways to use this function:

1. **Server**: directly, in a server-side function such as: a Route Handler, a Server Action, a Server Component, or a Middleware
2. **Client**: indirectly, in a React Hook in a client-side component

### Retrieving data in a server-side function

Let's see some scenarios where we can use this function in a server-side.

#### Route Handler

When you are fetching data from a Route Handler, you can use the `getSupabaseRouteHandlerClient` function.

```tsx title="pages/api/organizations/[id]/route.ts"

import { getOrganizationById } from '~/lib/organizations/database/queries';
import getSupabaseRouteHandlerClient from '~/core/supabase/route-handler-client';
import { NextRequest, NextResponse } from "next/server";

export const GET = async (
  req: NextRequest,
  { params }: { params: { id: string } }
) => {
  const client = getSupabaseRouteHandlerClient();
  const { data } = await getOrganizationById(client, params.id);

  return NextResponse.json(data);
};
```

### Server Action

When you are performing mutations using React Server Actions, you can use the `getSupabaseServerActionClient` function to read data from the Supabase database.

```tsx
'use server';

import getSupabaseServerActionClient from '~/core/supabase/action-client';
import { getOrganizationById } from '~/lib/organizations/database/queries';

export async function getOrganizationByIdAction(
  organizationId: number
) {
  const client = getSupabaseServerActionClient();
  const { data } = await getOrganizationById(client, organizationId);

  return data;
}
```

### Server Component

When you are fetching data from a Server Component, you can use the `getSupabaseServerComponentClient` function.

```tsx
import getSupabaseServerComponentClient from '~/core/supabase/server-component-client';
import { getOrganizationById } from '~/lib/organizations/database/queries';

interface Params {
  params: {
    id: string;
  };
}

async function OrganizationPage({ params }: Params) {
  const client = getSupabaseServerComponentClient();
  const organization = await getOrganizationById(client, params.id);

  return <div>{organization.name}</div>;
}
```

### Retrieving data using a React hook

Now that we have a hook to fetch an organization, we can use it in our
components to retrieve the data.

```tsx
import { useOrganizationQuery } from './use-organization-query';

function OrganizationCard({ organizationId }) {
  const {
    data: organization,
    isLoading,
    error
  } = useOrganizationQuery(organizationId);

  /* data is loading */
  if (isLoading) {
    return <div>Loading...</div>
  }

  /* request errored */
  if (error) {
    return <div>Error!</div>
  }

  /* request successful, we can access "organization" */
  return <div>{organization.name}</div>;
}
```


Learn how fetch data from your Supabase database in Makerkit and Next.js

Fetching data from Supabase


Starting from the version 0.2.0, the Makerkit Supabase Next.js starter kit comes with support for Server Actions. Next.js Server Actions allow us to call functions on the server side, which is useful for mutating data.

This is the default way of mutating data in Makerkit - so I recommend you to use this approach instead of the client-side approach.

Makerkit offers support for some built-in features that allow you to protect your endpoints form unauthorized access and CSRF attacks.

## Creating a Server Action

You have two ways of creating a Server Action:

1. Defining a server function inline within a server component
2. Defining server functions into a separate file and exporting them to be used inside client components

### Defining a file for server functions

Assuming you have a `lib/tasks` folder, you can create a file called `lib/tasks/actions.ts` and define server actions inside it.

#### How to define a server action

Actions can be defined in two ways:

1. If you want to pass it to a `form` element, you need to use `FormData` as the parameter type.
2. Alternatively, you can customize the parameters as you wish - and call it imperatively from a client component just like a normal function

#### Utility functions

We can use two utilities:

1. `withSession` - this utility will check if the request contains a valid session
2. `withAdminSession` - this utility will check if the request contains a valid session from a Super Admin that can access the admin panel

#### Defining a Form Action

When defining server actions that will be used by a `form` element, you need to use the `FormData` type as the parameter type.

```ts
'use server';

import { z } from 'zod';

import { withSession } from '~/core/generic/actions-utils';
import getSupabaseServerActionClient from '~/core/supabase/action-client';

const zodSchema = z.object({
  task: z.object({
    name: z.string().nonempty(),
  }),
});

export const insertNewTask =
  withSession(
    async (data: FormData) => {
      const client = getSupabaseServerActionClient();
      const body = zodSchema.parse(Object.fromEntries(data.entries()));

      await insertNewTask(client, body.task);

      return {
        success: true,
      };
    }
  );
```

To call server actions from Forms, you can use the `action` attribute. This attribute will be used to call the server action.

```tsx
function TaskForm() {
  return (
    <form action={insertNewTask}>
    ...
    </form>
  );
}

export default TaskForm;
```

### Defining a Custom Server Action

Below we define a custom server action that takes two parameters: `task` and `csrfToken`. This action will insert a new task into the database.

```ts
'use server';

import { withSession } from '~/core/generic/actions-utils';
import getSupabaseServerActionClient from '~/core/supabase/action-client';

export const insertNewTask = withSession(
    async (params: {
      task: Task;
    }) => {
      const client = getSupabaseServerActionClient();

      await insertNewTask(client, params);

      return {
        success: true,
      };
    }
);
```

While we don't use the `csrfToken` parameter in the function body, the middleware will check if the request contains a valid CSRF token by checking against this property name. Therefore, the TS signature of the function needs to contain this parameter.

To call this function from a client component, you can do the following:

```tsx
import {FormEventHandler, useCallback, useTransition } from "react";

function TaskForm() {
  const [isPending, startTransition] = useTransition();

  const onSubmit: FormEventHandler = useCallback(e => {
    e.preventDefault();

    const data = new FormData(e.target as HTMLFormElement);
    const taskName = data.get("name") as string;

    startTransition(async () => {
      await insertNewTask({
        task: {
          name: taskName,
        },
      });
    });
  });

  return (
    <form onSubmit={onSubmit}>
    ...
    </form>
  );
}

export default TaskForm;
```

## Learn more about Server Actions

To learn more about server actions, we have a simple tutorial that you can follow: [Introduction to Next.js Server Actions](/blog/tutorials/nextjs-server-actions)

Learn how mutate data using the new Next.js Server Actions in the Makerkit Supabase Next.js starter kit

Mutating data using Server Actions


To use API Routes in your Next.js Project, you can create a `route.ts` file within the `app` directory, which will be treated automatically as an API Route.

To export an handler, we need to export the HTTP verb we want to handle, such as `GET`, `POST`, `PUT`, etc.

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

export async function GET(
  req: NextRequest
) {
  return NextResponse.json({ hello: "world" });
}
```

<Alert type={'warn'}>
  Don't confuse API Routes in the App Directory with API Routes in the Pages Directory.

  They are different and the signature doesn't match. Copy/pasting examples from the pages directory will not work.
</Alert>

## Calling API Routes

To call API Routes, you have two ways:
1. Use our utility function that wraps `fetch` and automatically inserts the CSRF token for you
2. Manually call the `fetch` function and insert the CSRF token yourself

The Middleware will reject every mutation request that does not add a CSRF token to the request. You can disable this, but it is not recommended.

### Using the Utility Function

By using the `useApiRequest` utility function, you can easily call API Routes from your application. In the example below, we use both the `useApiRequest` and `useSWR` hooks to fetch data from an API Route.

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

To use the `useTransferOrganizationOwnership` hook, we can simply call it from our component.

```tsx
function Component() {
  const { trigger } = useTransferOrganizationOwnership();

  // use trigger to call the mutation
}
```

Using `useSWRMutation` is not required, but it is recommended.

## CSRF Check

By default, the CSRF check is enabled. This means that every mutation request must include a CSRF token.

If you use the utility `useApiRequest` function, this is handled automatically for you. If you use `fetch` directly, you must add the CSRF token yourself.

To add the CSRF token, you can use the `useCsrfToken` hook.

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

function MyComponent() {
  const { csrfToken } = useCsrfToken();

  // use csrfToken in your fetch request

  return (
    <button onClick={() => {
      fetch('/api/my-route', {
        method: 'POST',
        headers: {
          'Content-Type': 'application/json',
          'X-CSRF-Token': csrfToken,
        },
      });
    }}>Click</button>
  );
}
```


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


To upload data to Supabase Storage, we can use the Supabase JavaScript client. 

## Uploading a file

To upload a file, we can use the `upload` method.

For example, the code below is the code that uploads a user's profile image to the `avatars` bucket:

```ts
async function uploadUserProfilePhoto(
  client: SupabaseClient,
  photoFile: File,
  userId: string
) {
  const bytes = await photoFile.arrayBuffer();
  const bucket = client.storage.from('avatars');
  const extension = photoFile.name.split('.').pop();
  const fileName = `${userId}.${extension}`;

  const result = await bucket.upload(fileName, bytes, {
    upsert: true,
  });

  if (!result.error) {
    return bucket.getPublicUrl(fileName).data.publicUrl;
  }

  throw result.error;
}
```

You can also combine the above with `useSWRMutation` from `SWR` when you use the code above from a React component:

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

function useUpdateProfile() {
  const client = useSupabase();
  const key = 'useUpdateProfile';

  return useSWRMutation(key, async (_, { arg: data }: { arg: {
    file: File;
    userId: string;
  } }) => {
    return updateUserData(client, data);
  });
}
```

And then, you can use it like this:

```tsx
const updateProfile = useUpdateProfile();

<Form onUpload={(file: File, userId: string) => {
  return updateProfile.trigger({ file, userId })
} />
```

Uploading data to Storage

Development


Here are all the commands defined in the MakerKit's template:

### Run the development server

Run the command:

```
npm run dev
```

### Build a production bundle

Run the command:

```
npm build
```

### Start a production server

Run the command after building the application with the `build` command:

```
npm start
```

This is optional as it is automatically called after the `build` command.

### Format all the files

Run the command:

```
npm run format
```

### Type checking

Run the command:

```
npm run typecheck
```

### Linting

Run the command:

```
npm run lint
```

### Start the Supabase Local Environment

Run the command:

```
npm run supabase:start
```

This is needed during development. It requires Docker to be up and running.

### Stopping the Supabase Local Environment

Run the command:

```
npm run supabase:stop
```

### Reset the Supabase Local Environment Database

Run the command:

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

### Running the Supabase Database Tests

Run the command:

```
npm run test:db
```

### Running and resetting the Supabase Database Tests

Run the command:

```
npm run test:reset:db
```

### Run Cypress for E2E Tests (with UI)

Run the command:

```
npm run cypress
```

### Run Cypress for E2E Tests (Headless)

Run the command:

```
npm run cypress:headless
```

### Run E2E Tests and Exit

Run the command:

```
npm test:e2e
```

### Run the Local Stripe Webhooks Server

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

Run the command:

```
npm run stripe:listen
```

### Run the Mock Stripe Server

Run the command:

```
npm run stripe:mock-server
```

### Kill Ports

The following commands kills all the ports that need to be free to run the Makerkit stack. This can be necessary after running the tests, for example when the emulators don't free up the ports after shutting down.

Run the command:

```
npm run killports
```


All the commands to use for your Makerkit app


The Makerkit's boilerplate codebase is formatted with *Prettier*. You can configure it as you wish by updating the file Prettier configuration in the `package.json` file:

The default settings look like the below:

```json
{
  "tabWidth": 2,
  "useTabs": false,
  "semi": true,
  "arrowParens": "always",
  "parser": "typescript",
  "printWidth": 80,
  "singleQuote": true
}
```

For example, to remove semicolons, update the `semi` and set it to `false`.

After adjusting the Prettier configuration, you can reformat the whole project by running the following command:

```
npm run format
```


Adjust the codebase style according to your preferences


MakerKit uses the popular package `nodemailer` to allow you to send emails.

Normally, **you would use a service for sending transactional emails** such as SendGrid, Mailjet, MailGun, Postmark, and so on.

These are all valid, and it doesn't really matter what you use. In
fact, as long as you provide the SMTP credentials for your service, you shouldn't be needing any other change.

## Email Configuration

To add your service's configuration, fill the environment variables in your production environment.

This is best done from your Hosting provider's safe environment variables, or from your CI/CD pipeline.

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

The details above are provided by the service you're using.

**Note**: Some email providers don't like the `EMAIL_SENDER` format. If you're having issues, try using just the email address, such as `info@makerkit.dev`.

<Alert type='warn'>
  When running the emulators, by default, Makerkit uses InBucket for sending
  emails, and not your production service. Read below for more info.
</Alert>

## Sending Emails

To send emails, import and use the `sendEmail` function, such as below:

```tsx
interface SendEmailParams {
  from: string;
  to: string;
  subject: string;
  text?: string;
  html?: string;
}

import { sendEmail } from '~/core/email/send-email';

function sendTransactionalEmail() {
  const sender = configuration.email.senderAddress;

  return sendEmail({
    to: `youruser@email.com`,
    from: sender,
    subject: `Achievement Unlocked!`,
    html: `Yay, you unlocked an achievement!`,
  });
}
```

## Using react.email to render emails

Makerkit's newest versions use [react-email](https://react.email) to render emails: this is a great library that allows us to write emails using React components.

By default, Makerkit's only email is the one sent when inviting members to a Makerkit application - but you can leverage this library to write your own emails for your application.

For example, here's the code for the email sent when inviting members:

```tsx title="src/lib/emails/invite.ts"
interface Props {
  organizationName: string;
  organizationLogo?: string;
  inviter: Maybe<string>;
  invitedUserEmail: string;
  link: string;
  productName: string;
}

export default function renderInviteEmail(props: Props) {
  const title = `You have been invited to join ${props.organizationName}`;

  return render(
    <Html>
      <Head>
        <title>{title}</title>
      </Head>
      <Preview>{title}</Preview>
      <Body style={{ width: '500px', margin: '0 auto', font: 'helvetica' }}>
        <EmailNavbar />
        <Section style={{ width: '100%' }}>
          <Column>
            <Text>Hi,</Text>

            <Text>
              {props.inviter} with {props.organizationName} has invited you to
              use {props.productName} to collaborate with them.
            </Text>

            <Text>
              Use the button below to set up your account and get started:
            </Text>
          </Column>
        </Section>

        <Section>
          <Column align="center">
            <CallToActionButton href={props.link}>
              Join {props.organizationName}
            </CallToActionButton>
          </Column>
        </Section>

        <Section>
          <Column>
            <Text>Welcome aboard,</Text>
            <Text>The {props.productName} Team</Text>
          </Column>
        </Section>
      </Body>
    </Html>
  );
}
```

### How do I test emails locally?

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

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

The InBucket container runs automatically when starting the Supabase platform.

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

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

#### Ethereal

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

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

```bash
ETHEREAL_EMAIL=
ETHEREAL_PASSWORD=
```

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


Sending emails with a Makerkit application


Supabase uses RLS policies to protect your data. RLS are useful for two main reasons:

1. Supabase exposes your database directly to your clients. This means that your clients can query your database directly. RLS policies allow you to restrict what data they can access.
2. You can use SQL policies to apply access rules to your data. This helps you to keep your data secure without having to write any additional code.

In this document, we'll list some common RLS policies you can apply to your data in Makerkit.

You can copy and paste some of this (provided the table names match) into your database so that you can get started quickly.

## Common RLS Policies

### Restricting access to a table based on a column

This policy will restrict access to a table based on a column. In this example, we're restricting access to the `users` table based on the `id` column.

```sql
create policy "Restrict access to user tasks to their own tasks"
  on tasks
  for select
  to authenticated
  using (user_id = auth.uid());
```

### Restricting write access to a table based on a column

This policy will restrict write access to a table based on a column. In this example, we're restricting write access to the `users` table based on the `id` column.

```sql
create policy "Restrict write access to authenticated users"
  on users
  for insert
  to authenticated
  with check (id = auth.uid());
```

#### Restrictive Policies

If you want these rules to be `restrictive` (i.e. they apply to all queries), then you can add `as restrictive`:

```sql
create policy "Restrict write access to authenticated users"
  on users
  as restrictive;
  for insert
  to authenticated
  with check (id = auth.uid())
```

This means that if you have 2 `select` policies, one `restrictive` and one `permissive`, then the `restrictive` policy will take precedence. If the `restrictive` policy fails, then the `permissive` policy will not apply.

This is useful when a policy needs to apply to all queries.

## Subscriptions and RLS

RLS policies are applied to subscriptions. This means that if you have a subscription that returns data that the user doesn't have access to - then the subscription will fail.

Let's see how we can use RLS for restricting access to subscriptions.

This is **very dependent on your use case**. You'll need to think about how you want to restrict access to your data. But for the sake of this example, let's assume that we want to restrict how many tasks a user can write to the database.

### Storing your Plans in the database

First, we'll need to store our plans in the database. We'll create a `plans` table that stores the `id`, `name`, and `max_tasks` for each plan.

You have two options here when talking about Stripe:
1. assign a plan to a Product ID
2. assign a plan to a Price ID

If you need different quotas for monthly and yearly plans - then you'll need to assign a plan to a Price ID. If you don't need different quotas for monthly and yearly plans - then you can assign a plan to a Product ID.

In the example below, we're assigning a plan to a Price ID.

```sql
create table plans (
  name text not null,
  price_id text not null,
  task_quota int not null,
  primary key (product_id)
);
```

We also allow read access to this table for all authenticated users:

```sql
create policy "Allow all authenticated users to read plans"
    on plans
    as restrictive
    for select
    to authenticated
    using (true);
```

#### A function to get the organization's subscription

Let's create an SQL function that returns the user's subscription:

```sql
create or replace function get_active_subscription(user_id bigint)
returns table (
  period_starts_at timestamptz,
  period_ends_at timestamptz,
  price_id text,
  "interval" text
) as $$
begin
    return query select subscriptions.period_starts_at, subscriptions.period_ends_at, subscriptions.price_id, subscriptions."interval" from public.subscriptions
    where subscriptions.user_id = user_id and (subscriptions.status = 'active' or subscriptions.status = 'trialing');
end;
$$ language plpgsql;
```

#### A function to get the user's task count

Let's create an SQL function that returns the user's task count:

```sql
create or replace function get_user_task_count(user_id bigint)
returns int as $$
declare
    task_count int;
begin
    select count(*)
        from tasks
        where tasks.user_id = user_id
        into task_count;

    return task_count;
end;
$$ language plpgsql;
```

#### A function to check if the organization can create a task

Let's create an SQL function that returns `true` if the user can create a task:

```sql
create or replace function user_can_create_task(user_id bigint)
returns boolean as $$
declare
    task_count int;
    user_price_id text;
    plan_task_quota int;
begin
    select get_user_task_count(user_id)
        into task_count;

    select price_id
    into user_price_id
    from get_active_subscription(user_id);

    if user_price_id is null then
        raise exception 'User does not have an active subscription';
    end if;

    select task_quota from plans where price_id = user_price_id into plan_task_quota;

    return task_count < plan_task_quota;
end;
$$ language plpgsql;
```

Here we store the total tasks count in a variable:

```
select get_user_task_count(user_id) into task_count;
```

Then we get the user's price ID:

```
select price_id
    into user_price_id
    from get_active_subscription(user_id);
```

If the user doesn't have an active subscription - then we throw an error:

```
if user_price_id is null then
    raise exception 'User does not have an active subscription';
end if;
```

What if you wanted to provide a default plan for users that don't have an active subscription? You could do something like this for allowing 10 tasks for users that don't have an active subscription:

```
if user_price_id is null then
  return task_count < 10;
end if;
```

Then we get the plan's task quota:

```
select task_quota from plans where price_id = user_price_id into plan_task_quota;
```

Finally, we check that the count of tasks is less than the plan's task quota:

```
return task_count < plan_task_quota;
```

#### Wrapping it all up in a policy

We can now write a policy that restricts access to the `tasks` table based on the user's task quota:

```sql
create or replace policy "Only allow users to create tasks if they have enough quota"
    on tasks
    as restrictive
    for insert
    to authenticated
    with check (
        user_can_create_task(user_id)
    );
```

## You don't always need RLS

Sometimes - you don't need RLS. As long as RLS is enabled on the table - you can think about not applying any RLS policies.

Instead - you can manage access to the data using traditional server-side code. This is useful if you want to apply more complex access rules to your data or when the data is not directly updated by the client - but instead by a server-side process (such as a cron job or a webhook).

## Restricting Functions

Sometimes - you need a security definer functions. This is useful for bypassing RLS policies. But it's risky.

If you want to run a function - making sure only the admin service role ca call it, check the role of the user calling the function:

```sql
create or replace function create_task(user_id bigint, name text)
returns tasks as $$
begin
    if current_setting('role') != 'service_role' then
        raise exception 'Only admins can call this function';
    end if;

    insert into tasks (user_id, name) values (user_id, name);

    return (select * from tasks where id = currval('tasks_id_seq'));
end;
$$ language plpgsql security definer search_path = public;
```

This function will throw an error if it's called from the client. You can then call this function from the server using a service role key and ensure that the user has enough quota to create a task server-side before calling this function.

To protect your data, you can apply row-level-security policies to your data. This article lists some common policies you can apply to your data

Common Row-Level-Security Policies you can apply to your data


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

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

All Makerkit's API routes are secured with Zod: in this document, we want
to explain the conventions used by the SaaS Boilerplate, and how to use it
for your API endpoints.

When we write an API endpoint or a Server Action, 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 a Server Action that validates the body of the
function, which we expect to be equal to the `Body` interface.

```tsx
'use server';

export async function serverAction(
  data: z.infer<
    ReturnType<typeof getBodySchema>
  >
) {
  // we can safely use data with the interface Body
  const bodyResult = await getBodySchema().parseAsync(data);
  const { displayName, email } = bodyResult;

  return sendInvite({ displayName, email });
}

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

You can also use `safeParse` if you prefer not to throw an error when the
validation fails:

```tsx
'use server';

export async function serverAction(
  data: z.infer<
    ReturnType<typeof getBodySchema>
  >
) {
  // we can safely use data with the interface Body
  const bodyResult = await getBodySchema().safeParseAsync(data);

  if (bodyResult.success === false) {
    return bodyResult.error;
  }

  const { displayName, email } = bodyResult.data;

  return sendInvite({ displayName, email });
}

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

The same applies to Route Handlers:

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

export async function POST(
  request: NextRequest
) {
  const body = await request.json();
  const bodyResult = await getBodySchema().safeParseAsync(body);

  if (bodyResult.success === false) {
    return bodyResult.error;
  }

  const { displayName, email } = bodyResult.data;

  return sendInvite({ displayName, email });
}

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

To learn more about validating data with Zod, we suggest you
check out [the Zod official documentation on GitHub](https://github.com/colinhacks/zod).


Zod is a library for validating data with awesome support for Typescript. Learn how to use it within your Makerkit project.

403 error with API/Actions

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

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

Subscribe to our Newsletter