Tutorials


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

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

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

## Prerequisites

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

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

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

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

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

Building a SaaS tasks application with Makerkit


## Initializing the Project

You have two ways to initialize the project:

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

### 1. Forking the Repository

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

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

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

### 2. Cloning the Repository

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

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

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

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

### Reinitialize Git

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

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

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

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

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

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

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

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

Initial Setup


When we run the stack of a Makerkit application, we will need to run a few commands before:
1. **Next.js**: First, we need to run the Next.js development server
2. **Supabase**: We need to run the Supabase local environment using Docker
3. **Stripe CLI** (optional): If you plan on interacting with Stripe, you are also required to run the Stripe CLI, which allows us to test the webhooks from Stripe against our local server.

### Running the Next.js development server

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

```
npm run dev
```

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

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

### Running the Supabase Local environment

To run the Supabase local environment, we need to first run Docker. Then,
open a new terminal (or, better, from your IDE) and run the following
command:s

```
npm run supabase:start
```

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

```
> supabase start

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

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

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

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

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

```
npm run supabase:stop
```

#### Supabase Studio UI

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

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

### Running the Stripe CLI (optional)

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

```
npm run stripe:listen
```

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

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

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

```
STRIPE_WEBHOOK_SECRET=<KEY>
```

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

#### 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 the app locally for development and testing.

Running the App



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

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

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

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

Here is what the configuration file looks like:

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

const env = getEnv() ?? {};

const configuration = {
  site: {
    name: 'Awesomely - Your SaaS Title',
    description: 'Your SaaS Description',
    themeColor: '#ffffff',
    themeColorDark: '#0a0a0a',
    siteUrl: env.SITE_URL,
    siteName: 'Awesomely',
    twitterHandle: '',
    githubHandle: '',
    language: 'en',
    convertKitFormId: '',
    locale: env.DEFAULT_LOCALE,
  },
  auth: {
    // NB: Enable the providers below in the Supabase Console
    // in your production project
    providers: {
      emailPassword: true,
      phoneNumber: false,
      emailLink: false,
      oAuth: ['google'] as Provider[],
    },
  },
  production: env.NODE_ENV === 'production',
  environment: env.ENVIRONMENT,
  paths: {
    signIn: '/auth/sign-in',
    signUp: '/auth/sign-up',
    emailLinkSignIn: '/auth/link',
    onboarding: `/onboarding`,
    appHome: '/dashboard',
    settings: {
      profile: '/settings/profile',
      authentication: '/settings/profile/authentication',
      email: '/settings/profile/email',
      password: '/settings/profile/password',
    },
    api: {
      checkout: `/stripe/checkout`,
      billingPortal: `/stripe/portal`,
    },
    searchIndex: `/public/search-index`,
  },
  email: {
    host: '',
    port: 587,
    user: '',
    password: '',
    senderAddress: 'MakerKit Team <info@makerkit.dev>',
  },
  sentry: {
    dsn: env.SENTRY_DSN,
  },
  stripe: {
    plans: [
      {
        name: 'Basic',
        description: 'Description of your Basic plan',
        price: '$9/month',
        stripePriceId: '',
        features: [
          'Basic Reporting',
          'Up to 20 users',
          '1GB for each user',
          'Chat Support',
        ],
      },
    ],
  },
};

export default configuration;
```

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


Learn how to set up up your project's configuration

Project Configuration


The starter project comes with two different environment variables files:
1. **.env**: the main environment file
2. **.env.development**: the development environment file (used when running the project locally in development mode)
3. **.env.production**: the production environment file (used when deploying or running the build command)
4. **.env.local**: this environment file is loaded when running the project locally. It won't be committed to Git. Useful for adding secrets that you don't want to commit to Git.
5. **.env.test**: this environment file is loaded when running the Cypress
E2E tests. You would rarely need to use this.

The default environment variables for the production environment are:

```bash
NEXT_PUBLIC_SITE_URL=
ENVIRONMENT=production

# SUPABASE
NEXT_PUBLIC_SUPABASE_URL=
NEXT_PUBLIC_SUPABASE_ANON_KEY=
NEXT_PUBLIC_REQUIRE_EMAIL_CONFIRMATION=true

# SERCET KEY TO SIGN SECRETS. REPLACE THE BELOW WITH A RANDOM AND COMPLEX STRING. KEEPT IT SAFE.
SECRET_KEY=

# STRIPE
STRIPE_WEBHOOK_SECRET=
STRIPE_SECRET_KEY=
```



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

Environment Variables


This SaaS template uses Tailwind CSS for styling the application.

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

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

### Updating the Primary color of your app

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

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

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

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

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

### Dark Mode

Makerkit also ships with a dark theme.

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

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

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

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

## Caveats

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

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

Tailwind CSS and Styling


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

The kit supports the following strategies:

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

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

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

### How does Authentication work?

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

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

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

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

### Authentication Strategies

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

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

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

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

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

We will do the following:

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

And the result will be similar to the image below:

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

### Creating Accounts

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

### Requiring Email Verification

By default, Supabase requires users to verify their email address before being able to access the application.

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

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

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

## Emails sent by Supabase

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

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

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

Authentication


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

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

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

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

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

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

After the user submits the form, the API will receive the request and:

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

I encourage you to visit the [Local Supabase Studio UI](http://localhost:54323) and see the data created.

### What is an "Organization"?

Organizations are groups of users.

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

Users can:

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

### Can I remove this step?

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

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

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

Onboarding Flow


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

### Routing Structure

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

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

  └── onboarding

  __site
    └── faq
    └── pricing

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

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

  └── (app)
    └── dashboard
      └── page.tsx

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

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

      └── subscription

  └── page.tsx
```

The routes are split in the following way:

1. The website's pages are placed under `(site)`
2. The auth pages are placed under `auth`
3. The internal pages (behind auth) pages are placed under `(app)`

Some pages in the "middle" are placed outside `(app)`, such as the Invites page and the Onboarding flow. These require custom handling.

### Setting the application's Home Page

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

### Demo: Tasks Application

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

Here is a quick demo of what we will build:

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

### Routing

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

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

To create these two pages, we will create a folder named `tasks` at `src/app/(app)/tasks.` In the folder `src/app/(app)/tasks` we will create three `Page Components`:

1. The tasks list page at `tasks/page.tsx`
2. The form to create a new task at `tasks/new/page.tsx`
3. The task's own page at `tasks/[task]/page.tsx`.

```
├── app
  └── (app)
    └── tasks
      └── page.tsx
      └── new
        └── page.tsx
      └── [task]
        └── page.tsx
```

#### 1. List Page

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

```tsx
import React, { use } from 'react';
import { RectangleStackIcon } from '@heroicons/react/24/outline';
import { cookies } from 'next/headers';

import { parseOrganizationIdCookie } from '~/lib/server/cookies/organization.cookie';
import getSupabaseServerClient from '~/core/supabase/server-client';
import { getTasks } from '~/lib/tasks/queries';
import AppHeader from '~/app/(app)/components/AppHeader';
import Trans from '~/core/ui/Trans';
import AppContainer from '~/app/(app)/components/AppContainer';
import TasksContainer from '~/app/(app)/tasks/components/TasksListContainer';

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

function TasksPage() {
  const tasks = use(loadTasksData());

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

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

      <AppContainer>
        <TasksContainer tasks={tasks} />
      </AppContainer>
    </>
  );
}

export async function loadTasksData() {
  const organizationId = await parseOrganizationIdCookie(cookies());
  const client = getSupabaseServerClient();

  const { data: tasks, error } = await getTasks(client, Number(organizationId));

  if (error) {
    return [];
  }

  return tasks;
}

export default TasksPage;
```

We use the function `loadTasksData` to fetch the data from the RSC component `TasksPage`.

To retrieve the selected organization ID, we can retrieve it from the cookie using `parseOrganizationIdCookie(cookies())`: the cookie is set in upper `(app)` layout, and may not be finished running when the page is rendered.
To avoid this, if you're requiring the organization ID in the application home page, you will want to use the following pattern:

```tsx
export async function loadTasksData() {
  const client = getSupabaseServerClient();
  const session = await requireSession(client);

  if ('redirect' in session) {
    return redirect(session.destination);
  }

  const userId = session.user.id;
  const organizationCookie = await parseOrganizationIdCookie(cookies());

  let organizationId = Number(organizationCookie);

  if (!organizationId) {
    const result = await getCurrentOrganization(client, { userId });

    if (!result) {
      return redirect(configuration.paths.onboarding);
    }

    organizationId = result.organization.id;
  }

  const { data: tasks, error } = await getTasks(client, organizationId);

  if (error) {
    return [];
  }

  return tasks;
}
```

In the above, we verify that `organizationCookie` is defined, and if not, we retrieve the current organization from the database (ie. the first one in the user's memberships). If no organization is found, we redirect the user to the onboarding flow.

This ensures the organization ID is always defined when we need it.

#### 2. New Task Page

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

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

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

import Trans from '~/core/ui/Trans';

export const metadata = {
  title: 'New Task',
};

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

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

      <AppContainer>
        <div className={'max-w-lg'}>
          <CreateTaskForm />
        </div>
      </AppContainer>
    </>
  );
};

export default NewTaskPage;
```

#### 3. Task Page

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

We will not define `TaskItemContainer`: imagine a task item is a complex component, with a lot of logic and UI. We will not want to duplicate this logic in the list page and the task page. Instead, we will create a container component `TaskItemContainer` that will be used in both pages.

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

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

import Heading from '~/core/ui/Heading';
import Button from '~/core/ui/Button';
import AppHeader from '~/app/(app)/components/AppHeader';
import AppContainer from '~/app/(app)/components/AppContainer';
import TaskItemContainer from '~/app/(app)/tasks/components/TaskItemContainer';

import getSupabaseServerClient from '~/core/supabase/server-client';
import { getTask } from '~/lib/tasks/queries';

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

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

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

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

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

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

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

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

  if (!task) {
    return redirect('/tasks');
  }

  return {
    task,
  };
}

export default TaskPage;
```

### Adding Functionalities to your application

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

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

The above are the things we will do in the following few sections. To clarify further the conventions of this boilerplate, here is what you should know:

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

### Adding page links to the Navigation Menu

#### Updating the Top header Navigation

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

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

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

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

The result will be similar to the images below:

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

Learn how to get started developing new features in your app

Development: adding custom features


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

This involves a couple of steps:

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

##### How is the data structured?

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

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

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

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

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

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

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

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

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

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

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

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

#### Generating the types from the SQL schema

We can generate the types from the SQL schema using the `supabase-js`
library. To run this command, you need to ensure Supabase is running running
`npm run supabase:start`.

You can do so by running the following command:

```bash
npm run typegen
```

The types will be generated at `app/database-types.ts`. We will import the
types whenever we use the Supabase client.

For example:

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

type Client = SupabaseClient<Database>;
```

### Data Fetching: React Hooks to read data from Supabase Postgres

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

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

First, we want to write a function that is responsible for fetching the
tasks using the Supabase Postgres client. We can write this function at
`lib/tasks/queries.ts`:

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

type Client = SupabaseClient<Database>;

export function getTasks(client: Client, organizationId: number) {
  return client
    .from(TASKS_TABLE)
    .select<string, Task>(
      `
      id,
      name,
      organization_id: organizationId,
      dueDate: due_date,
      done
    `
    )
    .eq('organization_id', organizationId)
    .throwOnError();
}
```

The query above will be fetching all the tasks of the organization with the
ID `organizationId`.

As you can see, my convention (used throughout the boilerplate) is to write
queries that inject the Supabase client as a parameter. This allows me to
reuse these functions in both the browser and the server.

Additionally, I also like to write queries that throw errors. This allows me
to catch errors using try/catch blocks rather than using the `error`
property. This is a personal preference, feel free to use the `error` property instead.

Below is the tasks route, where we fetch the data from the server component and pass it down to the client components:

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

import { parseOrganizationIdCookie } from '~/lib/server/cookies/organization.cookie';
import getSupabaseServerClient from '~/core/supabase/server-client';
import { getTasks } from '~/lib/tasks/queries';
import AppHeader from '~/app/(app)/components/AppHeader';
import Trans from '~/core/ui/Trans';
import AppContainer from '~/app/(app)/components/AppContainer';
import TasksContainer from '~/app/(app)/tasks/components/TasksListContainer';

function TasksPage() {
  const tasks = use(loadTasksData());

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

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

      <AppContainer>
        <TasksContainer tasks={tasks} />
      </AppContainer>
    </>
  );
}

export default TasksPage;
```

Below is the function that is responsible for fetching the tasks from Supabase:

```tsx
async function loadTasksData() {
  const organizationId = await parseOrganizationIdCookie(cookies());
  const client = getSupabaseServerClient();

  const { data: tasks, error } = await getTasks(client, Number(organizationId));

  if (error) {
    console.error(`Error fetching tasks: ${error.message}`);

    return [];
  }

  return tasks;
}
```

### Displaying Tasks data

To display the tasks, let's create a new `client` component named `TasksListContainer`:

```tsx title="app/(app)/tasks/components/TasksListContainer.tsx"
'use client';

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

import type Task from '~/lib/tasks/types/task';
import TaskListItem from '~/app/(app)/tasks/components/TaskListItem';

const TasksContainer: React.FC<{
  tasks: Task[];
}> = ({ tasks }) => {
  if (!tasks || tasks.length === 0) {
    return <TasksEmptyState />;
  }

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

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

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

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

function TasksList({
  tasks,
}: React.PropsWithChildren<{
  tasks: Task[];
}>) {
  return (
    <div className={'flex flex-col space-y-4'}>
      {tasks.map((task) => {
        return <TaskListItem task={task} key={task.id} />;
      })}
    </div>
  );
}

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

export default TasksContainer;
```

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

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

Supabase: Data Fetching


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

#### Creating a Task

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

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

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

type Client = SupabaseClient<Database>;

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

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

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

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

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

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

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

export default useCreateTaskMutation;
```

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

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

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

#### Updating a Task

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

We will write another mutation function to update a task:

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

type Client = SupabaseClient<Database>;

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

And we can write a hook to use this mutation:

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

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

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

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

export default useUpdateTaskMutation;
```

#### Deleting a Task

We will write another mutation function to delete a task:

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

type Client = SupabaseClient<Database>;

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

Finally, we write a mutation to delete a task:

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

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

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

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

export default useDeleteTaskMutation;
```

### Using the Modal component for confirming actions

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

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

```tsx
import Modal from '~/core/ui/Modal';
import Button from '~/core/ui/Button';

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

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

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

export default ConfirmDeleteTaskModal;
```

### Wrapping all up: listing each Task Item

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

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

```tsx title="TaskListItem.tsx"
'use client';

import type { MouseEventHandler } from 'react';
import { useCallback, useState } from 'react';
import { TrashIcon } from '@heroicons/react/24/outline';
import toaster from 'react-hot-toast';
import { formatDistance } from 'date-fns';
import { useRouter } from 'next/navigation';
import Link from 'next/link';

import type Task from '~/lib/tasks/types/task';
import Heading from '~/core/ui/Heading';
import IconButton from '~/core/ui/IconButton';
import { Tooltip, TooltipContent, TooltipTrigger } from '~/core/ui/Tooltip';
import useDeleteTaskMutation from '~/lib/tasks/hooks/use-delete-task';
import useUpdateTaskMutation from '~/lib/tasks/hooks/use-update-task';

import ConfirmDeleteTaskModal
  from '~/app/(app)/tasks/components/ConfirmDeleteTaskModal';

const TaskListItem: React.FC<{
  task: Task;
}> = ({ task }) => {
  const getTimeAgo = useTimeAgo();
  const deleteTaskMutation = useDeleteTaskMutation();
  const updateTaskMutation = useUpdateTaskMutation();
  const router = useRouter();
  const [isDeleting, setIsDeleting] = useState(false);

  const onDelete = useCallback(async () => {
    const deleteTaskPromise = deleteTaskMutation
      .trigger(task.id);

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

    await router.refresh();

    setIsDeleting(false);
  }, [deleteTaskMutation, router, task.id]);

  const onDoneChange = useCallback(
    (done: boolean) => {
      const promise = updateTaskMutation.trigger({ done, id: task.id });

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

  const onDeleteRequested: MouseEventHandler = useCallback((e) => {
    e.stopPropagation();
    setIsDeleting(true);
  }, []);

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

              <TooltipContent>
                {task.done ? `Mark as not done` : `Mark as done`}
              </TooltipContent>
            </Tooltip>
          </div>

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

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

          <div className={'flex justify-end'}>
            <Tooltip>
              <TooltipTrigger asChild>
                <IconButton onClick={onDeleteRequested}>
                  <TrashIcon className={'h-5 text-red-500'} />
                </IconButton>
              </TooltipTrigger>

              <TooltipContent>Delete Task</TooltipContent>
            </Tooltip>
          </div>
        </div>
      </div>

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

export default TaskListItem;

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


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

Supabase: Data Writing


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

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

```tsx title="components/tasks/CreateTaskForm.tsx"
'use client';

import type { FormEventHandler } from 'react';
import { useCallback } from 'react';
import { useRouter } from 'next/navigation';
import toaster from 'react-hot-toast';

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

import useCreateTaskMutation from '~/lib/tasks/hooks/use-create-task';
import useCurrentOrganization from '~/lib/organizations/hooks/use-current-organization';

const CreateTaskForm = () => {
  const { trigger, isMutating } = 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) {
        toaster.error('Task name must be at least 3 characters long');

        return;
      }

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

      // create task
      await trigger(task);

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

  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-y-0 md:space-x-2'
          }
        >
          <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;
```

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

Forms


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

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

#### Using the components AppHeader and AppContainer

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

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

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

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

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

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

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

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

Application Pages


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

### Calling API functions from the client

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

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

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

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

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

interface Params {
  membershipId: number;
}

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

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

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

export default useTransferOrganizationOwnership;
```

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

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

#### Sending the CSRF Token

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

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

```tsx
const csrfToken = useCsrfToken();

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

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

### CSRF Token check

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

### API Logging

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

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

We import the logging utility from `~/core/logger`. Typically, you can log every time you perform an action, both before and after. For example:

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

  await performAction();

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

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

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

API Routes


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

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

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

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

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

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

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

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

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

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

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

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

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

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

API Routes Validation



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

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

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

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

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

### Adding new languages

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

Adding a new language is very simple:

1. **Translation Files**: First, we need to create a new folder, such as `/public/locales/es`, and then copy over the files from the English version and start translating files.
2. **Next.js i18n config**: We need to also add a new language to the Next.js i18n
configuration at `src/i18n/i18next.settings.ts`.

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

The configuration will look like the below:

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

#### Setting the default Locale

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

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

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

### Translating Server Components strings

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


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

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

### Translating Client Components strings

When translating client components, you need to ensure you:

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

For example, here is the `SiteLayout` layout:

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

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

        {props.children}

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


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

Translations


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

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

## Client-Side Functions

### Supabase Hooks

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

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

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

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

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

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

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

### Makerkit Hooks

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

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

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

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

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

  return organization?.name;
}
```

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

You can customize this hook to fit your needs.

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

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

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

  if (!status) {
    return false;
  }

  return ACTIVE_STATUSES.includes(status);
}

export default useIsSubscriptionActive;
```

## Server-Side Functions

### 1. `getSupabaseServerClient`: getting the server-side Supabase client

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

```ts
import getSupabaseServerClient from '~/core/supabase/server-client';

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

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

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

```ts
import getSupabaseServerClient from '~/core/supabase/server-client';

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

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

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

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

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

It returns a Supabase Auth `Session` instance:

```ts
import getSupabaseServerClient from '~/core/supabase/server-client';

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

  //
}
```

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

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

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

And returns the organization data:

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

Usage:

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

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

  //
}
```

Using a user ID:

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

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

Using an organization ID:

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

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

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

Functions you need to know

Adding pages to the Marketing Site is easy.

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

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

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

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

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

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

export default AboutPage;
```

### Adding the page to the site's navigation menu

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

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

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

The menu is defined in the render function:

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

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

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

And then we update the menu:

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

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

Adding pages to the Marketing Site


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

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

1. **Supabase**: Create a new Supabase project, and add the relevant environment variables to your project
2. **Link project with the CLI**: Link the Supabase project with your local CLI
3. **Remote Database**: Deploy the database schema and migrations to your Supabase project
4. **Environment Variables**: Ensure that your environment variables are set correctly
5. **Auth**: Enable the authentication providers you want to use from the Supabase Console
6. **SMTP**: Set up an SMTP server to send emails
7. **Payments**: Set up your Stripe or Lemon Squeezy accounts and add the relevant environment variables
8. **Deployment**: Finally, deploy your application to your hosting provider (Vercel, Firebase, Netlify, etc.): please follow the instructions provided by your hosting provider to deploy a Next.js application.

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

Deploying to Production


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

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

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

Unfortunately, you may need to resolve eventual conflicts.

### Any questions?

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

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

Updating to the latest version

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

Getting Started


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

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 experimental "app" directory introduced with Next.js 13, which is built on top of the new React Server Components. At the time of writing, it is not production ready: for as long as Vercel marks it as experimental, this kit will also be marked as experimental.

Since it's not production ready, we recommend you start with this kit only if you're comfortable with the risks of using an experimental technology, and have a long-term horizon for your project. Starting with this kit also means you won't need to have a painful migration later on, but at the same time, you may need to refactor some code in the beginning, and put up with some bugs.

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

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

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


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 will release a Prisma version in the future.

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

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

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

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

### 5) Fully and Strictly Typed with Typescript

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

### 6) Payload validation with Zod

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

### 7) E2E testing with Cypress

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

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

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

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

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

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

### 9) Multi-language by default using i18next

We configured the application to be translated by default thanks to the
`i18next` package.

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

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

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

### 10) Logging with Pino

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

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

### 11) SWR for data fetching and mutations

MakerKit uses Vercel's SWR for data fetching and mutations.


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

The technologies that make up a MakerKit application


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

### Requirements

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

- Node.js
- Git
- Docker

### Cloning the repository

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

```
git clone --depth=1 git@github.com:makerkit/next-supabase-saas-kit.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. Reinitialize your git repository
3. Adding the original Makerkit repository as "upstream" so we can fetch updates from the main repository:

Personally I re-initialize the Git repository, but it's not required.

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

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

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

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

### Installing the Node dependencies

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

```
npm i
```

While the application code is fully working, we now need to set up your 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)

### 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_KEY=<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',
    onboarding: `/onboarding`,
    appHome: '/tasks',
    settings: {
      profile: '/settings/profile',
      authentication: '/settings/profile/authentication',
      email: '/settings/profile/email',
      password: '/settings/profile/password',
    },
    api: {
      checkout: `/api/stripe/checkout`,
      billingPortal: `/api/stripe/portal`,
      organizations: {
        create: `/api/organizations`,
        current: `/api/organizations/[organization]/current`,
        transferOwnership: `/api/organizations/owner`,
        members: `/api/organizations/members`,
        member: `/api/organizations/members/[member]`,
      },
    },
  },
  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: '',
  },
  emailEtherealTestAccount: {
    email: process.env.ETHEREAL_EMAIL,
    password: process.env.ETHEREAL_PASSWORD,
  },
  environment: process.env.NEXT_PUBLIC_ENVIRONMENT,
  production: process.env.NODE_ENV === 'production',
  enableThemeSwitcher: true,
  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.

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

### Development Environment Variables

The development 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=

# TESTING EMAILS. MAKE AN ACCOUNT ON ETHEREAL AND ADD THE CREDENTIALS BELOW
ETHEREAL_EMAIL=
ETHEREAL_PASSWORD=

# SERCET KEY TO SIGN SECRETS. REPLACE THE BELOW WITH A RANDOM AND COMPLEX STRING. KEEPT IT SAFE.
SECRET_KEY=

```

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

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

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)
  - 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)`: the routes that are accessible only to logged-in users
- `auth`: the routes that are accessible only to logged-in users, but only if they are not already logged in

#### 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 `components/events`
3. Finally, we add the pages of the `event` domain to `pages/events`

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

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

  - app
    - __app
      - events
        - index.tsx
        - $event.tsx
```

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

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

#### Types

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

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

#### Custom Hooks

For example, let's write a custom hook that retrieves a list of "events" from a 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"
import EventModel from '~/lib/events/types/event-model.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/(app)/events/index.tsx`:

```tsx title="app/(app)/events/index.tsx"
import EventsListContainer from '~/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`, `organizations`, `memberships`, `subscriptions` and `organizations_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,
  onboarded bool not null
);
```

## Organizations

`Organizations` are groups of users.

If the name doesn't suit your domain, don't worry: you can always change the terminology using the localization files.

Below is what the `Organizations` schema looks like:

```sql
create table organizations (
  id bigint generated always as identity primary key,
  name text not null,
  logo_url text
);
```

## Memberships

To link an user to an organization we use another table named `memberships`.

A user is associated to this table when:
1. it is part of the organization
2. it is not yet part, but has been invited

Furthermore, in this table we store the `role` property which defines the role of the user for the organization.

Below is what the `Organizations` schema looks like:

```sql
create table memberships (
  id bigint generated always as identity primary key,
  user_id uuid references public.users,
  organization_id bigint not null references public.organizations,
  role int not null,
  invited_email text,
  code text,
  unique (user_id, organization_id)
);
```

### Invites

To create an invite to join an organization, we create a membership for the user with two properties `code` and `invite_email`: these two properties are going to become `null` once the invite gets accepted.

### User Roles

By default, MakerKit defines three roles: Owner (can be only one), Admin, and Member.

This enum is hierarchical and associated with a number:

```tsx
enum MembershipRole {
  Member = 0,
  Admin = 1,
  Owner = 2
}
```

An Admin can do anything a member can do, and an Owner can do anything an Admin can.

## 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 organizations_subscriptions (
  organization_id bigint not null references public.organizations (id) on delete cascade,
  subscription_id text unique references public.subscriptions (id) on delete set null,
  customer_id text not null unique,
  primary key (organization_id)
);
```

We store the `customer_id` property so that, when an organization 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 two Storage buckets: `logos` and `avatars`:

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

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

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

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

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

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

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

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

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

export default useCreateTaskMutation;
```

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 toaster from 'react-hot-toast';

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) {
        toaster.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;
```

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

### Retrieving data from the server

When we want to fetch data from the server, we can import a server Supabase
client and use it to fetch data.

We can add a Next.js route `route.ts` to fetch the data. For example, let's
create a route to fetch an organization by ID at `app/api/organizations/[organizationId]/route.ts`

```tsx
export async function GET(request: NextRequest) {
  const client = getSupabaseServerClient();

  const currentOrganizationId = Number(
    await parseOrganizationIdCookie(cookies())
  );

  try {
    const { data } = await getOrganizationById(client, organizationId);

    return NextResponse.json(data);
  } catch (error) {
    return throwInternalServerErrorException();
  }
}
```

When you want to ensure your data is rendered on the server, you should ensure you're loading the data using the `loader` function. Then, you can co-ordinate data re-fetching on the client when the data changes using `useSubmit` or `useFetcher`.

When the data is only fetched on the client, you can use `useSWR` to fetch the data and re-fetch the stale queries.

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

Fetching data from Supabase


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


Much of the MakerKit's codebase uses translations using the package `remix-i18next' (which builds on top of `react-i18next` and `i18next`):

- this package allows you to create multi-language apps effortlessly
- it also helps easily renaming the Makerkit's entities according to your preferences: for example, renaming "organizations" to another entity such as "team" or "workspace"
- in a way, it helps write cleaner HTML

To add or update the default strings, you must use the locale files at `public/locales/{lang}.json`. For example, all the locale files for the English language are placed under `public/locales/en`.

<Alert type='warn'>
  When adding new keys, you'll need to restart the MakerKit server (npm run
  dev) to see the changes.
</Alert>

The locales are split by functionality, page, or entity: as your application grows, you may not want to load every JSON file to reduce your bundle size.

For example, the translations for the authentication are placed in `auth.json,` while the ones used across every page are placed under `common.json.`

If you are unsure where to add some translations, simply add them to `common.json`.

<Alert type='info'>
  To simplify things, the MakerKit's starter uses all the available JSON files, and we recommend doing so until you have too many files.
</Alert>

### Adding new languages

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

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

The configuration will look like the below:

```js title="app/i18n/i18next.config.ts"
const i18Config = {
  fallbackLanguage: DEFAULT_LOCALE,
  supportedLanguages: [DEFAULT_LOCALE, 'es'],
  defaultNS: ['common', 'auth', 'organization', 'profile', 'subscription'],
  react: { useSuspense: false },
};
```

To add new locale files by default, add them to the `defaultNS` array.

#### Setting the default Locale

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

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

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

## Using the Language Switcher

The MakerKit kits come with a language switcher that allows users to switch between the available languages. This is not enabled by default, but you can easily add it anywhere in your application by importing the `LanguageSwitcherDropdown` component from `~/components/LanguageSwitcherDropdown`. 

It does not require any props, and it will automatically detect the available languages and display them in a dropdown.

If you want to customize the language switcher or use a different component, you can leverage the `useChangeLanguage` hook to change the language and store the selection as a cookie, which will then be used to set the default language.


Adding and updating locales in your Makerkit application


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

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

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

## Email Configuration

To add your service's configuration, fill the `email` object in your configuration file at `src/configuration.ts`:

```tsx
email: {
  host: '',
  port: 0,
  user: '',
  password: '',
  senderAddress: 'MakerKit Team <test@makerkit.dev>',
}
```

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

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

## Sending Emails

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

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

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

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

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

## Using react.email to render emails

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

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

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

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

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

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

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

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

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

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

## Using MJML to render emails (deprecated)

**If you're using a newer version of Makerkit, this section is deprecated.**.

Thanks to MJML, we can write emails using handy web components (or HTML tags).

In addition, using `react-mjml`, [we can use React components to compose our emails](https://github.com/wix-incubator/mjml-react). Wonderful, right?

Makerkit provides two MJML emails:

1. The email sent when inviting members
2. The email sent when an asynchronous payment

You can find these emails at `src/lib/emails`.

#### Using MJML with React

Let's assume we want to write a Welcome email using React and the `sendEmail` utility above.

```tsx title="src/lib/emails/welcome.ts"
function renderWelcomeEmail(props: {
  name: string;
  link: string;
}) {
  const title = `Hey, ${props.name}, Welcome!`;

  return render(
    <Mjml>
      <MjmlHead>
        <MjmlTitle>{title}</MjmlTitle>
        <MjmlPreview>{title}</MjmlPreview>
      </MjmlHead>

      <MjmlBody width={500}>
        <EmailNavbar />

        <MjmlSection fullWidth>
          <MjmlColumn>
            <MjmlText>Hi ${props.name}</MjmlText>

            <MjmlText>
              We're super glad to have you with us!
            </MjmlText>
          </MjmlColumn>
        </MjmlSection>

        <MjmlSection>
          <MjmlColumn>
            <CallToActionButton href={props.link}>
              Sign In
            </CallToActionButton>
          </MjmlColumn>
        </MjmlSection>

        <MjmlSection>
          <MjmlColumn>
            <MjmlText>Welcome aboard</MjmlText>
          </MjmlColumn>
        </MjmlSection>
      </MjmlBody>
    </Mjml>,
    { validationLevel: 'soft' }
  );
}
```

Now, let's write a function that renders the MJML email and sends it to our user:

```tsx
function sendTransactionalWelcomeEmail(props: {
  user: string;
  email: string;
}) {
  const { html, errors } = renderInviteEmail({
    link: `https://makerkit.dev/sign-in`,
    name: props.user,
  });

  if (errors.length) {
    throw new Error(
      `Found errors while rendering email: ${JSON.stringify(errors)}`
    );
  }

  return sendEmail({
    to: props.email,
    from: configuration.email.senderAddress,
    subject: `Welcome to Makerkit`,
    html,
  });
}
```

That's it! Learn more about [react-mjml](https://github.com/wix-incubator/mjml-react).

## Testing Emails

By default, when running in dev mode, the email sender function will use
[Ethereal](https://ethereal.email) as an email transport provider. This service allows us to test our emails for free.

To configure Ethereal, subscribe to the service and grab the credentials generated for you. Then, add them as environment variables:

```
ETHEREAL_EMAIL=
ETHEREAL_PASSWORD=
```

Alternatively, **Makerkit will generate these credentials for you**. Every time you send an email, the credentials are printed to the console so that you can grab them and inspect the emails sent: feel free to add these as your environment variables if you haven't added them yet. In this way, you will always reuse the same Ethereal account.


Sending emails with a Makerkit application


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

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

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

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

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

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

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

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

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

export const action: ActionFunction = async ({request}) => {
  try {
     // we can safely use data with the interface Body
    const data = await req.formData();
    const body = Object.fromEntries(data.entries());
    const bodyResult = await getBodySchema().parseAsync(body);
    const { displayName, email } = bodyResult.data;

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

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

```tsx
export const action: ActionFunction = async ({request}) => {
  const data = await req.formData();
  const body = Object.fromEntries(data.entries());
  const result = await getBodySchema().parseAsync(body);

  // we use result.success as a type guard
  // when false, we throw an exception
  if (!result.success) {
    return throwBadRequestException();
  }

  // TS correctly infers result.data now
  return sendInvite(result.data);
}
```

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


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

Validating the Remix API inputs with Zod and Typescript


The Makerkit Boilerplate uses `pino` as logging library. Pino is simple and
lightweight, and it's used across the API functions to log important
information that helps you debug your code.

Generally speaking, you will find that we log every function, especially for
asynchronous operations that could fail for a number of reasons: network
issues, API exceptions, and so on.

So, how to log your API functions effectively? Our recommendation is to log
**before executing an operation** and then log the **result of the
operation**, without leaking important data.

Furthermore, we want to log information such as:
- which user is performing the operation?
- which organization is the user part of?
- any other information that can help you understand and debug what is
happening.

Let's assume you're writing an API function to write to your database:

```tsx
function addIntegrationHandler() {
  return writeToDb(data);
}
```

Let's rewrite the above by adding logging to your function:

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

async function addIntegrationHandler(
  userId: string,
  organizationId: number,
  integrationId: number,
) {
  // this is the context that every log will print out
  const loggingContext = {
    integrationId,
    organizationId,
    userId,
  };

  // Here we log what we're doing
  logger.log(loggingContext, `Adding new integration to organization`);

  try {
    await writeToDb(data);

    // Here we log that the result of the operation
    // was successful
    logger.log(loggingContext, `Integration successfully added`);

    // return successful response
    return res.json({
      integrationId,
      success: true
    });
  } catch (e) {
    // Here we log that the operation failed
    logger.error(loggingContext, `Encountered an error while adding integration`);

    // Logging errors can be okay but
    // ensure not to leak important information!
    logger.debug(e);

    // return 500
    return res.status(500).json({
      integrationId,
      success: false
    });
  }
}
```

If you use the filter `withExceptionFilter`, it will automatically
log eventual exceptions thrown by the function, which makes the try/catch
block optional.

NB: If you're using Vercel, logs are not persisted by default! [Check out the
Vercel integrations](https://vercel.com/integrations#logging) for adding persisting logs to your projects.


Logging is a fundamental part for your SaaS to understand and monitor the behavior of your code at runtime. Let's learn how to add logging to your Makerkit application.

Logging


Enabling CORS is required if you want to allow serving HTTP request to
external clients.

For example, if you want to expose an API to some
consumers: JS libraries, headless clients, and so on.

The code to enable CORS in Remix is very simple. In fact, you can enable it using the following code:

```tsx
function withCors() {
  const headers = new Headers();

  headers.append('Access-Control-Allow-Origin', '*');

  headers.append(
    'Access-Control-Allow-Headers',
    'Origin, X-Requested-With, Content-Type, Accept, referer-path'
  );

  return headers;
}
```

Additionally, you need to handle `OPTIONS` requests appropriately.

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

export async function GET(request: NextRequest) {
  if (request.method === `OPTIONS`) {
    return new Response(null, {
      headers: {
        'Access-Control-Allow-Origin': '*',
        'Access-Control-Allow-Methods': 'GET, HEAD, POST, PUT, DELETE',
      },
    });
  }
}
```

In your Makerkit codebase, this function is already available in the
`~/core/middleware/with-cors.ts` file.

To enable CORS, you can simply call it in your handler. If it fails, it will
throw an exception with the appropriate HTTP status code.

```tsx
import withCors from '~/core/middleware/with-cors';

export async function GET(request: NextRequest) {
  const headers = withCors();

  if (request.method === `OPTIONS`) {
    return new Response(null, {
      headers,
    });
  }
}
```


Enable CORS


When storing sensitive data, such as API keys, you must ensure to encrypt your data in Database.

To use these utilities, you must provide an environment variable named `SECRET_KEY`. This should be provided safely using your CI since it's a secret key.

MakerKit provides some utilities to encrypt and decrypt your data. 

```tsx
import { encrypt, decrypt } from '~/core/generic/crypto';

// storing secrets
function storeApiKey(key: string) {
  const encryptedKey = encrypt(key);

  return storeKeyInDb(encryptedKey);
}

// retrieving secrets
function getApiKey(id: string) {
  const encryptedKey = await getApiKeyFromDb(id);

  return decrypt(encryptedKey);
}
```


When storing sensitive data, such as API keys, you must ensure to encrypt your data in Supabase. Here is how we can encrypt and decrypt it.

Encrypting Secrets


The MakerKit Starter has three default roles:

```tsx
enum MembershipRole {
  Member = 0,
  Admin = 1,
  Owner = 2,
}

export default MembershipRole;
```

We use an `enum`, but you can convert this to an object if you need more granular permissions.

The permissions are hierarchical, which means that if we had a role with a lower level (`Readonly`), we would add it before `Member`:

```tsx
export enum MembershipRole {
  Readonly = 0,
  Member = 1,
  Admin = 2,
  Owner = 3,
}
```

When writing permissions between users, we can check if the user performing the action has a greater role than the target user.

You can extend the role above easily by adding your own, for example:

```tsx
export enum MembershipRole {
  Readonly = 0,
  AccountManager = 1,
  Owner = 2,
}
```

Afterward, remember to add the name and descriptions of these roles in the translations file `common.json`:

```json
"roles": {
  "owner": {
    "label": "Owner",
    "description": "Can change any setting, invite new members and manage billing"
  },
  "accountmanager": {
    "label": "Account Manager",
    "description": "Can change some settings, invite members, perform disruptive actions"
  },
  "readonly": {
    "label": "Readonly",
    "description": "Can only read information"
  }
}
```

Learn more about [using user roles in your permissions system](/docs/permissions).

The role is stored in the database as a column in the `memberships` tabel.

Extend User Roles

Learn how to configure Stripe, and start collecting payments from your customers

Payments


MakerKit offers support for subscriptions and payments using [Stripe](https://stripe.com).

To get started with [Stripe Checkout](https://stripe.com/docs/payments/checkout), you will need to create an account using the [Stripe website](https://stripe.com).

If you want, you can get your business details sorted right away. If you
want to continue with the set-up, you can skip it for now and get back to it later.

## Configuration

Visit the [Stripe Checkout Tutorial](https://stripe.com/docs/checkout/quickstart?client=next) where we can copy the
configuration for our development environment.

If you click on the file `.env` of the code editor on the right-hand side,
you will be able to see the variables needed:

- `STRIPE_SECRET_KEY`
- `STRIPE_WEBHOOK_SECRET`

Copy these values to your local `.env` file.

<Alert type="warn">
  Make sure to keep your <code>.env</code> file private. It should not be committed to your repository. These environment variables should be added using your hosting provider's dashboard.
</Alert>

## Creating your SaaS plans in Stripe

Stripe allows us to create our plans using the UI in the Stripe Dashboard.

To get started, let's add a couple of testing plans that you can use while
developing your application.

Visit [the Stripe Dashboard](https://dashboard.stripe.com/test/products/prod_KpXDAnvbPkXkgp) and add a new product (for example, a one-time purchase or a SaaS subscription).

You can add multiple "prices": for example, if you're defining a
subscription, you could use two plans, "Basic" and "Pro".

## Creating a Webhook endpoint

Stripe allows us to create a webhook endpoint to receive events. To tell Stripe
where to send the events, we need to create a webhook endpoint that points to our application.

After creating a Stripe endpoint, we need to add the "Signing Secret" key in Stripe to the production environment variables. To do so, use the environment variables editor in your hosting provider's dashboard.

<Image src='/assets/images/docs/stripe-webhook-config.webp' width="1670" height="368" />

### Webhook API Endpoint

The API endpoint needs to point to your application's Stripe webhook: the path is `/app/api/stripe/webhook`. For example, if your application is hosted at `https://myapp.com`, the webhook endpoint would be `https://myapp.com/resources/stripe/webhook`.

### Events

The events you want to receive from Stripe are:
- `checkout.session.completed`
- `customer.subscription.updated`
- `customer.subscription.deleted`

If you have any other events you want to receive, you need to add them here.

### Signing Secret

The signing secret is the value of the `STRIPE_WEBHOOK_SECRET` environment variable. 

<Alert type='warn'>
  If you do not follow these steps, you will not be able to receive events from Stripe. This will prevent you from being able to update the subscription status of your users. Please make sure to follow these steps.
</Alert>

### Pricing Table Configuration

Below is the default Pricing Table configuration of the kits. The `PricingTable` component will automatically generate the pricing table based on the Stripe plans you have created and added to the configuration (see below).

We have 3 products (Basic, Pro and Premium), each with 2 plans (monthly, yearly). By default, the Pro plan is set as the recommended plan.

Of course, the below is simply an example. You will need to customize this according to your application's plans.

```tsx
stripe: {
  products: [
    {
      name: 'Basic',
      description: 'Description of your Basic plan',
      badge: `Up to 20 users`,
      features: [
        'Basic Reporting',
        'Up to 20 users',
        '1GB for each user',
        'Chat Support',
      ],
      plans: [
        {
          name: 'Monthly',
          price: '$9',
          stripePriceId: 'price_1LfXGaI1i3VnbZTq7l3VgZNa',
          trialPeriodDays: 0,
        },
        {
          name: 'Yearly',
          price: '$90',
          stripePriceId: 'basic-plan-yr',
          trialPeriodDays: 0,
        },
      ],
    },
    {
      name: 'Pro',
      badge: `Most Popular`,
      recommended: true,
      description: 'Description of your Pro plan',
      features: [
        'Advanced Reporting',
        'Up to 50 users',
        '5GB for each user',
        'Chat and Phone Support',
      ],
      plans: [
        {
          name: 'Monthly',
          price: '$29',
          stripePriceId: 'pro-plan-mth',
          trialPeriodDays: 0,
        },
        {
          name: 'Yearly',
          price: '$200',
          stripePriceId: 'pro-plan-yr',
          trialPeriodDays: 0,
        },
      ],
    },
    {
      name: 'Premium',
      description: 'Description of your Premium plan',
      badge: ``,
      features: [
        'Advanced Reporting',
        'Unlimited users',
        '50GB for each user',
        'Account Manager',
      ],
      plans: [
        {
          name: '',
          price: 'Contact us',
          stripePriceId: '',
          trialPeriodDays: 0,
          label: `Contact us`,
          href: `/contact`,
        },
      ],
    },
  ],
}
```

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

### Additional Configuration

You can also configure the following properties on each `product`:

- `recommended` - set to `true` if you want to highlight a plan as recommended
- `badge` - set to a string if you want to display a badge next to the plan name

You can also configure the following properties on each `plan`:

- `price` - any string that you want to display as the price (e.g. `$9.99` or `Free`)
- `label` - set to a custom string if you want to display a button label
- `href` - set to a custom URL if you want to link to a custom page (for example, a contact page)
- `trialPeriodDays` - set to the number of days you want to offer a free trial for

### Install The Stripe CLI

The Stripe CLI is required to help us test our integration.
Please [follow this guide to install the CLI on your system](https://stripe.com/docs/stripe-cli).

The default recommendation is to use Docker, which Makerkit uses by default.

### Connect CLI with your account

To connect the Stripe CLI with your account, run the following command:

```
npm run stripe:listen
```

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

The CLI should prompt you to connect your account. If you signed in already, visit the link and follow the instructions.

If you followed the instructions, get back to the terminal, and then copy
the webhook secret to your `STRIPE_WEBHOOK_SECRET` environment variables in the
`.env` file.

Restart the next.js server to apply the changes.

## Billing Portal

MakerKit uses the [Stripe Billing Portal](https://dashboard.stripe.com/test/settings/billing/portal) to let your users manage their invoices and subscriptions.

The portal becomes accessible once the organization subscribes to a plan, which creates a `customerId` property, making it possible for the organization to access the portal.

### Enabling the Billing Portal in test mode

Please visit the [Stripe Billing Page](https://dashboard.stripe.com/test/settings/billing/portal) to enable the Billing Portal.

Choose the settings that best apply to your product and save your changes.

The only required fields to get started are `Terms of Service` and
`Privacy` URLs. You can add any URL at this stage. **However, remember to update these pages when you go live**.

For a technical deep-dive, we recommend reading our blog post where we [build the integration between Stripe and Next.js from scratch](/blog/tutorials/guide-nextjs-stripe). Because the result of the blog post is a simplified version of the Makerkit's implementation, it can be beneficial for understanding its code.


Learn how to configure Stripe with your MakerKit application

Set up Stripe Payments for Next.js and Supabase SaaS applications


Makerkit handles five webhooks from Stripe and stores "just enough" data into the organization's entity to function correctly.

The Stripe's webhooks topics are defined here at `app/core/stripe/stripe-webhooks.enum.ts`:

```tsx
export enum StripeWebhooks {
  Completed = 'checkout.session.completed',
  SubscriptionDeleted = 'customer.subscription.deleted',
  SubscriptionUpdated = 'customer.subscription.updated',
}
```

To handle webhooks, we created an API route at `app/api/stripe/webhook.ts`.

This route is responsible for:

1. Validating that the webhook is coming from Stripe
2. Routing the webhook to its handler

## Validating Stripe's Webhooks

To validate the webhook, we do the following:
1. get the header 'stripe-signature'
2. create a Stripe instance
3. get the raw body
4. call `constructEvent` to validate and build an event object sent by Stripe. When this fails, it will throw an error

```tsx
const signature = req.headers['stripe-signature'];

// verify signature header is not missing
if (!signature) {
  return throwBadRequestException(res);
}

const rawBody = await getRawBody(req);
const stripe = await getStripeInstance();

const event = stripe.webhooks.constructEvent(
  rawBody,
  signature,
  webhookSecretKey
);
```

## Handling Stripe's Webhooks

After validating the webhook, we can now handle the webhook type relative to its topic:

```tsx
switch (event.type) {
  case StripeWebhooks.Completed: {
    // handle completed
  }

  case StripeWebhooks.AsyncPaymentSuccess: {
     // handle async payment success
  }
}
```

As described above, we handle 5 events:

1. `Completed`: the checkout session was completed (but payment may not have arrived yet if it's asynchronous)
2. `SubscriptionDeleted`: the subscription was deleted by the customer
3. `SubscriptionUpdated`: the subscription was updated by the customer

### Checkout Completed

When a user completes the checkout session, we create the `subscription` object on the currently connected user's organization.

<Alert type='warn'>
  The payment may not have yet succeeded when it's "asynchronous", so the payment's status may be "AwaitingPayment" rather than "Paid". You may want to consider the subscription active only when the subscription's status is "active" or "trialing".
</Alert>

The subscription's object has the following interface:

```tsx
export interface OrganizationSubscription {
  id: string;
  priceId: string;

  status: Stripe.Subscription.Status;
  currency: string | null;
  cancelAtPeriodEnd: boolean;

  interval: string | null;
  intervalCount: number | null;

  createdAt: UnixTimestamp;
  periodStartsAt: UnixTimestamp;
  periodEndsAt: UnixTimestamp;
  trialStartsAt: UnixTimestamp | null;
  trialEndsAt: UnixTimestamp | null;
}
```

This interface is added to the `Organization` object.

### Subscription Updated

When a subscription is updated, we rebuild the subscription object and update it in the organization's Database row.

### Subscription Deleted

When a subscription is deleted, we simply remove it from the organization entity.

## Adding additional webhooks

If you want to add additional webhooks, you can do so by adding a new case in the switch statement.

For example, if you want to handle the `customer.subscription.trial_will_end` event, you can do so by adding the following case:

```tsx
case 'customer.subscription.trial_will_end': {
  // handle trial will end
}
```

## Adding additional data to the subscription object

If you want to add additional data to the subscription object, you can do so by adding the data to the `OrganizationSubscription` interface.

For example, if you want to add the `quantity` property to the subscription object, you can do so by adding the following property to the interface:

```tsx
export interface OrganizationSubscription {
  // ...
  quantity: number | null;
}
```

Then you will update the `subscription` table in the PostgreSQL database to add the `quantity` column.

Finally, you can add the data to the subscription object using the `subscriptionMapper` function:

```tsx
function subscriptionMapper(
  subscription: Stripe.Subscription
): SubscriptionRow {
  const lineItem = subscription.items.data[0];
  const price = lineItem.price;
  const priceId = price.id;
  const interval = price?.recurring?.interval ?? null;
  const intervalCount = price?.recurring?.interval_count ?? null;

  const row: Partial<SubscriptionRow> = {
    // custom props
    quantity: lineItem.quantity,

    // default props
    price_id: priceId,
    currency: subscription.currency,
    status: subscription.status ?? 'incomplete',
    interval,
    interval_count: intervalCount,
    cancel_at_period_end: subscription.cancel_at_period_end ?? false,
    created_at: subscription.created ? toISO(subscription.created) : undefined,
    period_starts_at: subscription.current_period_start
      ? toISO(subscription.current_period_start)
      : undefined,
    period_ends_at: subscription.current_period_end
      ? toISO(subscription.current_period_end)
      : undefined,
  };

  if (subscription.trial_start) {
    row.trial_starts_at = toISO(subscription.trial_start);
  }

  if (subscription.trial_end) {
    row.trial_ends_at = toISO(subscription.trial_end);
  }

  return row as SubscriptionRow;
}
```

Learn how MakerKit handles Stripe Webhooks in your application

How Makerkit handles Stripe Webhooks


While Makerkit uses subscriptions by default, you can offer your customers one-time payments.

Fortunately, Stripe Checkout makes it insanely easy. Let's see how to update  Makerkit's codebase to enable Stripe one-off payments for your product.

1) First, when choosing your Stripe Price's billing type, select `One Time.` [Learn more about creating Prices with Stripe](https://support.stripe.com/questions/how-to-create-products-and-prices).

2) Secondly, we need to change the payment mode in Makerkit's codebase. To do so, we will update the `createStripeCheckout` function defined at `~/lib/stripe/create-checkout.ts`.

If you open the file, you'll find the line below:

```tsx
const mode: Stripe.Checkout.SessionCreateParams.Mode = 'subscription';

// some code here...

return stripe.checkout.sessions.create({
  mode,
  // more code here...
});
```

To enable one-time payments, we will replace the `mode` constant from `subscription` to `payment`:

```tsx
const mode: Stripe.Checkout.SessionCreateParams.Mode = 'payment';

// some code here...

return stripe.checkout.sessions.create({
  mode,
  // more code here...
});
```

And that's it! Stripe will not charge our users recurringly but will simply charge them once.

<Alert type='warn'>
As the UI is set up for recurring subscriptions, you may want to tweak the Subscription Page UI to reflect that charges are not recurring and that the product has been successfully purchased.
</Alert>

## Handling the Payment Method dynamically

The above works great if you only offer one plan. However, let's assume you have multiple prices and want to dynamically update the payment mode based on the selected price.

In this case, let's do the following:
1. Extend the plan information in the application configuration
2. Select the appropriate method when creating the checkout by retrieving the plan's model

If you open your application's configuration, you will notice that plans have the following interface:

```tsx title="src/configuration.ts"
{
  name: 'Basic',
  description: 'Unlimited applications and 2-hour onboarding session',
  price: '$249/year',
  stripePriceId: 'price_***********',
}
```

Now, we can extend it with the payment mode, which would be `subscription` or `payment`:

```tsx
{
  name: 'Basic',
  description: 'Unlimited applications and 2-hour onboarding session',
  price: '$249 one off!',
  stripePriceId: 'price_***********',
  mode: 'payment'
}
```

Now, let's reopen the file `create-checkout.ts` file and find the payment mode of the selected price ID:

```tsx
const price = configuration.plans.find(item => {
  return item.stripePriceId === params.priceId;
});

if (!price) {
  throw new Error(`Price with ID ${params.priceId} not found in config`);
}

const mode: Stripe.Checkout.SessionCreateParams.Mode = price.mode;

// some code here...

return stripe.checkout.sessions.create({
  mode,
  // more code here...
});
```

🎉 Now it looks better and works for multiple plans based on their payment mode!


Learn how to switch from Stripe Subscriptions to One-Time Payments in your Makerkit application

Enabling One-Time Payments with Stripe


If you prefer using Lemon Squeezy instead of Stripe with your Makerkit kit, we provide a different branch from the main repository that you can use.

The branch is called `main-ls`. If you want to use Lemon Squeezy, you can clone the repository and checkout the `main-ls` branch.

NB: the integration is in beta, and I am working on improving it.

## Setting up Lemon Squeezy

### Step 1: Create a Lemon Squeezy account

First, you need to create a Lemon Squeezy account. You can do so by visiting [https://lemonsqueezy.io](https://lemonsqueezy.com).

Get your store setup (start in Test mode, so you don't need to wait for activation).

### Step 2: Create a Product/Variant in Lemon Squeezy

You can see this guide for [setting up SaaS subscription plans in Lemon Squeezy](https://docs.lemonsqueezy.com/guides/tutorials/saas-subscription-plans).

If you want, set up a monthly/annual plan for your product, or just a single plan.

<Image src="/assets/images/posts/lemon-squeezy-plans.webp" width={"1286"} height={"816"} />

To replicate the basic Makerkit subscription plans, you can create a plan for each of the following: Basic, Pro and Premium plans.

To get started quickly, you can also set up a single plan for your product.

### Step 3: Create a Lemon Squeezy API key

Now, we need to setup an API Key. Go to your Lemon Squeezy settings page and click on the [API Keys tab](https://app.lemonsqueezy.com/products).

Click on the "Create API Key" button and give it a **very specific name**, so you won't confuse it with your production keys. Copy the API key and ensure to store it. We will be adding this to your Makerkit's local environment variables file.

<Image src="/assets/images/posts/lemon-squeezy-api-key-name.webp" width={"946"} height={"614"} />

Depending on which kit you're using, you will add this key to either `.env.local` (Next.js) or `.env` (Remix). This key is not supposed to be committed to your repository, so we add them safely to our local files.

Additionally, we need to add the `LEMON_SQUEEZY_STORE_ID` to the local environment variables file, and a secret string `LEMONS_SQUEEZY_SIGNATURE_SECRET` that we use to verify the webhook signature.

Update them in your local environment variables file:

```
LEMON_SQUEEZY_API_KEY=<YOUR_KEY>
LEMON_SQUEEZY_STORE_ID=<YOUR_STORE_ID>
LEMONS_SQUEEZY_SIGNATURE_SECRET=<a random string>
```

#### Find your Lemon Squeezy Store ID

To find your Lemon Squeezy Store ID, visit your `Stores` page in the Lemon Squeezy dashboard.

You can do so by visiting the following URL: [https://app.lemonsqueezy.com/settings/stores](https://app.lemonsqueezy.com/settings/stores).

The ID is the number next to the store name.

Proceed by copying the Store ID into the `LEMON_SQUEEZY_STORE_ID` environment variable.

## Step 4: Configure Lemon Squeezy plans in the Makerkit configuration

Now, we need to configure the Lemon Squeezy plans in the Makerkit configuration, and enter the correct plan IDs.

To do so, open the `~/configuration.ts` file and edit the `stripe` object.

We can convert this to something more abstract, such as `subscriptions`, and add the relevant Lemon Squeezy product and variant IDs.

```ts title="src/configuration.ts"
{
  subscriptions: {
    products: [
      {
        name: 'Basic',
        description: 'Description of your Basic plan',
        badge: `Up to 20 users`,
        productId: 1, // <-- Lemon Squeezy product ID
        features: [
          'Basic Reporting',
          'Up to 20 users',
          '1GB for each user',
          'Chat Support',
        ],
        plans: [
          {
            name: 'Monthly',
            price: '$9',
            variantId: 1, // <-- Lemon Squeezy variant ID
          },
          {
            name: 'Yearly',
            price: '$90',
            variantId: 2, // <-- Lemon Squeezy variant ID
          },
        ],
      }
    ]
  }
}
```

**Note**: The `variantId` is the ID of the plan in Lemon Squeezy. The `productId` is the ID of the product.

#### Find your Lemon Squeezy product and variant IDs

To find your Lemon Squeezy product and variant IDs, we need to use the API.

Submit a `GET` request to the following endpoint using `curl` or Postman and insert your API key:

```
GET https://api.lemonsqueezy.com/v1/products
Accept: application/vnd.api+json
Authorization: Bearer {api_key}
Content-Type: application/vnd.api+json
```

The JSON response will return a list of products and variants. You can find the IDs in the response. Please add the IDs to the `configuration.ts` file.

### Step 4: Creating the Webhook In Lemon Squeezy

We need to create a Webhook from the Lemon Squeezy Dashboard so that we can receive the events to our webhook handler.

You will be prompted for the following:

- URL: point it to the ngrok URL (see below). Ensure you point it to the `/api/ls/webhook` endpoint.
- Secret: the secret `LEMONS_SQUEEZY_SIGNATURE_SECRET` that you have set in the `.env` file
- Events: select the events that you want to receive. In our case, we want to receive the `subscription_created` and `subscription_updated` events.

<Image src="/assets/images/posts/lemon-squeezy-webhook-setup.webp" width={"1118"} height={"1666"} />

#### Testing Locally

To test the webhook handler locally, we can use the [ngrok](https://ngrok.com/) tool.

We add the following command to the `package.json` file:

```
"ngrok": "npx ngrok http 3000"
```

And you can run it with:

```bash
npm run ngrok
```

You can also use other alternatives, such as Localtunnel or Cloudflare Tunnel.

### Step 5: Go to production

Once you're ready to go to production, you can switch your Lemon Squeezy store to production mode.

Additionally, remember to set up the webhook in production mode as well, pointing to your production URL.

Lear how to migrate your MakerKit project to Lemon Squeezy

Use Lemon Squeezy with MakerKit

Learn how to run and update the Cypress E2E tests

Testing


The Makerkit SaaS boilerplate comes with a set of predefined tests with the following goals:

1. Verify that the boilerplate application works well
2. Provide instructions for building your own tests

As your application grows, the tests will inevitably need to be updated and
maintained. We hope that our tests will be simple to understand and to
change when you will need them.

## Running the Next.js development server

First, we have to run the following command to run Next.js with a testing
environment (i.e. using `.env.test`):

```
npm run dev:test
```

This command will start a Next.js dev server at http://localhost:3000, so
it's important to make sure you have no other Next.js server running at the
same port.

Additionally, we have to start the **Supabase local instance**:

```
npm run supabase:start
```

## Running Cypress in development mode

While you build your tests, it can be handy to use a windowed version of the
Cypress testing suite, so that you can easily retry the tests without having
to re-run the while tests suite.

To do that, run the following command:

```
npm run cypress
```

## Running All Cypress tests

Whenever you want to run all your tests at once, you can use the following commands:

```
npm run cypress:headless
```

This will run all the tests and exit.

## Running Cypress in CI mode

Whenever you want to run all your tests in a CI
environment, you can use the following commands:

```
npm test
```

The command above will:

1. Start the Supabase local instance
2. Start the Next.js environment
3. Run the tests in headless mode
4. Exit and close all the processes

As you may have noticed, this is the command to run in your CI environment.

## Testing Stripe

Testing Stripe requires one more process to start, i.e. the official Stripe
emulator.

The command below **will require Docker installed**, which is why you can
choose to disable it by setting the environment variable `ENABLE_STRIPE_TESTING`
to `false` from the `.env.test` environment file:

```bash title=".env.test"
ENABLE_STRIPE_TESTING=false
```

If instead, you want to test Stripe Checkout as well, run the command below:

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

As we've mentioned, this will require Docker running. Of course, we think
it's worth it.


Learn how to run Cypress E2E tests for your Makerkit application

Running Cypress Tests with Supabase and Next.js


To run your tests in any CI, we recommend you simply run the following command:

```
npm test
```

This command takes care of running all the required services, importing the test data, executing the tests and then exiting.

### The Makerkit testing pipeline

As mentioned in the previous section, testing a Makerkit requires a few services to be up and running:

- the Remix server
- the Supabase environment
- optionally, the Stripe Mock server

While executing these tests in your CI, this can get cumbersome. Therefore, we provided a single script to execute all your tests in one simple command: you can find the script at `scripts/test.sh`, which will contain the following content:

```
set -e

npm run dev:test & npm run stripe:mock-server &
npm run cypress:headless
sh scripts/kill-ports.sh
```

Let's explain it, so you can add your own modifications to it.

The first command will run (in parallel and in the background) the Remix server and the Stripe mock server:

```
npm run dev:test & npm run stripe:mock-server &
```

Afterward, we execute the Cypress tests in headless mode:

```
npm run cypress:headless
```

Finally, we clean up all the ports that may have remained open after executing the script:

```
sh scripts/kill-ports.sh
```

If you update your ports, remember to change them also in `scripts/kill-ports.sh`.

### Running the Tests in CI mode

Finally, the tests can be executed with the command `npm test`.

This command **will automatically run the Supabase docker instance** and the `test.sh` script, and is defined as:

When finished, the instance will exit.

Learn how to test your Makerkit in your CI

CI Tests

Learn how to prepare your application for shipping to production

Going to Production


Before going to production, it's essential to follow certain precautions to avoid failures.

## 1) Environment Variables

First, we must safely inject the correct environment variables into their
relative environment. MakerKit has predefined templates that allow you to understand where each variable should be added.

Before publishing your SaaS, or if you are making a production release after
a change and this included an environment variable; ensure your CI provider is
up to date with the correct variable in the right environments.

Since the `.env` file will not be committed to your repository, you will
need to add the environment variables beforehand.

## 2) Supabase Postgres Row Level Security (RLS) Policies

If you are using Supabase, you will need to ensure that your RLS policies
are set up correctly, and that the changes are propagated to the production
database.

## 3) Sync your database schema with your remote Supabase database

If you are using Supabase, you will need to ensure that your database schema is in sync with your remote Supabase database. 

You can do this using the Supabase CLI: for more information, please refer to the [Supabase CLI documentation](https://supabase.com/docs/reference/cli/supabase-db-push).

More specifically, you need to run the following command:

```bash
supabase db push
```

You may need to link your Supabase project to your local Supabase CLI instance first.

After running this command, navigate to your Supabase project and check that the database schema is in sync with your local database schema.

## 4) Enable your Stripe account Billing Status

Remember to complete your Stripe account's information and enable billing and to not forget it in `Testing Mode`.

Additionally, you will need to add your Stripe API keys to the environment variables to process payments. Ensure you have added the correct keys to the correct environment and that have selected all the required events to your webhook.

Please follow the [Stripe configuration guide](/docs/remix-supabase/stripe-configuration) to configure your Stripe account.

## 5) Add your SMPT service credentials

You will need to add your SMTP service credentials to the environment variables to send emails. This is required for sending emails to users when they are invited to an organization.

To set the credentials, use the global configuration file `configuration.ts`.

## 6) Enable Google Analytics (Optional)

Understand how visitors find your website early on.

## 7) Enable Sentry (Optional)

With 4000 events for free per month, we recommend that you use [Sentry.io](https://sentry.io) for
ensuring you can catch, analyze and fix any runtime errors in your application that your users will encounter.


Checklist to ship a MakerKit application to Production

/*@jsxRuntime automatic @jsxImportSource react*/
const {Fragment: _Fragment, jsx: _jsx, jsxs: _jsxs} = arguments[0];
function _createMdxContent(props) {
  const _components = Object.assign({
    p: "p",
    ol: "ol",
    li: "li",
    strong: "strong",
    div: "div",
    pre: "pre",
    code: "code",
    span: "span"
  }, props.components);
  return _jsxs(_Fragment, {
    children: [_jsx(_components.p, {
      children: "The starter project comes with two different environment variables files:"
    }), "\n", _jsxs(_components.ol, {
      children: ["\n", _jsxs(_components.li, {
        children: [_jsx(_components.strong, {
          children: ".env"
        }), ": the main environment file"]
      }), "\n", _jsxs(_components.li, {
        children: [_jsx(_components.strong, {
          children: ".env.development"
        }), ": the development environment file (used when running the project locally in development mode)"]
      }), "\n", _jsxs(_components.li, {
        children: [_jsx(_components.strong, {
          children: ".env.production"
        }), ": the production environment file (used when deploying or running the build command)"]
      }), "\n", _jsxs(_components.li, {
        children: [_jsx(_components.strong, {
          children: ".env.local"
        }), ": this environment file is loaded when running the project locally. It won't be committed to Git. Useful for adding secrets that you don't want to commit to Git."]
      }), "\n", _jsxs(_components.li, {
        children: [_jsx(_components.strong, {
          children: ".env.test"
        }), ": this environment file is loaded when running the Cypress\nE2E tests. You would rarely need to use this."]
      }), "\n"]
    }), "\n", _jsx(_components.p, {
      children: "The default environment variables for the production environment are:"
    }), "\n", _jsx(_components.div, {
      "data-rehype-pretty-code-fragment": "",
      children: _jsx(_components.pre, {
        style: {
          backgroundColor: "#24292e"
        },
        tabIndex: "0",
        "data-language": "bash",
        "data-theme": "default",
        children: _jsxs(_components.code, {
          "data-language": "bash",
          "data-theme": "default",
          children: [_jsxs(_components.span, {
            className: "line",
            children: [_jsx(_components.span, {
              style: {
                color: "#E1E4E8"
              },
              children: "NEXT_PUBLIC_SITE_URL"
            }), _jsx(_components.span, {
              style: {
                color: "#F97583"
              },
              children: "="
            })]
          }), "\n", _jsxs(_components.span, {
            className: "line",
            children: [_jsx(_components.span, {
              style: {
                color: "#E1E4E8"
              },
              children: "ENVIRONMENT"
            }), _jsx(_components.span, {
              style: {
                color: "#F97583"
              },
              children: "="
            }), _jsx(_components.span, {
              style: {
                color: "#9ECBFF"
              },
              children: "production"
            })]
          }), "\n", _jsx(_components.span, {
            className: "line",
            children: " "
          }), "\n", _jsx(_components.span, {
            className: "line",
            children: _jsx(_components.span, {
              style: {
                color: "#6A737D"
              },
              children: "# SUPABASE"
            })
          }), "\n", _jsxs(_components.span, {
            className: "line",
            children: [_jsx(_components.span, {
              style: {
                color: "#E1E4E8"
              },
              children: "NEXT_PUBLIC_SUPABASE_URL"
            }), _jsx(_components.span, {
              style: {
                color: "#F97583"
              },
              children: "="
            })]
          }), "\n", _jsxs(_components.span, {
            className: "line",
            children: [_jsx(_components.span, {
              style: {
                color: "#E1E4E8"
              },
              children: "NEXT_PUBLIC_SUPABASE_ANON_KEY"
            }), _jsx(_components.span, {
              style: {
                color: "#F97583"
              },
              children: "="
            })]
          }), "\n", _jsxs(_components.span, {
            className: "line",
            children: [_jsx(_components.span, {
              style: {
                color: "#E1E4E8"
              },
              children: "NEXT_PUBLIC_REQUIRE_EMAIL_CONFIRMATION"
            }), _jsx(_components.span, {
              style: {
                color: "#F97583"
              },
              children: "="
            }), _jsx(_components.span, {
              style: {
                color: "#79B8FF"
              },
              children: "true"
            })]
          }), "\n", _jsx(_components.span, {
            className: "line",
            children: " "
          }), "\n", _jsx(_components.span, {
            className: "line",
            children: _jsx(_components.span, {
              style: {
                color: "#6A737D"
              },
              children: "# SERCET KEY TO SIGN SECRETS. REPLACE THE BELOW WITH A RANDOM AND COMPLEX STRING. KEEPT IT SAFE."
            })
          }), "\n", _jsxs(_components.span, {
            className: "line",
            children: [_jsx(_components.span, {
              style: {
                color: "#E1E4E8"
              },
              children: "SECRET_KEY"
            }), _jsx(_components.span, {
              style: {
                color: "#F97583"
              },
              children: "="
            })]
          }), "\n", _jsx(_components.span, {
            className: "line",
            children: " "
          }), "\n", _jsx(_components.span, {
            className: "line",
            children: _jsx(_components.span, {
              style: {
                color: "#6A737D"
              },
              children: "# STRIPE"
            })
          }), "\n", _jsxs(_components.span, {
            className: "line",
            children: [_jsx(_components.span, {
              style: {
                color: "#E1E4E8"
              },
              children: "STRIPE_WEBHOOK_SECRET"
            }), _jsx(_components.span, {
              style: {
                color: "#F97583"
              },
              children: "="
            })]
          }), "\n", _jsxs(_components.span, {
            className: "line",
            children: [_jsx(_components.span, {
              style: {
                color: "#E1E4E8"
              },
              children: "STRIPE_SECRET_KEY"
            }), _jsx(_components.span, {
              style: {
                color: "#F97583"
              },
              children: "="
            })]
          })]
        })
      })
    })]
  });
}
function MDXContent(props = {}) {
  const {wrapper: MDXLayout} = props.components || ({});
  return MDXLayout ? _jsx(MDXLayout, Object.assign({}, props, {
    children: _jsx(_createMdxContent, props)
  })) : _createMdxContent(props);
}
return {
  default: MDXContent
};


SERCET KEY TO SIGN SECRETS. REPLACE THE BELOW WITH A RANDOM AND COMPLEX STRING. KEEPT IT SAFE.