Let's get started with the Next.js Supabase Turbo SaaS Starter kit

Installation


# Next.js Supabase SaaS Kit Documentation

Welcome to the latest version of the Next.js Supabase SaaS Kit! This starter kit is designed to help you build robust SaaS applications using the powerful combination of Next.js and Supabase. Whether you're a beginner or an experienced developer, this documentation will guide you through the setup, configuration, and deployment of your SaaS application.

## What's New? 🎉

Compared to previous versions, this kit includes:

- **More Functionality:** Enhanced features to meet modern SaaS requirements.
- **Organized Code:** A cleaner, more maintainable codebase.
- **Modern Dependencies:** Up-to-date libraries and tools.

## Features

### Authentication

- **Sign Up, Sign In, Sign Out:** Easy and secure user authentication.
- **Forgot Password:** Simple password recovery process.

### Multi-Factor Authentication (MFA)

- **Enable MFA:** Add an extra layer of security to your account.

### Account Management

- **Personal Accounts:** Users have their own personal accounts in addition to organization accounts.
- **Organization Accounts:** Users can create and join organizations.
- **Organization Roles:** Assign different roles to users within organizations.
- **Organization Invitations:** Invite others to join your organization.

### Billing

- **Personal Account Billing:** Manage billing information for personal accounts.
- **Organization Billing:** Handle billing for organization accounts.
- **Subscriptions:** Support for various subscription plans, including flat, tiered, and per-seat models.
- **Multiple Billing Providers:** Out-of-the-box support for Stripe, Lemon Squeezy, and (soon) Paddle.

### Content Management Systems (CMS)

- **Multiple CMS Support:** Integration with Keystatic and WordPress.

### Monitoring

- **Monitoring Tools:** Built-in support for Sentry and Baselime.

## A Modular, Extensible, and Modern SaaS Starter Kit

### Modular Structure

The biggest change in this kit is its modular structure, which allows for:

- **🧩 Easy Feature Integration:** Plug new features into the kit with minimal changes.
- **🛠️ Simplified Maintenance:** Keep the codebase clean and maintainable.
- **🎯 Core Feature Separation:** Distinguish between core features and custom features.
- **🌟 Additional Modules:** Easily add modules like billing, CMS, monitoring, logger, mailer, and more.

## Scope of This Documentation

### Focus on the Kit

While building a SaaS application involves many moving parts, this documentation focuses specifically on the Next.js Supabase SaaS Kit. For in-depth information on the underlying technologies (Next.js, Supabase, Turbo, etc.), please refer to their respective official documentation.

This documentation will guide you through configuring, running, and deploying the kit, and will provide links to the official documentation of the underlying technologies where necessary. To fully grasp the kit's capabilities, it's essential to understand these technologies, so be sure to explore their documentation as well.

For anything strictly related to the Next.js Supabase SaaS Kit, this documentation has you covered!

### Refer to Official Documentation

For in-depth understanding of the underlying technologies, refer to their official documentation:

- **Next.js:** [Next.js Documentation](https://nextjs.org)
- **Supabase:** [Supabase Documentation](https://supabase.com)
- **Stripe:** [Stripe Documentation](https://stripe.com)

Understanding these technologies is crucial for building a successful SaaS application.

## Conclusion

This Next.js Supabase SaaS Kit is designed to accelerate your SaaS development with a robust, modular, and extensible foundation. Dive into the documentation, explore the features, and start building your SaaS application today! 🚀

Introducing the Next.js Supabase SaaS Kit Turbo repository, which is a Next.js starter kit for building SaaS applications with Supabase.

Introduction to Next.js Supabase SaaS Kit Turbo Repository


The kit is built as a [Turborepo](https://turbo.build) monorepo, and is broadly using the following technologies:

1. Next.js App Router (using Turbopack for faster builds)
2. Supabase for the database, authentication and storage
3. Shadcn UI for the UI components
4. React Query, Zod, Lucide React and other libraries
5. Configurable mailers (SMTP with Nodemailer or Resend)

Makerkit's modular architecture allows you to easily add or remove features, and customize the application to your needs.

Additionally, the kit is designed to be easily deployable to Vercel, Cloudflare, or any other hosting provider. It also supports edge rendering so you can deploy the application to Cloudflare Workers and go FAST.

### Monorepo Structure

Below are the reusable packages that can be shared across multiple applications (or packages):

- **@kit/ui**: Shared UI components and styles (using Shadcn UI and some custom components)
- **@kit/shared**: Shared code and utilities
- **@kit/supabase**: Supabase package that defines the schema and logic for managing Supabase
- **@kit/i18n**: Internationalization package that defines utilities for managing translations
- **@kit/billing**: Billing package that defines the schema and logic for managing subscriptions
- **@kit/billing-gateway**: Billing gateway package that defines the schema and logic for managing payment gateways
- **@kit/email-templates**: Here we define the email templates using the react.email package.
- **@kit/mailers**: Mailer package that abstracts the email service provider (e.g., Resend, Cloudflare, SendGrid, Mailgun, etc.)
- **@kit/monitoring**: A unified monitoring package that defines the schema and logic for monitoring the application with third party services (e.g., Sentry, Baselime, etc.)
- **@kit/database-webhooks**: Database webhooks package that defines the actions following database changes (e.g., sending an email, updating a record, etc.)
- **@kit/cms**: CMS package that defines the schema and logic for managing content
- **@kit/next**: Next.js specific utilities

And features that can be added to the application:

- **@kit/auth**: Authentication package (using Supabase)
- **@kit/accounts**: Package that defines components and logic for managing personal accounts
- **@kit/team-accounts**: Package that defines components and logic for managing team
- **@kit/admin**: Admin package that defines the schema and logic for managing users, subscriptions, and more.
- **@kit/notifications**: Notifications package that defines the schema and logic for managing notifications

And billing packages that can be added to the application:

- **@kit/stripe**: Stripe package that defines the schema and logic for managing Stripe. This is used by the @kit/billing-gateway package and abstracts the Stripe API.
- **@kit/lemon-squeezy**: Lemon Squeezy package that defines the schema and logic for managing Lemon Squeezy. This is used by the @kit/billing-gateway package and abstracts the Lemon Squeezy API.
- **@kit/paddle**: Paddle package that defines the schema and logic for managing Paddle. This is used by the @kit/billing-gateway package and abstracts the Paddle API. (Coming once they release their customer portal)

The CMSs that can be added to the application:

- **@kit/keystatic**: [Keystatic](https://keystatic.com/) package that defines the schema and logic for managing Keystatic. This is used by the @kit/cms package and abstracts the Keystatic API
- **@kit/wordpress**:  WordPress package that defines the schema and logic for managing WordPress. This is used by the @kit/cms package and abstracts the WordPress API.

Also planned (post-release):

- **@kit/plugins**: Move the existing plugins to a separate package here
- **@kit/analytics**: A unified analytics package to track user behavior

### Application Configuration

The configuration is defined in the `apps/web/config` folder. Here you can find the following configuration files:

- **app.config.ts**: Application configuration (e.g., name, description, etc.)
- **auth.config.ts**: Authentication configuration
- **billing.config.ts**: Billing configuration
- **feature-flags.config.ts**: Feature flags configuration
- **paths.config.ts**: Paths configuration (e.g., routes, API paths, etc.)
- **personal-account-sidebar.config.ts**: Personal account sidebar configuration (e.g., links, icons, etc.)
- **team-account-sidebar.config.ts**: Team account sidebar configuration (e.g., links, icons, etc.)


A detailed look at the technical details of the Next.js Supabase SaaS Kit.

Technical Details


Below are some of the conventions used in the Next.js Supabase Turbo Starter Kit.

You're not required to follow these conventions: they're simply a standard set of practices used in the core kit. If you like them - I encourage you to keep these during your usage of the kit - so to have consistent code style that you and your teammates understand.

### Turborepo Packages

In this project, we use Turborepo packages to define reusable code that can be shared across multiple applications.

- **Apps** are used to define the main application, including routing, layout, and global styles.
- Apps pass down configuration to the packages, and the packages provide the corresponding logic and components.

### Creating Packages

**Should you create a package for your app code?**

- **Recommendation:** Do not create a package for your app code unless you plan to reuse it across multiple applications or are experienced in writing library code.
- If your application is not intended for reuse, keep all code in the app folder. This approach saves time and reduces complexity, both of which are beneficial for fast shipping.
- **Experienced developers:** If you have the experience, feel free to create packages as needed.

### Imports and Paths

When importing modules from packages or apps, use the following conventions:

- **From a package:** Use `@kit/package-name` (e.g., `@kit/ui`, `@kit/shared`, etc.).
- **From an app:** Use `~/` (e.g., `~/lib/components`, `~/config`, etc.).

### Non-Route Folders

Non-route folders within the `app` directory are prefixed with an underscore (e.g., `_components`, `_lib`, etc.).

- This prefix indicates that these folders are not routes but are used for shared components, utilities, etc.

### Server Code

Files located in `server` folders are intended for server-side code only. They should not be used in client-side code.

- This convention helps clarify where the code is meant to run, which is particularly important in Next.js where the distinction can be blurry.
- For example, server-related code for a part of the app can be found in the `_lib/server` folder.
- Include the `server-only` package at the top of the file to ensure it is not accidentally imported in client-side code.

Conventions in the Next.js Supabase Turbo Starter Kit

## Prerequisites

To get started with Makerkit, ensure you have the following prerequisites installed and set up:

- **Node.js 18.x or later**
- **Docker**
- **Pnpm**
- **Supabase account** (optional for local development)
- **Payment Gateway account** (Stripe or Lemon Squeezy)
- **Email Service account** (optional for local development)

## Verify your Git username

To verify you have access, you need to check that your local Git username is the same as set up in the Makerkit's Github organization.

Please run the following command to check your Git username:

```bash
git config user.username
```

If the output is not your Github username, or does not match the username registered in Makerkit's Github organization, you can set it using the following command:

```bash
git config --global user.username <your-github-username>
```

**NB**: You must replace `<your-github-username>` with your actual Github username in between quotes.

For example, if your Github username is `johndoe`, you can set it using the following command:

```bash
git config --global user.username "johndoe"
```

This is important to ensure you can run the repository.

## Cloning the Repository

Clone the repository using the following command:

```bash
git clone git@github.com:makerkit/next-supabase-saas-kit-turbo
```

**Note:** If your SSH key isn't set up, use HTTPS instead:

```bash
git clone https://github.com/makerkit/next-supabase-saas-kit-turbo
```

### Important: Use HTTPS for All Commands if Not Using SSH

If you are not using SSH, ensure you switch to HTTPS for all Git commands, not just the clone command.

## Configuring Git Remotes

After cloning the repository, remove the original `origin` remote:

```bash
git remote rm origin
```

Add the upstream remote pointing to the original repository to pull updates:

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

Once you have your own repository set up, add your repository as the `origin`:

```bash
git remote add origin <your-repository-url>
```

### Keeping Your Repository Up to Date

To pull updates from the upstream repository, run the following command daily (preferably with your morning coffee ☕):

```bash
git pull upstream main
```

This ensures your repository stays up to date with the latest changes.

## 0.1. Install Pnpm

Install Pnpm globally with the following command:

```bash
npm i -g pnpm
```

## 1. Setup Dependencies

Install the necessary dependencies for the project:

```bash
pnpm i
```

With these steps completed, your development environment will be set up and ready to go! 🚀

## 2. Post-merge Hooks

It's very useful to run the following command after pulling updates from the upstream repository:

```bash
pnpm i
```

This ensures that any new dependencies are installed and the project is up to date. We can run this command automatically after pulling updates by setting up a post-merge hook.

Create a new file named `post-merge` in the `.git/hooks` directory:

```bash
touch .git/hooks/post-merge
```

Add the following content to the `post-merge` file:

```bash
#!/bin/bash

pnpm i
```

Make the `post-merge` file executable:

```bash
chmod +x .git/hooks/post-merge
```

Now, every time you pull updates from the upstream repository, the `pnpm i` command will run automatically to ensure your project is up to date. This ensures you're always working with the latest changes and dependencies and avoid errors that may arise from outdated dependencies.


Clone the Next.js Supabase SaaS Kit Turbo repository to your local machine.

Clone the Next.js Supabase SaaS Kit Turbo Repository

To run the project, follow these steps to start the development server, Supabase, and Stripe (optional for billing system testing).

## 1. Start the Development Server

To start the web application development server, run:

```bash
# Start the development server
pnpm dev
```

This command launches the web application.

For more details about the web application, please refer to `apps/web/README.md`.

### Quick Start Credentials

Use the following credentials to get started right away:

- **Email**: `test@makerkit.dev`
- **Password**: `testingpassword`

To confirm email addresses, visit [Inbucket](http://localhost:54324/status). Supabase uses Inbucket to capture emails sent during the authentication process.

## 2. Start Supabase

Ensure Docker is running, then start Supabase with:

```bash
pnpm run supabase:web:start
```

This command initiates the Supabase web server.

## 3. Start Stripe (Optional)

To test the billing system, start Stripe by running:

```bash
pnpm run stripe:listen
```

This command routes webhooks to your local machine.

You now have the Next.js Supabase Turbo project running on your local machine. 🚀

## Deploying to Production

When you're ready to deploy the project to production, follow the [checklist](checklist) to ensure everything is set up correctly.

**Note:** Using Supabase's hosted instance is similar to deploying to production. Therefore, you still need to follow the checklist to ensure everything is properly configured.

Learn how to run the Next.js Supabase Turbo project on your local machine.

Running the Next.js Supabase Turbo project


Here are some common commands you'll need to know when working with the Next.js Supabase Turbo Starter Kit.

**Note:** You don't need these commands to kickstart your project, but it's useful to know they exist for when you need them.

## Installing Dependencies

To install the dependencies, run the following command:

```bash
pnpm i
```

This command will install all the necessary dependencies for the project.

## Starting the Development Server

Start the development server for the web application with:

```bash
pnpm run dev
```

## Running Supabase CLI Commands

Supabase is installed in the `apps/web` folder. To run commands with the Supabase CLI, use:

```bash
pnpm run --filter web supabase <command>
```

For example, if Supabase documentation recommends a command like:

```bash
supabase db link
```

You would run:

```bash
pnpm run --filter web supabase db link
```

## Starting Supabase

To start Supabase, run:

```bash
pnpm run supabase:web:start
```

This command starts the Supabase web server.

## Starting Stripe

To test the billing system, start Stripe with:

```bash
pnpm run stripe:listen
```

This routes webhooks to your local machine.

## Resetting Supabase

To reset the Supabase database, which is necessary when you update the schema or need a fresh start, run:

```bash
pnpm run supabase:web:reset
```

## Generate Supabase Types

When you update the Supabase schema, generate the latest types for the client by running:

```bash
pnpm run supabase:web:typegen
```

This should be done every time the Supabase schema is updated.

## Running Tests

To run the tests for the project, use:

```bash
pnpm run test
```

## Cleaning the Project

To clean the project, run:

```bash
pnpm run clean:workspaces
pnpm run clean
```

Then, reinstall the dependencies:

```bash
pnpm i
```

## Type-Checking the Project

To type-check the project, use:

```bash
pnpm run typecheck
```

## Linting the Project

To lint the project using ESLint, run:

```bash
pnpm run lint:fix
```

## Formatting the Project

To format the project using Prettier, run:

```bash
pnpm run format:fix
```

These commands will help you manage and maintain your project efficiently.

Learn about the common commands you need to know to work with the Next.js Supabase Turbo Starter Kit.

Common commands you need to know for the Next.js Supabase Turbo Starter Kit


🚀 Ready to keep your project at the cutting edge? 

This guide will walk you through the process of updating your codebase by pulling the latest changes from the GitHub repository and merging them into your project. This ensures you're always equipped with the latest features and bug fixes.

If you've been following along with our previous guides, you should already have a Git repository set up for your project, with an `upstream` remote pointing to the original repository.

Updating your project involves fetching the latest changes from the `upstream` remote and merging them into your project. Let's dive into the steps!

## 0. Stashing your changes

If you have uncommited changes, before updating your project, it's a good idea to stash your changes to avoid any conflicts during the update process. You can stash your changes by running:

```bash
git stash
```

This will save your changes temporarily, allowing you to update your project without any conflicts. Once you've updated your project, you can apply your changes back by running:

```bash
git stash pop
```

If you don't have any changes to stash, you can skip this step and proceed with the update process. 🛅

Alternatively, you can commit your changes.

## 1. Refresh the `upstream` remote

The first step is to fetch the latest changes from the `upstream` remote. You can do this by running the following command:

```bash
git pull upstream main
```

When prompted the first time, please opt for merging instead of rebasing.

Don't forget to run `pnpm i` in case there are any updates in the dependencies. 🔄

## 2. Resolve any conflicts

Encountered conflicts during the merge? No worries! You'll need to resolve them manually. Git will highlight the files with conflicts, and you can edit them to resolve the issues.

### 2.1 Conflicts in the lock file "pnpm-lock.yaml"

If you find conflicts in the `pnpm-lock.yaml` file, accept either of the two changes (avoid manual edits), then run:

```bash
pnpm i
```

Your lock file will now reflect both your changes and the updates from the `upstream` repository. 🎉

### 2.2 Conflicts in the DB types "database.types.ts"

Your types might differ from those in the `upstream` repository, so you'll need to rebuild them. To do this, reset the DB:

```bash
npm run supabase:web:reset
```

Next, regenerate the types with the following command:

```bash
npm run supabase:web:typegen
```

Your types will now reflect the changes from both the `upstream` repository and your project. 🚀

### Run a health check on your project after resolving conflicts

After resolving the conflicts, it's time to test your project to ensure everything is working as expected. Run your project locally and navigate through the various features to verify that everything is functioning correctly.

You can run the following commands for a quick health check:

```bash
pnpm run typecheck
```

And lint your code with:

```bash
pnpm run lint
```

If everything looks good, you're all set! Your project is now up to date with the latest changes from the `upstream` repository. 🎉

## Commit and push changes

Once everything is working fine, don't forget to commit your changes with git commit -m "COMMIT_MESSAGE" and push them to your remote repository with git push origin BRANCH_NAME.

Of course - please make sure to replace COMMIT_MESSAGE and BRANCH_NAME with your actual commit message and branch name. 🚀

Learn how to update your Next.js Supabase Turbo Starter Kit to the latest version.

Updating your Next.js Supabase Turbo Starter Kit


As mentioned before, this SaaS Starter Kit is modular, thanks to Turborepo - which makes it easy to manage multiple packages in a single repository.

## Project Structure

The main directories in the project are:
1. `apps` - the location of the Next.js app
2. `packages` - the location of the shared code and the API

### `apps` Directory

This is where the app (or the apps, should you add more) lives. The main app is a Next.js app, which is a React framework that allows you to build static and server-rendered web applications.

The Next.js app defines:

1. the configuration of the project
2. the routes of the application

### `packages` Directory

This is where the shared code and the API live. The shared code is a collection of functions that are used by both the Next.js app and the API. The API is a serverless function that is used to interact with the Supabase database.

The shared code defines:

1. shared libraries (Supabase, Mailers, CMS, Billing, etc.)
2. shared features (admin, accounts, account, auth, etc.)
3. UI components (buttons, forms, modals, etc.)

All apps can use and reuse the API exported from the `packages` directory. This makes it easy to have one, or many apps in the same codebase, sharing the same code.

## Diving into the Codebase

The codebase is structured in a way that makes it easy to navigate and update. Here are some of the key files and directories you should be aware of:

```
- apps
--- web
----- app
----- components
----- config
----- lib
----- content
----- styles
----- supabase
```


### Diving into `apps/web`

The `apps/web` directory is where the Next.js app lives. Here are some of the key directories and files you should be aware of:

1. `app` - this is where the main app lives. This is where you define the routes of the application.
2. `components` - this is where you define the shared components of the application.
3. `config` - this is where you define the configuration of the application.
4. `lib` - this is where you define the shared libraries of the application.
5. `content` - this is where you define the content of the application (by default, uses Keystatic Markdoc files)
6. `styles` - this is where you define the styles of the application.
7. `supabase` - this is where you define the Supabase configuration, migrations and tests

### Diving into `app`

The `app` directory is where the routing of the application is defined. Here are some of the key files you should be aware of:

```
- app
--- home
--- (marketing)
--- auth
--- join
--- admin
--- update-password
--- server-sitemap.xml
```

Let's break down the directories:

1. `home` - this is where the internal home of the application lives. This is where you define the routes when the user is logged in.
2. `(marketing)` - this is where the marketing pages of the application live. This is where you define the routes when the user is not logged in. It's a pathless route, so you don't see it in the URL.
3. `auth` - this is where the authentication pages of the application live. This is where you define the routes for the login, signup, and forgot password pages.
4. `join` - this is where the join pages of the application live. This route is the route where the user can join a team account following an invitation.
5. `admin` - this is where the admin pages of the application live. This is where you define the routes for the super admin pages.
6. `update-password` - this is where the update password pages of the application live. This is the route the user is redirected to after resetting their password.
7. `server-sitemap.xml` - this is where the sitemap of the application is defined.

### Diving into `home`

The `home` directory is where the internal dashboard of the application lives. Here are some of the key files you should be aware of:

```
--- home
------ (user)
------ [account]
```

Let's break down the directories:

1. `(user)` - this is where the user pages of the application live. This is where you define the routes for the personal account pages.
2. `[account]` - this is where the account pages of the application live. This is where you define the routes for the team account pages.

The `home` path allows us to separate the marketing pages from the internal dashboard pages.

So the user home page would be `/home/user` and the account home page would be `/home/[account]`.






Learn how to navigate the codebase of the Next.js Supabase Turbo Starter Kit. Understand the project structure and how to update the codebase.

Navigating the your Next.js Supabase Turbo Starter Kit codebase


This is a functional walkthrough of the Next.js Supabase Turbo Starter Kit. In this guide, you'll learn about the functional aspects of the kit.

## Overview of the Next.js Supabase Turbo Starter Kit

We can break down the Next.js Supabase Turbo Starter Kit into the following functional sections:

1. **Marketing / External Section** - the public-facing part of the application. This also includes the blog and documentation.
2. **Authentication** - the authentication system of the application.
3. **Personal Account Features** - the features available to personal accounts.
4. **Team Account Features** - the features available to team accounts.
5. **Invitations** - the invitation system of the application.
6. **Super Admin** - the super admin features of the application.

## Marketing / External Section

The marketing section is the public-facing part of the application. It is where users can learn about the product, the pricing and the legal information.

### Home Page

The home page is the landing page of the application. It showcases the features of the product and encourages users to sign up.

<Image src="/assets/images/docs/walkthrough/home-page.webp" width={3420} height={2142} />

### Pricing

The pricing page is where users can learn about the different pricing plans of the product.

<Image src="/assets/images/docs/walkthrough/pricing.webp" width={3420} height={2142} />

This section is also added to the home page.

### FAQ

The FAQ page is where users can find answers to common questions about the product.

<Image src="/assets/images/docs/walkthrough/faq.webp" width={3420} height={2142} />

### Contact

The contact page is where users can get in touch with the company. It includes a contact form that allows users to send messages to the company directly.

<Image src="/assets/images/docs/walkthrough/contact.webp" width={3420} height={2142} />

### Content Pages

Content pages can be displayed using the CMS that you have setup. By default, the kit implements a Blog and a Documentation systems using either Keystatic or Wordpress. You can choose which one you prefer.

#### Blog

The blog is where the company can publish articles about the product, the industry, and other topics.

Below is the page where all the latest blog posts are listed:

<Image src="/assets/images/docs/walkthrough/blog.webp" width={3420} height={2142} />

And here is an example of a blog post:

<Image src="/assets/images/docs/walkthrough/blog-post.webp" width={3420} height={2142} />

#### Documentation

The documentation is where users can learn how to use the product. It includes guides, tutorials, and reference material.

<Image src="/assets/images/docs/walkthrough/walkthrough-documentation.webp" width={3420} height={2142} />

### Legal Pages

The legal pages are, of course, empty and need to be filled in with the appropriate legal information.

Don't use ChatGPT to fill them up. It's a bad idea.

## Authentication

The authentication system is where users can sign up, sign in, reset their password. It also includes multi-factor authentication.

### Sign Up

The sign-up page is where users can create an account. They need to provide their email address and password.

<Image src="/assets/images/docs/walkthrough/sign-up.webp" width={3420} height={2142} />

Once successful, users are asked to confirm their email address. This is enabled by default - and due to security reasons, it's not possible to disable it.

<Image src="/assets/images/docs/walkthrough/sign-up-success.webp" width={3420} height={2142} />

### Sign In

The sign-in page is where users can log in to their account. They need to provide their email address and password.

<Image src="/assets/images/docs/walkthrough/sign-in.webp" width={3420} height={2142} />

### Password Reset

The password reset page is where users can reset their password. They need to provide their email address.

<Image src="/assets/images/docs/walkthrough/password-reset.webp" width={3420} height={2142} />

### Multi-Factor Authentication

Multi-Factor Authentication (MFA) is an additional layer of security that requires users to provide two or more verification factors to sign in to their account.

First, users need to enable MFA and add a factor:

<Image src="/assets/images/docs/walkthrough/setup-mfa.webp" width={3420} height={2142} />

Then, after signing in, users need to provide the verification code:

<Image src="/assets/images/docs/walkthrough/verify-mfa.webp" width={3420} height={2142} />

## Internal / Behind authentication pages

After signing in - users are redirected to the internal pages of the application. These pages are only accessible to authenticated users.

The internal part of the application is divided into two workspaces:

1. The user workspace
2. The team workspace (optional)

This is how this works:

1. **Personal Account** - all users have a personal account. This is where they can: manage their settings, choose a team account - and **optionally** subscribe to a plan, or access the features you provide.
2. **Team Account (optional)** - users can create a team account - and invite other users to join. The team account has its own workspace - where users can manage the team settings, members, and billing.

Generally speaking, **it's up to you** to decide what features are available to personal accounts and team accounts. You can choose to disable billing for personal accounts - and only enable it for team accounts - or vice versa.

One simple rule of a thumb is that personal accounts are for individuals - and team accounts are for organizations. Personal accounts cannot be disabled, as that would disallow users from accessing the application should they not be part of a team - which doesn't make sense.

## Personal Account Features

The personal account workspace is where users can access the features available to their personal account.

This is the home page after logging in - and it's the user workspace:

1. Home Page - empty by default (but you can optionally provide the list of teams the user is part of)
2. Account Settings
3. Billing (if enabled)

### Home Page of the user workspace

By default - the user home is an empty page - as it's likely you will want to place some content that is unique to your SaaS.

However, we provide a component that allows you to lists the team an account is part of: this is useful for B2B SaaS rather than B2C.

The internal pages have two layouts:

1. A sidebar layout (default)
2. A top navigation layout

You can choose any of the two - and also choose either one for the user layout or the account layout.

Below is the user home page with the sidebar layout:

<Image src="/assets/images/docs/walkthrough/user-home-sidebar.webp" width={3420} height={2142} />

And below is the user home page with the top navigation layout:

<Image src="/assets/images/docs/walkthrough/user-home-header.webp" width={3420} height={2142} />

You can choose the one that fits your needs.

### Account Settings of the user workspace

From the navigation - users can access their account settings. Here they can update their profile information, change their password, language, multi-factor authentication, and more.

We've used light mode so far - how about dark mode? Let's switch to dark mode:

<Image src="/assets/images/docs/walkthrough/user-account-settings.webp" width={3420} height={2142} />

### Billing of the user workspace

Users can check out and subscribe to a plan - or visit the billing portal - from the billing page.

**This is only visible if billing is enabled**: you can choose to disable billing for a personal account - and only enable it for team accounts - or vice versa.

<Image src="/assets/images/docs/walkthrough/user-billing.webp" width={3420} height={2142} />

Once choosing a plan - we load the embedded checkout form from Stripe (or Lemon Squeezy).

After subscribing, the billing page will show the subscription details.

<Image src="/assets/images/docs/walkthrough/user-billing-plan.webp" width={3420} height={2142} />

## Team Account Features

From the profile dropdown, users can choose:

1. Switch to a team account
2. Create a team account

<Image src="/assets/images/docs/walkthrough/user-profile-dropdown.webp" width={876} height={796} />

In a team account workspace - users can access the following features:

1. A team account home page: by default - we display a mock dashboard, just as an example.
2. Account settings: users can update the team account settings.
3. Members: users can view the members of the team account.
4. Billing: users can view the billing of the team account.

### Home Page of the team workspace

By default - the team home is a mock dashboard - just as an example. You can replace this with your own dashboard - or any other content.

<Image src="/assets/images/docs/walkthrough/team-account-dashboard.webp" width={3420} height={2142} />

### Account Settings of the team workspace

From the navigation - users can access the team account settings. Here they can update the team account information, or delete the team account (if owner), or leave the team account (if member).

<Image src="/assets/images/docs/walkthrough/team-account-settings.webp" width={3420} height={2142} />

### Members page of the team workspace

From the navigation - users can access the members of the team account.

Here they can:

1. view the members
2. invite new members
3. remove or update an existing member
4. transfer ownership to another member
5. remove or update an invitation

<Image src="/assets/images/docs/walkthrough/team-account-members.webp" width={3420} height={2142} />

### Billing of the team workspace

If enabled - users can view the billing of the team account - and subscribe to a plan or visit the billing portal.

<Image src="/assets/images/docs/walkthrough/team-account-billing.webp" width={3420} height={2142} />

## Joining a team account

When a user is invited to join a team account - they receive an email with an invitation link. After signing up or signing in - they are redirected to the join page.

<Image src="/assets/images/docs/walkthrough/sign-up-invite.webp" width={3420} height={2142} />

### Join Page

The join page is where users can join a team account.

<Image src="/assets/images/docs/walkthrough/join-team.webp" width={3420} height={2142} />

## Super Admin

The super admin is the administrator of the SaaS. They have access to a special set of features that allow them to manage the accounts of the SaaS.

### Home Page of the super admin

The home page is a small overview of the SaaS.

You can easily customize this page to show the most important metrics of your SaaS.

<Image src="/assets/images/docs/walkthrough/super-admin-dashboard.jpg" width={3420} height={2142} />

### Listing the accounts of the SaaS

The super admin can view all the accounts of the SaaS. They can filter the accounts by personal accounts, team accounts, or all accounts.

<Image src="/assets/images/docs/walkthrough/super-admin-accounts.webp" width={3420} height={2142} />

### Viewing the account details

The super admin can view the details of an account. They can see the account information, the members of the account, and the billing information.

Additionally, they can perform the following actions:

1. Ban the account (or unban)
2. Delete the account

<Image src="/assets/images/docs/walkthrough/super-admin-account.webp" width={3420} height={2142} />

## Conclusion

This concludes the functional walkthrough of the Next.js Supabase Turbo Starter Kit. You should now have a good understanding of the features of the kit and how to use it. If you have any questions, feel free to reach out to us. We're here to help!


A functional walkthrough of the Next.js Supabase Turbo Starter Kit. Understand the features and how to use the kit.

Functional Walkthrough - Next.js Supabase Turbo Starter Kit


🚀 Welcome to your journey from Makerkit v1 to the Next.js SaaS Boilerplate! 

This guide is designed to help you understand the changes between the two versions and navigate your project migration to the new v2. Whether you're a seasoned developer or just starting out, we've got you covered!

Here's a roadmap of the steps you'll take:

1. **Bootstrap a new project**: Kickstart a new project using the Next.js SaaS Boilerplate v2 🎉
2. **Update Schema**: Tweak the Postgres schema foreign key references, and integrate your existing tables 🧩
3. **Move files from older app**: Transport your files to the new app structure 📦
4. **Update imports to existing files**: Refresh imports to align with the new file structure 🔄
5. **Update configuration**: Modify the configuration files to match the new schemas ⚙️

## 1. Bootstrap a new project

The Next.js SaaS Boilerplate is a fresh take on Makerkit v1. You'll need to create a new project using this innovative boilerplate. Follow the [installation guide](clone-repository) to get your new project up and running in no time!

## 2. Update Schema

The schema in the Next.js SaaS Boilerplate has evolved significantly from Makerkit v1. You'll need to update your Postgres schema to match the new one.

Previously, you'd have a foreign key set to the organization ID:

```sql
organization_id bigint not null references organizations(id) on delete cascade,
```

Now, you'll have a foreign key set to the account ID as a UUID:

```sql
account_id uuid not null references public.accounts(id) on delete cascade,
```

In v2, an account can be both a user or an organization. So, instead of referencing the organization ID as in v1, you'll now reference the account ID. 

## 3. Move files from older app

In v2, you have the flexibility to add these files to either the "user scope" (`/home`) or the "account scope" (`/home/[account]`). Choose the one that best suits your project needs.

## 4. Update imports to existing files

You'll need to update the imports to your existing files to match the new file structure. This applies to all the components and utilities that you imported from Makerkit. For instance, a button previously imported from `~/core/ui/Button`, will now be imported from `@kit/ui/button`.

## 5. Update configuration

Lastly, you'll need to update the configuration files to match the new schemas. The configuration is now split across various files at `apps/web/config`. Pay special attention to the billing schema, which is now more versatile (and a bit more complex).

Ready to get started? Let's dive in! 🏊‍♀️

Guidelines for migrating from Makerkit v1 to Next.js SaaS Boilerplate.

Guidelines for migrating from Makerkit v1


Makerkit provides a set of tools to ensure code health and quality in your project. This includes setting up Github Actions, pre-commit hooks, and more.

## Github Actions

By default, Makerkit sets up Github Actions to run tests on every push to the repository. You can find the Github Actions configuration in the `.github/workflows` directory.

The workflow has two jobs:

1. `typescript` - runs the Typescript compiler to check for type errors.
2. `test` - runs the Playwright tests in the `tests` directory.

### Enable E2E Tests

Since it needs some setup - these are not enabled by default. To enable E2E tests, you need to set the following environment variables in the Github Actions workflow:

```bash
ENABLE_E2E_JOB=true
```

### Configuring the E2E environment for Github Actions
To set up Github Actions for your project, please add the following secrets to your repository Github Actions settings:

1. `SUPABASE_SERVICE_ROLE_KEY` - the service role key for Supabase.
2. `SUPABASE_DB_WEBHOOK_SECRET` - the webhook secret for Supabase.
3. `STRIPE_SECRET_KEY` - the secret key for Stripe.
4. `STRIPE_WEBHOOK_SECRET` - the webhook secret for Stripe.

These are the same as the ones you have running the project locally. Don't use real secrets here - use the development app secrets that you use locally. **This is a testing environment**, and you don't want to expose your production secrets.

Additionally, please set the following environment variables in the Github Actions workflow:

1. `NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY` - this is the publishable key for Stripe.
2. `SUPABASE_DB_WEBHOOK_SECRET`: Use the value `WEBHOOKSECRET` for the webhook secret. Again, this is a testing environment, so we add testing values.

### Enable Stripe Tests

Since it needs some setup - these are not enabled by default. To enable Stripe tests, you need to set the following environment variables in the Github Actions workflow:

```bash
ENABLE_BILLING_TESTS=true
```

Of course - make sure you have the Stripe secrets set up in the Github Actions secrets.

## Pre-Commit Hook

It's recommended to set up a pre-commit hook to ensure that your code is linted correctly and passes the typechecker before committing.

### Setting up the Pre-Commit Hook

To do so, create a `pre-commit` file in the `./.git/hooks` directory with the following content:

```bash
#!/bin/sh

pnpm run typecheck
pnpm run lint
```

Turborepo will execute the commands for all the affected packages - while skipping the ones that are not affected.

### Make the Pre-Commit Hook Executable

Now, make the file executable:

```bash
chmod +x ./.git/hooks/pre-commit
```

To test the pre-commit hook, try to commit a file with linting errors or type errors. The commit should fail, and you should see the error messages in the console.

### What about the e2e tests?

You could also add tests - but it'll slow down your commits. It's better to run tests in Github Actions.


Learn how to set up Github Actions, pre-commit hooks, and more in Makerkit to ensure code health and quality.

Code Health and Testing in Makerkit. Set up Github Actions, pre-commit hooks, and more.

The below is a technical FAQ about this kit. For general questions about Makerkit, please see the [Makerkit FAQ](/faq).

## Technical FAQ

### Do I need to know Supabase to use the Next.js SaaS Boilerplate?

Yes, you should have a basic understanding of Supabase to use the Next.js SaaS Boilerplate. You'll need to know how to:

- Create a Supabase project
- Set up the database
- Understand PostgreSQL
- Use the Supabase client in your Next.js app

While you can use the kit to learn, it does not teach you how to use Supabase. For that, please refer to the [Supabase documentation](https://supabase.com/docs).

### Do I need to know Next.js to use the Next.js SaaS Boilerplate?

Yes, you should have a basic understanding of Next.js to use the Next.js SaaS Boilerplate.

### I don't know Supabase! Should I buy the Next.js SaaS Boilerplate?

You should be prepared for a learning curve or consider learning Supabase first. The Next.js SaaS Boilerplate is built on top of Supabase, so knowing how to use Supabase is essential.

### I don't know Turborepo! Should I buy the Next.js SaaS Boilerplate?

Yes, you can still use the Next.js SaaS Boilerplate without prior knowledge of Turborepo. Turborepo is used to manage the monorepo structure of the boilerplate. Your main focus will be on building your SaaS product within the `apps/web` directory, not on the tools used to build the boilerplate. Even without experience using Turborepo, you won't need to interact with it directly unless you plan to customize the core code in the `packages` directory.

### Will you add more packages in the future?

Very likely! This kit is designed to be modular, allowing for new features and packages to be added without interfering with your existing code. There are many ideas for new packages and features that may be added in the future.

### Can I use this kit for a non-SaaS project?

This kit is primarily intended for SaaS projects. If you're building a non-SaaS project, the Next.js SaaS Boilerplate might be overkill. You can still use it, but you might need to remove some features specific to SaaS projects.

### Can I use personal accounts only?

Yes, you can set a feature flag to disable team accounts and use personal accounts only.

### Can I use the React package X with this kit?

Yes, you can use any React package with this kit. The kit is a simple Next.js application, so you are generally only constrained by the underlying technologies (Next.js, Stripe, Supabase, etc.) and not by the kit itself. Since you own and can edit all the code, you can adapt the kit to your needs. However, if there are limitations with the underlying technology, you might need to work around them.

### Does Makerkit set up the production instance for me?

No, Makerkit does not set up the production instance for you. This includes setting up Supabase, Stripe, and any other services you need. Makerkit does not have access to your Stripe or Supabase accounts, so setup on your end is required. Makerkit provides the codebase and documentation to help you set up your SaaS project.

### How do I get support if I encounter issues?

For support, you can:

1. Visit our Discord
2. Contact us via support email

### Are there any example projects or demos?

Yes - you get access to the OpenAI demo.

### How do I deploy my application?

Please check the [production checklist](checklist) for more information.

### How do I contribute to the Next.js SaaS Boilerplate?

We welcome contributions! Please ping me if you'd like to contribute (licensees only).

### How do I update my project when a new version of the boilerplate is released?

Please [read the documentation for updating your Makerkit project](updating-codebase).


Frequently asked questions about the Next.js SaaS Boilerplate.

FAQ - Questions about the Next.js SaaS Boilerplate

Configuration for the Next.js SaaS Starter Kit

Configuration


Environment variables are defined in the `.env` file in the root of the `apps/web` package.

1. **Shared Environment Variables**: Shared environment variables are defined in the `.env` file. These are the env variables shared between environments (e.g., development, staging, production).
2. **Environment Variables**: Environment variables for a specific environment are defined in the `.env.development` and `.env.production` files. These are the env variables specific to the development and production environments.
3. **Secret Keys**: Secret keys and sensitive information are not stored in the `.env` file. Instead, they are stored in the environment variables of the CI/CD system.
4. **Secret keys to be used locally**: If you need to use secret keys locally, you can store them in the `.env.local` file. This file is not committed to Git, therefore it is safe to store sensitive information in it.

---

The majority of the environment variables are defined in the `apps/web/.env` file. These are the env variables
shared between environments (eg. they will be the same for development, staging, and production).

**NB: You will not add any secret keys or sensitive information here.** Only configuration, paths, feature flags, etc.

```bash
# SHARED ENVIRONMENT VARIABLES
# HERE YOU CAN ADD ALL THE **PUBLIC** ENVIRONMENT VARIABLES THAT ARE SHARED ACROSS ALL THE ENVIRONMENTS
# PLEASE DO NOT ADD ANY CONFIDENTIAL KEYS OR SENSITIVE INFORMATION HERE
# ONLY CONFIGURATION, PATH, FEATURE FLAGS, ETC.
# TO OVERRIDE THESE VARIABLES IN A SPECIFIC ENVIRONMENT, PLEASE ADD THEM TO THE SPECIFIC ENVIRONMENT FILE (e.g. .env.development, .env.production)

# SITE
NEXT_PUBLIC_SITE_URL=http://localhost:3000
NEXT_PUBLIC_PRODUCT_NAME=Makerkit
NEXT_PUBLIC_SITE_TITLE="Makerkit - The easiest way to build and manage your SaaS"
NEXT_PUBLIC_SITE_DESCRIPTION="Makerkit is the easiest way to build and manage your SaaS. It provides you with the tools you need to build your SaaS, without the hassle of building it from scratch."
NEXT_PUBLIC_DEFAULT_THEME_MODE=light
NEXT_PUBLIC_THEME_COLOR="#ffffff"
NEXT_PUBLIC_THEME_COLOR_DARK="#0a0a0a"

# AUTH
NEXT_PUBLIC_AUTH_PASSWORD=true
NEXT_PUBLIC_AUTH_MAGIC_LINK=false
NEXT_PUBLIC_CAPTCHA_SITE_KEY=

# BILLING
NEXT_PUBLIC_BILLING_PROVIDER=stripe

# CMS
CMS_CLIENT=keystatic

# KEYSTATIC
NEXT_PUBLIC_KEYSTATIC_CONTENT_PATH=./content

# LOCALES PATH
NEXT_PUBLIC_LOCALES_PATH=apps/web/public/locales

# PATHS (to be used in "packages")
SIGN_IN_PATH=/auth/sign-in
SIGN_UP_PATH=/auth/sign-up
TEAM_ACCOUNTS_HOME_PATH=/home
INVITATION_PAGE_PATH=/join

# FEATURE FLAGS
NEXT_PUBLIC_ENABLE_THEME_TOGGLE=true
NEXT_PUBLIC_ENABLE_PERSONAL_ACCOUNT_DELETION=true
NEXT_PUBLIC_ENABLE_PERSONAL_ACCOUNT_BILLING=true
NEXT_PUBLIC_ENABLE_TEAM_ACCOUNTS_DELETION=true
NEXT_PUBLIC_ENABLE_TEAM_ACCOUNTS_BILLING=true
NEXT_PUBLIC_ENABLE_TEAM_ACCOUNTS=true
NEXT_PUBLIC_ENABLE_TEAM_ACCOUNTS_CREATION=true
```

Please update the `apps/web/.env` file with the appropriate values.

This is complemented by the environment variables defined in the `apps/web/.env.development` and `apps/web/.env.production` files.

### Secret Keys

Secret keys and sensitive information are to be never stored in the `.env` file. Instead, **they are stored in the environment variables of the CI/CD system**.

What does this mean? It means that you will need to add the secret keys to the environment variables of your CI/CD system (e.g., GitHub Actions, Vercel, Cloudflare, your VPS, Netlify, etc.). This is not a Makerkit-specific requirement, but a best practice for security for any application. Ultimately, it's your choice.

Below are some of the additional secret keys that you may need to add to your environment variables:

#### Supabase

For Supabase, you'll need to add the following environment variables:

```bash
SUPABASE_SERVICE_ROLE_KEY=
```

#### Stripe

Please check the [Stripe documentation](stripe).

#### Lemon Squeezy

Please check the [Lemon Squeezy documentation](lemon-squeezy).

#### Mailers

Please check the [Mailers documentation](email-configuration).

#### Monitoring

Please check the [Monitoring documentation](monitoring).

#### CMS

Please check the [CMS documentation](cms).

### Feature Flags

To enable or disable certain application features, please toggle the values below:

```BASH
NEXT_PUBLIC_ENABLE_THEME_TOGGLE=true
NEXT_PUBLIC_ENABLE_PERSONAL_ACCOUNT_DELETION=true
NEXT_PUBLIC_ENABLE_PERSONAL_ACCOUNT_BILLING=true
NEXT_PUBLIC_ENABLE_TEAM_ACCOUNTS_DELETION=true
NEXT_PUBLIC_ENABLE_TEAM_ACCOUNTS_BILLING=true
NEXT_PUBLIC_ENABLE_TEAM_ACCOUNTS=true
NEXT_PUBLIC_ENABLE_TEAM_ACCOUNTS_CREATION=true
```

The following feature flags are available:

1. **NEXT_PUBLIC_ENABLE_THEME_TOGGLE** - you can hide the theme toggle (if you want to force a single theme)
2. **NEXT_PUBLIC_ENABLE_PERSONAL_ACCOUNT_DELETION** - to prevent users from self-deleting their personal account
3. **NEXT_PUBLIC_ENABLE_PERSONAL_ACCOUNT_BILLING** - to enable/disable billing for personal accounts
4. **NEXT_PUBLIC_ENABLE_TEAM_ACCOUNTS_DELETION** - to prevent team accounts from self-deleting the account
5. **NEXT_PUBLIC_ENABLE_TEAM_ACCOUNTS_BILLING** - to enable/disable billing for team accounts
6. **NEXT_PUBLIC_ENABLE_TEAM_ACCOUNTS** - to disable team accounts
7. **NEXT_PUBLIC_ENABLE_TEAM_ACCOUNTS_CREATION** - to enable/disable the ability to create a team account

#### Personal Accounts vs Team Accounts

The starter kit supports two types of accounts:

1. Personal accounts are accounts that are owned by a single user.
2. Team accounts are accounts that group multiple users together.

This allows you to:

1. Serve B2C customers (personal accounts)
2. Serve B2B customers (team accounts)
3. Allow both (for example, like GitHub)

In the vast majority of cases, **you will want to enable billing for personal OR team accounts**. I have not seen many cases where billing both was required.

To do so, please set the following variables accordingly.

For enabling personal accounts billing only:

```bash
NEXT_PUBLIC_ENABLE_PERSONAL_ACCOUNT_BILLING=true
NEXT_PUBLIC_ENABLE_TEAM_ACCOUNTS_BILLING=false
```

You may also want to fully disable team accounts:

```bash
NEXT_PUBLIC_ENABLE_TEAM_ACCOUNTS=false
```

To enable team accounts billing only:

```bash
NEXT_PUBLIC_ENABLE_PERSONAL_ACCOUNT_BILLING=false
NEXT_PUBLIC_ENABLE_TEAM_ACCOUNTS_BILLING=true
```

To enable both, leave them both as `true`.

Please remember that for ensuring DB consistency, you need to also set them at DB level by adjusting the table `config`:

```sql
create table if not exists public.config(
    enable_team_accounts boolean default true not null,
    enable_account_billing boolean default true not null,
    enable_team_account_billing boolean default true not null,
    billing_provider public.billing_provider default 'stripe' not null
);
```

To enable personal account billing:

```sql
update config set enable_account_billing = true;
```

To enable team account billing:

```sql
update config set enable_team_account_billing = true;
```

To disable team accounts:

```sql
update config set enable_team_accounts = false;
```

To leave them both enabled, just leave them as they are.

## Contact Form submissions

To receive submissions from the contact form, you need to set up the following environment variables:

```bash
CONTACT_EMAIL=
```

This email will receive the submissions from the contact form.

## List of Environment Variables for the Web App

### NEXT_PUBLIC_SITE_URL

The URL of the site. This is used for generating absolute URLs across the site (where needed). When going to production, this should be set to the production URL - including `https` as protocol (e.g., `https://example.com`). The configuration will validate that the URL is valid - so the build will fail if the URL is not valid.

```
NEXT_PUBLIC_SITE_URL=https://example.com
```

### NEXT_PUBLIC_PRODUCT_NAME

The name of the product. This is used in various places across the site.

```
NEXT_PUBLIC_PRODUCT_NAME=Makerkit
```

### NEXT_PUBLIC_SITE_TITLE

The title of the site. This is used in the `<title>` tag of the site.

```
NEXT_PUBLIC_SITE_TITLE=Makerkit - The easiest way to start your next project
```

### NEXT_PUBLIC_SITE_DESCRIPTION

The description of the site. This is used in the `<meta name="description">` tag of the site.

```
NEXT_PUBLIC_SITE_DESCRIPTION=Makerkit is the easiest way to start your next project. It comes with everything you need to get started.
```

### NEXT_PUBLIC_DEFAULT_THEME_MODE

The default theme mode of the site. This can be either `light` or `dark` or `system` (to follow the system theme).

```
NEXT_PUBLIC_DEFAULT_THEME_MODE=light
```

### NEXT_PUBLIC_DEFAULT_LOCALE

The default locale of the site. This is used for the default language of the site.

```
NEXT_PUBLIC_DEFAULT_LOCALE=en
```

### NEXT_PUBLIC_AUTH_PASSWORD

Use this variable to enable or disable password-based authentication. If you set this to `true`, users will be able to sign up and sign in using their email and password. If you set this to `false`, the form won't be shown.

```
NEXT_PUBLIC_AUTH_PASSWORD=true
```

### NEXT_PUBLIC_AUTH_MAGIC_LINK

Use this variable to enable or disable magic link-based authentication. If you set this to `true`, users will be able to sign up and sign in using a magic link sent to their email. If you set this to `false`, the form won't be shown.

```
NEXT_PUBLIC_AUTH_MAGIC_LINK=true
```

### CONTACT_EMAIL

The email address where the contact form submissions will be sent.

```
CONTACT_EMAIL=info@makerkit.dev
```

### NEXT_PUBLIC_ENABLE_THEME_TOGGLE

Use this variable to enable or disable the theme toggle. If you set this to `true`, the theme toggle will be shown. If you set this to `false`, the theme toggle won't be shown.

```
NEXT_PUBLIC_ENABLE_THEME_TOGGLE=true
```

### NEXT_PUBLIC_ENABLE_PERSONAL_ACCOUNT_DELETION

Use this variable to enable or disable personal account deletion. If you set this to `true`, users will be able to delete their personal account. If you set this to `false`, the form won't be shown.

```
NEXT_PUBLIC_ENABLE_PERSONAL_ACCOUNT_DELETION=true
```

### NEXT_PUBLIC_ENABLE_PERSONAL_ACCOUNT_BILLING

Use this variable to enable or disable billing for personal accounts. If you set this to `true`, users will be able to add their billing information. If you set this to `false`, the form won't be shown.

```
NEXT_PUBLIC_ENABLE_PERSONAL_ACCOUNT_BILLING=true
```

### NEXT_PUBLIC_ENABLE_TEAM_ACCOUNT_DELETION

Use this variable to enable or disable team accounts deletion. If you set this to `true`, users will be able to delete their team account. If you set this to `false`, the form won't be shown.

```
NEXT_PUBLIC_ENABLE_TEAM_ACCOUNT_DELETION=true
```

### NEXT_PUBLIC_ENABLE_TEAM_ACCOUNTS_BILLING

Use this variable to enable or disable billing for team accounts. If you set this to `true`, users will be able to add their billing information. If you set this to `false`, the form won't be shown.

```
NEXT_PUBLIC_ENABLE_TEAM_ACCOUNTS_BILLING=true
```

### NEXT_PUBLIC_ENABLE_TEAM_ACCOUNTS

Use this variable to enable or disable team accounts. If you set this to `true`, users will be able to create team accounts. If you set this to `false`, the form won't be shown.

```
NEXT_PUBLIC_ENABLE_TEAM_ACCOUNTS=true
```

### NEXT_PUBLIC_ENABLE_TEAM_ACCOUNTS_BILLING

Use this variable to enable or disable billing for team accounts. If you set this to `true`, users will be able to add their billing information. If you set this to `false`, the form won't be shown.

```
NEXT_PUBLIC_ENABLE_TEAM_ACCOUNTS_BILLING=true
```

### NEXT_PUBLIC_ENABLE_TEAM_ACCOUNTS_CREATION

Use this variable to enable or disable team accounts creation. If you set this to `true`, users will be able to create team accounts. If you set this to `false`, the form won't be shown.

```
NEXT_PUBLIC_ENABLE_TEAM_ACCOUNTS_CREATION=true
```

### NEXT_PUBLIC_ENABLE_NOTIFICATIONS

Use this variable to enable or disable notifications.

If you set this to `true`, users will be able to see the notifications dropdown. If you set this to `false`, the notifications dropdown won't be shown.

```
NEXT_PUBLIC_ENABLE_NOTIFICATIONS=true
```

### NEXT_PUBLIC_REALTIME_NOTIFICATIONS

Use this variable to enable or disable real-time notifications.

If you set it to `true` we will use Supabase Realtime to show notifications in real-time. If you set it to `false`, notifications will be fetched lazily.

This is preferable for billing reasons, as real-time notifications can be expensive.

```
NEXT_PUBLIC_REALTIME_NOTIFICATIONS=true
```

### NEXT_PUBLIC_ENABLE_VERSION_UPDATER

Use this variable to enable or disable the version updater. If enabled, the version updater will check for new versions of the app and prompt the user to update.

NB: if you use Vercel, this is redundant, as Vercel uses Skew Protection to automatically reload the page when a new version is deployed.

```
NEXT_PUBLIC_ENABLE_VERSION_UPDATER=true
```

This is disabled by default.

### NEXT_PUBLIC_SUPABASE_URL

The URL of the Supabase project.

```
NEXT_PUBLIC_SUPABASE_URL=https://yourproject.supabase.co
```

### NEXT_PUBLIC_SUPABASE_ANON_KEY

The anonymous key of the Supabase project. You find this in your Supabase project settings.

```
NEXT_PUBLIC_SUPABASE_ANON_KEY=your-anon-key
```

### SUPABASE_SERVICE_ROLE_KEY

The service role key of the Supabase project. You find this in your Supabase project settings.

```
SUPABASE_SERVICE_ROLE_KEY=your-service-role-key
```

### NEXT_PUBLIC_BILLING_PROVIDER

The billing provider to use. This can be either `stripe` or `lemon-squeezy`.

```
NEXT_PUBLIC_BILLING_PROVIDER=stripe
```

### NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY

If you are using Stripe as your billing provider, you need to set this variable to your Stripe publishable key.

```
NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY=your-stripe-publishable-key
```

### STRIPE_SECRET_KEY

If you are using Stripe as your billing provider, you need to set this variable to your Stripe secret key.

```
STRIPE_SECRET_KEY=your-stripe-secret-key
```

### STRIPE_WEBHOOK_SECRET

If you are using Stripe as your billing provider, you need to set this variable to your Stripe webhook secret.

```
STRIPE_WEBHOOK_SECRET=your-stripe-webhook-secret
```

This variable is the "Signing Secret" from the Stripe webhook settings, after creating a webhook endpoint.

### LEMON_SQUEEZY_SECRET_KEY

If you are using Lemon Squeezy as your billing provider, you need to set this variable to your Lemon Squeezy secret key.

```
LEMON_SQUEEZY_SECRET_KEY=your-lemon-squeezy-secret-key
```

### LEMON_SQUEEZY_STORE_ID

If you are using Lemon Squeezy as your billing provider, you need to set this variable to your Lemon Squeezy store ID.

```
LEMON_SQUEEZY_STORE_ID=your-lemon-squeezy-store-id
```

### LEMON_SQUEEZY_SIGNING_SECRET

If you are using Lemon Squeezy as your billing provider, you need to set this variable to your Lemon Squeezy signing secret.

```
LEMON_SQUEEZY_SIGNING_SECRET=your-lemon-squeezy-signing-secret
```

### SUPABASE_DB_WEBHOOK_SECRET

This is a secret key that you must generate and set in both the the environment variable and in the Supabase webhook headers when ccreating a webhook.

This is used to verify that the webhook is coming from the correct source.

Please use any random string for this. For example, make a strong password using a password manager.

```
SUPABASE_DB_WEBHOOK_SECRET=********
```

### CMS_CLIENT

The CMS client to use. This can be either `wordpress` or `keystatic`.

```
CMS_CLIENT=keystatic
```

### WORDPRESS_API_URL

If you are using WordPress as your CMS client, you need to set this variable to your WordPress API URL.

```
WORDPRESS_API_URL=https://your-wordpress-site.com/wp-json
```

### MAILER_PROVIDER

The mailer provider to use. This can be either `nodemailer` or `resend`.

```
MAILER_PROVIDER=nodemailer
```

Resend uses an HTTP API to send emails. Nodemailer uses SMTP. It is mandatory to use Resend when using the edge runtime, since it doesn't support Nodemailer, which requires a Node.js runtime.

### RESEND_API_KEY

If you are using Resend as your mailer provider, you need to set this variable to your Resend API key.

```
RESEND_API_KEY=your-resend-api-key
```

### EMAIL_SENDER

The email address to use as the sender of the emails.

```
EMAIL_SENDER=info@makerkit.dev
```

### EMAIL_HOST

If you are using Nodemailer as your mailer provider, you need to set this variable to your SMTP host.

```
EMAIL_HOST=smtp.your-email-provider.com
```

### EMAIL_PORT

If you are using Nodemailer as your mailer provider, you need to set this variable to your SMTP port.

```
EMAIL_PORT=587
```

### EMAIL_USER

If you are using Nodemailer as your mailer provider, you need to set this variable to your SMTP user.

```
EMAIL_USER=your-email-user
```

### EMAIL_PASSWORD

If you are using Nodemailer as your mailer provider, you need to set this variable to your SMTP password.

```
EMAIL_PASSWORD=your-email-password
```

### EMAIL_TLS

If you are using Nodemailer as your mailer provider, you need to set this variable to your SMTP TLS setting.

```
EMAIL_TLS=true
```

### NEXT_PUBLIC_CAPTCHA_SITE_KEY

If you want to protect your endpoints using Cloudflare's Captcha, you need to set this variable to your Captcha site key.

```
NEXT_PUBLIC_CAPTCHA_SITE_KEY=your-captcha-site-key
```

### CAPTCHA_SECRET_TOKEN

If you want to protect your endpoints using Cloudflare's Captcha, you need to set this variable to your Captcha secret token.

```
CAPTCHA_SECRET_TOKEN=your-captcha-secret-token
```


Learn how to configure environment variables in the Next.js Supabase Starter Kit.

Environment Variables in the Next.js Supabase Starter Kit


The application configuration is set at `apps/web/config/app.config.ts`. This configuration stores some overall variables for your application.

This configuration is set at application-level. The configuration gets propagated to the packages that the app imports, so you can control the behavior and logic of the package. This also allows you to host multiple apps in the same monorepo, as every application defines its own configuration.

The recommendation is **to not update this directly** - instead, please define the environment variables below and override the default behavior. The configuration is validated using the Zod schema `AppConfigSchema`, so if something is off, you'll see the errors.

```tsx
const appConfig = AppConfigSchema.parse({
  name: process.env.NEXT_PUBLIC_PRODUCT_NAME,
  title: process.env.NEXT_PUBLIC_SITE_TITLE,
  description: process.env.NEXT_PUBLIC_SITE_DESCRIPTION,
  url: process.env.NEXT_PUBLIC_SITE_URL,
  locale: process.env.NEXT_PUBLIC_DEFAULT_LOCALE,
  theme: process.env.NEXT_PUBLIC_DEFAULT_THEME_MODE,
  themeColor: process.env.NEXT_PUBLIC_THEME_COLOR,
  themeColorDark: process.env.NEXT_PUBLIC_THEME_COLOR_DARK,
  production,
});
```

For example, to set the product name and app URL, you'd update the variables:

```bash
NEXT_PUBLIC_SITE_URL=https://myapp.com
NEXT_PUBLIC_PRODUCT_NAME="My wonderful AI App"
```

Learn how to setup the overall settings of your Next.js Supabase application

Setting your application configuration


Makerkit supports three different authentication methods:

1. **Password** - the traditional email/password method, set to `true` by default
2. **Magic Link** - magic link, set to `false` by default
3. **oAuth** - oAuth providers, by default we set Google Auth

The authentication configuration is set at `apps/web/config/auth.config.ts`.

The recommendation is **to not update this directly** - instead, please define the environment variables below and override the default behavior. The configuration is validated using the Zod schema `AuthConfigSchema`, so if something is off, you'll see the errors.

```tsx
const authConfig = AuthConfigSchema.parse({
  // NB: This is a public key, so it's safe to expose.
  // Copy the value from the Supabase Dashboard.
  captchaTokenSiteKey: process.env.NEXT_PUBLIC_CAPTCHA_SITE_KEY,

  // whether to display the terms checkbox during sign-up
  displayTermsCheckbox:
    process.env.NEXT_PUBLIC_DISPLAY_TERMS_AND_CONDITIONS_CHECKBOX === 'true',

  // NB: Enable the providers below in the Supabase Console
  // in your production project
  providers: {
    password: process.env.NEXT_PUBLIC_AUTH_PASSWORD === 'true',
    magicLink: process.env.NEXT_PUBLIC_AUTH_MAGIC_LINK === 'true',
    oAuth: ['google'],
  },
} satisfies z.infer<typeof AuthConfigSchema>);
```

For example, if you wanted to switch from password auth to magic link, you'd set the below variables:

```bash
NEXT_PUBLIC_AUTH_PASSWORD=false
NEXT_PUBLIC_AUTH_MAGIC_LINK=true
```

## Third Party Providers

To display third-party providers in the UI, you need to set the `oAuth` array to include the provider you want to display. The default is Google.

```tsx
providers: {
  oAuth: ['google'],
}
```

**The configuration is done on Supabase's side - not on Makerkit's side**.

Third Party providers need to be configured, managed and enabled fully on the provider's and Supabase's side. Makerkit does not need any configuration (beyond setting the provider to be displayed in the UI).

Please [read Supabase's documentation](https://supabase.com/docs/guides/auth/social-login) on how to set up third-party providers.

For local development, also check out [Supabase's documentation on how to set up OAuth providers locally](https://supabase.com/docs/guides/cli/managing-config).

### Scopes

Scopes are used to request specific permissions from the user. Different providers support and require different scopes.

To add your required scopes, please specify them in the `OAuthProviders` component.

```tsx title="packages/features/auth/src/components/oauth-providers.tsx"
/**
 * @name OAUTH_SCOPES
 * @description
 * The OAuth scopes are used to specify the permissions that the application is requesting from the user.
 *
 * Please add your OAuth providers here and the scopes you want to use.
 *
 * @see https://supabase.com/docs/guides/auth/social-login
 */
const OAUTH_SCOPES: Partial<Record<Provider, string>> = {
  azure: 'email',
  // add your OAuth providers here
};
```

For example, if you want to request the user's email address, you can add the `email` scope to the Google provider.

```tsx title="packages/features/auth/src/components/oauth-providers.tsx"
const OAUTH_SCOPES: Partial<Record<Provider, string>> = {
  azure: 'email',
  google: 'email',
};
```

## Password Requirements

To set the password requirements, you can set the following environment variables:

```bash
NEXT_PUBLIC_PASSWORD_REQUIRE_UPPERCASE=true
NEXT_PUBLIC_PASSWORD_REQUIRE_NUMBERS=true
NEXT_PUBLIC_PASSWORD_REQUIRE_SPECIAL_CHARS=true
```

The above will enforce the following rules:
1. At least one uppercase letter
2. At least one number
3. At least one special character

## Displaying Terms and Conditions

To display the terms and conditions checkbox during sign-up, set the following environment variable:

```bash
NEXT_PUBLIC_DISPLAY_TERMS_AND_CONDITIONS_CHECKBOX=true
```

This is off by default.

Learn how to setup the authentication configuration of your Next.js Supabase application

Setting your authentication configuration


The paths configuration is set at `apps/web/config/paths.config.ts`. This configuration stores all the paths that you'll be using in your application. It is a convenient way to store them in a central place rather than scatter them in the codebase using magic strings.

The configuration is validated using the Zod schema `PathsSchema`, so if something is off, you'll see the errors.

It **is unlikely you'll need to change this** unless you're heavily editing the codebase.

```tsx
const pathsConfig = PathsSchema.parse({
  auth: {
    signIn: '/auth/sign-in',
    signUp: '/auth/sign-up',
    verifyMfa: '/auth/verify',
    callback: '/auth/callback',
    passwordReset: '/auth/password-reset',
    passwordUpdate: '/update-password',
  },
  app: {
    home: '/home',
    personalAccountSettings: '/home/settings',
    personalAccountBilling: '/home/billing',
    personalAccountBillingReturn: '/home/billing/return',
    accountHome: '/home/[account]',
    accountSettings: `/home/[account]/settings`,
    accountBilling: `/home/[account]/billing`,
    accountMembers: `/home/[account]/members`,
    accountBillingReturn: `/home/[account]/billing/return`,
    joinTeam: '/join',
  },
} satisfies z.infer<typeof PathsSchema>);
```

Learn how to setup the paths configuration of your Next.js Supabase application

Setting your paths configuration


The features flags configuration is set at `apps/web/config/feature-flags.config.ts`. We use this configuration to store feature flags, i.e. to enable or disable certain features in the app.

This configuration is set at application level. The configuration gets propagated to the packages that the app imports, so you can control the behavior and logic of the package. This also allows you to host multiple apps in the same monorepo, as every application defines its own configuration.

The recommendation is **to not update this directly** - instead, please define the environment variables below and override the default behavior. The configuration is validated using the Zod schema `FeatureFlagsSchema`, so if something is off, you'll see the errors.

```tsx

const featuresFlagConfig = FeatureFlagsSchema.parse({
  enableThemeToggle: getBoolean(
    process.env.NEXT_PUBLIC_ENABLE_THEME_TOGGLE,
    true,
  ),
  enableAccountDeletion: getBoolean(
    process.env.NEXT_PUBLIC_ENABLE_PERSONAL_ACCOUNT_DELETION,
    false,
  ),
  enableTeamDeletion: getBoolean(
    process.env.NEXT_PUBLIC_ENABLE_TEAM_ACCOUNTS_DELETION,
    false,
  ),
  enableTeamAccounts: getBoolean(
    process.env.NEXT_PUBLIC_ENABLE_TEAM_ACCOUNTS,
    true,
  ),
  enableTeamCreation: getBoolean(
    process.env.NEXT_PUBLIC_ENABLE_TEAM_ACCOUNTS_CREATION,
    true,
  ),
  enablePersonalAccountBilling: getBoolean(
    process.env.NEXT_PUBLIC_ENABLE_PERSONAL_ACCOUNT_BILLING,
    false,
  ),
  enableTeamAccountBilling: getBoolean(
    process.env.NEXT_PUBLIC_ENABLE_TEAM_ACCOUNTS_BILLING,
    false,
  ),
  languagePriority: process.env
    .NEXT_PUBLIC_LANGUAGE_PRIORITY as LanguagePriority,
  enableNotifications: getBoolean(
    process.env.NEXT_PUBLIC_ENABLE_NOTIFICATIONS,
    true,
  ),
  realtimeNotifications: getBoolean(
    process.env.NEXT_PUBLIC_REALTIME_NOTIFICATIONS,
    false,
  ),
  enableVersionUpdater: getBoolean(
    process.env.NEXT_PUBLIC_ENABLE_VERSION_UPDATER,
    false,
  ),
} satisfies z.infer<typeof FeatureFlagsSchema>);

export default featuresFlagConfig;
```

You can update the following environment variables to override the default behavior:

```bash
NEXT_PUBLIC_ENABLE_THEME_TOGGLE=
NEXT_PUBLIC_ENABLE_PERSONAL_ACCOUNT_DELETION=
NEXT_PUBLIC_ENABLE_TEAM_ACCOUNTS=
NEXT_PUBLIC_ENABLE_TEAM_ACCOUNTS_DELETION=
NEXT_PUBLIC_ENABLE_TEAM_ACCOUNTS_CREATION=
NEXT_PUBLIC_ENABLE_PERSONAL_ACCOUNT_BILLING=
NEXT_PUBLIC_ENABLE_TEAM_ACCOUNTS_BILLING=
NEXT_PUBLIC_LANGUAGE_PRIORITY=
NEXT_PUBLIC_ENABLE_NOTIFICATIONS=
NEXT_PUBLIC_REALTIME_NOTIFICATIONS=
NEXT_PUBLIC_ENABLE_VERSION_UPDATER=
```

### Explanation

1. **NEXT_PUBLIC_ENABLE_THEME_TOGGLE**: use this feature if you want to set a specific theme mode (dark or light) and disallow switching to another mode
2. **NEXT_PUBLIC_ENABLE_PERSONAL_ACCOUNT_DELETION**: use this feature flag if you don't want users to self-delete their accounts
3. **NEXT_PUBLIC_ENABLE_TEAM_ACCOUNTS**: use this feature flag to enable or disable team accounts. For B2C apps, disabling may be your preference.
4. **NEXT_PUBLIC_ENABLE_TEAM_ACCOUNTS_DELETION**: use this feature flag if you don't want users to self-delete their team accounts
5. **NEXT_PUBLIC_ENABLE_TEAM_ACCOUNTS_CREATION**: use this feature flag to prevent users from creating a team account. This can be useful if you wish to manage the onboarding yourself.
6. **NEXT_PUBLIC_ENABLE_PERSONAL_ACCOUNT_BILLING**: use this feature to enable or disable the ability of personal accounts to subscribe to a plan.
7. **NEXT_PUBLIC_ENABLE_TEAM_ACCOUNTS_BILLING**: use this feature to enable or disable the ability of team accounts to subscribe to a plan.
8. **NEXT_PUBLIC_LANGUAGE_PRIORITY**: use this feature to set the language priority. If set to `user`, the user's preferred language will be used. If set to `application`, the application's default language will be used.
9. **NEXT_PUBLIC_ENABLE_NOTIFICATIONS**: use this feature to enable or disable notifications in the app.
10. **NEXT_PUBLIC_REALTIME_NOTIFICATIONS**: use this feature to enable or disable real-time notifications in the app.
11. **NEXT_PUBLIC_ENABLE_VERSION_UPDATER**: use this feature to enable or disable the version updater in the app.

### Note

It is unlikely that both `NEXT_PUBLIC_ENABLE_PERSONAL_ACCOUNT_BILLING` and `NEXT_PUBLIC_ENABLE_TEAM_ACCOUNTS_BILLING` would both be enabled at once. In most cases, you want to enable it for users or team accounts.


Learn how to setup the feature flags configuration of your Next.js Supabase application

Setting your feature flags configuration


The personal account navigation is set at `apps/web/config/personal-account-navigation.config.tsx`. We use this configuration to define the navigation menu of the personal account. By default, it has three routes: home page, settings, and billing (if enabled).

We define it in one place so we can build different views at once (for example, the mobile menu).

**Please update this file to add more routes to the sidebar.**

```tsx title="apps/web/config/personal-account-navigation.config.tsx"
const routes = [
  {
    label: 'common:homeTabLabel',
    path: pathsConfig.app.home,
    Icon: <Home className={iconClasses} />,
    end: true,
  },
  {
    label: 'account:accountTabLabel',
    path: pathsConfig.app.personalAccountSettings,
    Icon: <User className={iconClasses} />,
  },
];

if (featureFlagsConfig.enablePersonalAccountBilling) {
  routes.push({
    label: 'common:billingTabLabel',
    path: pathsConfig.app.personalAccountBilling,
    Icon: <CreditCard className={iconClasses} />,
  });
}

export const personalAccountSidebarConfig = SidebarConfigSchema.parse({
  routes,
  style: process.env.NEXT_PUBLIC_USER_NAVIGATION_STYLE,
});
```

You can choose the style of the navigation by setting the `NEXT_PUBLIC_USER_NAVIGATION_STYLE` environment variable. The default style is `sidebar`.

```bash
NEXT_PUBLIC_USER_NAVIGATION_STYLE=sidebar
```

Alternatively, you can set the style to `header`:

```bash
NEXT_PUBLIC_TEAM_NAVIGATION_STYLE=header
```



Learn how to setup the personal account navigation of your Next.js Supabase application

Setting your personal account navigation configuration


The team account navigation is set at `apps/web/config/team-account-navigation.config.tsx`. We use this configuration to define the menu of the team account. By default, it has four routes: dashboard, settings, members, and billing (if enabled).

We define it in one place so we can build different views at once (for example, the mobile menu).

**Please update this file to add more routes to the sidebar.**

```tsx title="apps/web/config/team-account-navigation.config.tsx"
const getRoutes = (account: string) => [
  {
    label: 'common:dashboardTabLabel',
    path: pathsConfig.app.accountHome.replace('[account]', account),
    Icon: <LayoutDashboard className={iconClasses} />,
    end: true,
  },
  {
    label: 'common:settingsTabLabel',
    collapsible: false,
    children: [
      {
        label: 'common:settingsTabLabel',
        path: createPath(pathsConfig.app.accountSettings, account),
        Icon: <Settings className={iconClasses} />,
      },
      {
        label: 'common:accountMembers',
        path: createPath(pathsConfig.app.accountMembers, account),
        Icon: <Users className={iconClasses} />,
      },
      featureFlagsConfig.enableTeamAccountBilling
        ? {
            label: 'common:billingTabLabel',
            path: createPath(pathsConfig.app.accountBilling, account),
            Icon: <CreditCard className={iconClasses} />,
          }
        : undefined,
    ].filter(Boolean),
  },
];

export function getTeamAccountSidebarConfig(account: string) {
  return SidebarConfigSchema.parse({
    routes: getRoutes(account),
    style: process.env.NEXT_PUBLIC_TEAM_NAVIGATION_STYLE,
  });
}

function createPath(path: string, account: string) {
  return path.replace('[account]', account);
}
```

You can choose the style of the navigation by setting the `NEXT_PUBLIC_TEAM_NAVIGATION_STYLE` environment variable. The default style is `sidebar`.

```bash
NEXT_PUBLIC_TEAM_NAVIGATION_STYLE=sidebar
```

Alternatively, you can set the style to `header`:

```bash
NEXT_PUBLIC_TEAM_NAVIGATION_STYLE=header
```

Learn how to setup the team account navigation of your Next.js Supabase application

Setting your team account navigation configuration

How to fetch and write data to the server

Communicating with the Server


Before diving into the various ways we can communicate with the server, we need to introduce how we communicate with Supabase, which is hosting the database and therefore the source of our data.

## Using the Supabase client

Depending on whether you are running your code in the browser or on the server, you will need to use different clients to interact with Supabase.

### Using the Supabase client in the browser

To import the Supabase client in a browser environment,  you can use the `useSupabase` hook:

```tsx
import { useSupabase } from '@kit/supabase/hooks/use-supabase';

export default function Home() {
  const supabase = useSupabase()

  return (
    <div>
      <h1>Supabase Browser Client</h1>
      <button onClick={() => supabase.auth.signOut()}>Sign Out</button>
    </div>
  )
}
```

### Using the Supabase client in a Server environment

To import the Supabase client in a server environment, you can use the `getSupabaseServerClient` function, and you can do the same across all server environments like Server Actions, Route Handlers, and Server Components:

```tsx
import { getSupabaseServerClient } from '@kit/supabase/server-client';

export async function myServerAction() {
  const supabase = getSupabaseServerClient();

  const { data, error } = await supabase.from('users').select('*')

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

To use the Server Admin, e.g. an admin client with elevated privileges, you can use the `getSupabaseServerAdminClient` function:

```tsx
import { getSupabaseServerAdminClient } from '@kit/supabase/server-admin-client';

export async function myServerAction() {
  const supabase = getSupabaseServerAdminClient();

  const { data, error } = await supabase.from('users').select('*')

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

NB: The `getSupabaseServerAdminClient` function should only be used in server environments, as it requires the `SUPABASE_SERVICE_ROLE_KEY` environment variable to be set. Additionally, it should only be used in very exceptional cases, as it has elevated privileges. In most cases, please use the `getSupabaseServerClient` function.

### DEPRECATED: Older Versions of the Kit

In older versions of the kit, you may see different ways of importing the Supabase client. The code below will work, but please note that it is deprecated and will be removed in future versions of the kit.

Depending on where your code runs, you may need to use different clients to interact with Supabase. This is due to how cookies are set differently in various parts of the Next.js application.

You can use 4 different clients to interact with Supabase:

1. **Browser** - This runs in the browser and is used to interact with Supabase from the client
2. **Server Actions** - This runs in Server Actions and is used to interact with Supabase from the server
3. **Route Handlers** - This runs in Route Handlers and is used to interact with Supabase from the server
4. **Server Components** - This runs in Server Components and is used to interact with Supabase from the server

## Browser

To use the browser client, use the `useSupabase` hook:

```tsx
import { useSupabase } from '@kit/supabase/hooks/use-supabase';

export default function Home() {
  const supabase = useSupabase()

  return (
    <div>
      <h1>Supabase Browser Client</h1>
      <button onClick={() => supabase.auth.signOut()}>Sign Out</button>
    </div>
  )
}
```

## Server Actions

To use the server actions client, use the `useSupabase` hook:

```tsx
'use server';

import { getSupabaseServerActionClient } from '@kit/supabase/server-actions-client';

export async function myServerAction() {
  const supabase = getSupabaseServerActionClient();

  const { data, error } = await supabase.from('users').select('*')

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

## Route Handlers

To use the route handlers client, use the `getSupabaseRouteHandlerClient` function:

```tsx
import { NextRequest, NextResponse } from 'next/server';
import { getSupabaseRouteHandlerClient } from '@kit/supabase/route-handlers-client';

export async function POST(req: NextRequest) {
  const supabase = getSupabaseRouteHandlerClient();

  const { data, error } = await supabase.from('users').select('*')

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

## Server Components

To use the server components client, use the `getSupabaseServerComponentClient` function:

```tsx
import { getSupabaseServerComponentClient } from '@kit/supabase/server-component-client';

export default async function TasksPage() {
  const supabase = getSupabaseServerComponentClient();

  const { data, error } = await supabase.from('users').select('*');

  return <TasksList tasks={data} />
}
```

Supabase Clients


Server Actions help us communicate with the server just by creating normal Javascript functions that Next.js converts to server POST endpoints. They are particularly useful to mutate data and revalidate the data that we fetched from Server Components.

Generally speaking, there is nothing special in Makerkit compared to any other Next.js application in how you will use Server Actions. However, I want to introduce you to a nifty utility to make your life easier while writing Server Actions: `enhanceAction`.

Let's first introduce Server Actions.

In the large majority of cases - you will be writing React Server Actions to update data in your DB. Server Actions are used to perform mutations on the server-side - while being called like normal functions.

To create a server action, it's enough to add `use server` at the top of the file and export the function.

```tsx
'use server';

// I am now a server action!
export const myServerAction = async function () {
  // ... your code here
  return {
    success: true,
  };
};
```

The above is a plain POST request that basically does nothing. Let's see how we can make it more useful.

Makerkit ships with a utility to help you write these actions. The utility is called `enhanceAction` and we import it from `@kit/next/actions`.

```tsx
import { enhanceAction } from '@kit/next/actions';
```

This utility helps us with three main things:
1. checks the user state (if the user is authenticated)
2. given a Zod schema, it validates the request body
3. given a captcha site key, it validates the captcha token
4. if you configured a monitoring provider, it sends the caught exception to the monitoring provider

Fantastic, let's see how we can use it.

```tsx
'use server';

import { z } from 'zod';
import { enhanceAction } from '@kit/next/actions';

const ZodSchema = z.object({
  email: z.string().email(),
  password: z.string().min(6),
});

export const myServerAction = enhanceAction(
  async function (data, user) {
    // 1. "data" has been validated against the Zod schema, and it's safe to use
    // 2. "user" is the authenticated user
    
    // ... your code here
    return {
      success: true,
    };
  },
  {
    schema: ZodSchema,
  },
);
```

### Using a Captcha token protection

If you want to protect your server actions with a captcha token, you can do so by passing the captcha site token to the `enhanceAction` function and setting the `captcha` flag to `true`.

```tsx
'use server';

import { enhanceAction } from '@kit/next/actions';

export const myServerAction = enhanceAction(
  async function (data, user) {
    // ... your code here
    return {
      success: true,
    };
  },
  {
    captcha: true,
    schema: ZodSchema,
  },
);
```

When calling the server action, we must supply the captcha token in the request body.

The captcha token can be retrieved from the `useCaptchaToken` hook in the package `@kit/auth/captcha/client`.

```tsx
import { useCaptchaToken } from '@kit/auth/captcha/client';

function Component() {
  const captchaToken = useCaptchaToken();
  
  // ... your code here
}
```

Now, when calling the server action, we can pass the captcha

```tsx
import { useCaptchaToken } from '@kit/auth/captcha/client';

function Component() {
  const captchaToken = useCaptchaToken();
  
  const onSubmit = async (params: {
    email: string;
    password: string;
  }) => {
    const response = await myServerAction({
      ...params,
      captchaToken,
    });
    
    // ... your code here
  };
}
```

NB: to use Captcha protection, you need to set the captcha token in the environment variables.

```bash
CAPTCHA_SECRET_TOKEN=
NEXT_PUBLIC_CAPTCHA_SITE_KEY=
```

As a secret environment variable, please do not add it to the `.env` file. Instead, add it to the environment variables of your CI/CD system.

The only captcha provider supported is Cloudflare Turnstile.

#### Passing the Captcha Token

NB: you must pass the captcha token in the request body when calling the server action. The function's type checker will ensure that you pass the captcha token as it will error out if the token is not defined in the Zod schema as `captchaToken`.

## Capturing Exceptions

This function **automatically reports uncaught exceptions** if you configured a monitoring provider. The monitoring provider is set in the environment variable `MONITORING_PROVIDER`.

To disable it, pass `captureException: false` to the `enhanceAction` function.

```tsx {14}
'use server';

import { enhanceAction } from '@kit/next/actions';

export const myServerAction = enhanceAction(
  async function (data, user) {
    // ... your code here
    return {
      success: true,
    };
  },
  {
    captcha: true,
    captureException: false,
    schema: ZodSchema,
  },
);
```

Learn how to write Server Actions to mutate and revalidate your data

Using Server Actions in the Next.js Supabase SaaS Kit


API Route handlers are added using the convention `route.ts` and exporting one or many HTTP methods (e.g., `GET`, `POST`, `PUT`, `DELETE`).

While you won't be writing too many API route handlers (prefer Server Actions for mutations) - you can use the `enhanceRouteHandler` utility to help you with the following:

1. checks the user state (if the user is authenticated)
2. given a Zod schema, it validates the request body
3. given a captcha site key, it validates the captcha token
4. report an uncaught exception to the monitoring provider (if configured)

Fantastic, let's see how we can use it.

```tsx
import { z } from 'zod';

import { enhanceRouteHandler } from '@kit/next/routes';
import { NextResponse } from 'next/server';

const ZodSchema = z.object({
  email: z.string().email(),
  password: z.string().min(6),
});

export const POST = enhanceRouteHandler(
  async function({ body, user, request }) {
    // 1. "body" has been validated against the Zod schema, and it's safe to use
    // 2. "user" is the authenticated user
    // 3. "request" is the request object that contains the headers, query, etc.

    // ... your code here
    return NextResponse.json({
      success: true,
    });
  },
  {
    schema: ZodSchema,
  },
);
```

### Using a Captcha token protection

If you want to protect your API route handlers with a captcha token, you can do so by passing the captcha site token to the `enhanceRouteHandler` function and setting the `captcha` flag to `true`.

```tsx
import { enhanceRouteHandler } from '@kit/next/routes';

export const POST = enhanceRouteHandler(
  async function({ body, user, request }) {
    // ... your code here
    return NextResponse.json({
      success: true,
    });
  },
  {
    captcha: true,
    schema: ZodSchema,
  },
);
```

When calling the API route handler, we must supply the captcha token in the request body.

The captcha token can be retrieved from the `useCaptchaToken` hook in the package `@kit/auth/captcha/client`.

```tsx
import { useCaptchaToken } from '@kit/auth/captcha/client';

function Component() {
  const captchaToken = useCaptchaToken();
  
  // ... your code here
}
```

Now, when calling the API route handler, we can pass the captcha and the CSRF token.

NB: The CSRF token **must be added for all API routes** making mutations in routes that are outside `/api/*`. Routes inside `/api/*` are not protected by default as they're meant to be used externally.

```tsx
import { useCaptchaToken } from '@kit/auth/captcha/client';
import { useCsrfToken } from '@kit/shared/hooks';

function Component() {
  const captchaToken = useCaptchaToken();
  const csrfToken = useCsrfToken();
  
  const onSubmit = async (params: {
    email: string;
    password: string;
  }) => {
    const response = await fetch('/my-api-route', {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'x-csrf-token': csrfToken,
        'x-captcha-token': captchaToken,
      },
      body: JSON.stringify(params),
    });
    
    // ... your code here
  };
  
  // ... your code here
}
```

You can improve the above using React Query:

```tsx
import { useMutation } from '@tanstack/react-query';
import { useCaptchaToken } from '@kit/auth/captcha/client';

function Component() {
  const captchaToken = useCaptchaToken();
  const mutation = useMutateData();

  const onSubmit = async (params: {
    email: string;
    password: string;
  }) => {
    await mutation.mutateAsync(params);
  };
  
  // ... your code here
}

function useMutateData() {
  return useMutation({
    mutationKey: 'my-mutation',
    mutationFn: async (params: { email: string; password: string }) => {
      const response = await fetch('/my-api-route', {
        method: 'POST',
        headers: {
          'Content-Type': 'application/json',
          'x-captcha-token': captchaToken,
        },
        body: JSON.stringify(params),
      });
      
      if (!response.ok) {
        throw new Error('An error occurred');
      }

      return response.json();
    },
  });
}
```

NB: to use Captcha protection, you need to set the captcha token in the environment variables.

```bash
CAPTCHA_SECRET_TOKEN=
NEXT_PUBLIC_CAPTCHA_SITE_KEY=
```

As a secret environment variable, please do not add it to the `.env` file. Instead, add it to the environment variables of your CI/CD system.

The only captcha provider supported is Cloudflare Turnstile.

## Capturing Exceptions

This function **automatically reports uncaught exceptions** if you configured a monitoring provider. The monitoring provider is set in the environment variable `MONITORING_PROVIDER`.

To disable it, pass `captureException: false` to the `enhanceAction` function.

```tsx {12}
import { enhanceRouteHandler } from '@kit/next/routes';

export const POST = enhanceRouteHandler(
  async function({ body, user, request }) {
    // ... your code here
    return NextResponse.json({
      success: true,
    });
  },
  {
    captcha: true,
    captureException: false,
    schema: ZodSchema,
  },
);
```

Learn how to write Route Handlers in the Next.js Supabase SaaS Kit to fetch and write data

Using API Route Handlers in the Next.js Supabase SaaS Kit


Server Components are the primary way we fetch and render data in the Next.js Supabase SaaS kit. 

When you create a new page and want to fetch some data, Server Components are the perfect place where to fetch it: it is done when you render your page (which means one less round-trip) and the data is streamed to the client (so it's very fast).

In Next.js, every component is a Server Component, unless you specify `use client`, which converts it to a client component. Client components are also server-rendered, however they're also rendered on the client. Server Components are only rendered on the server - so we can use data-fetching methods (using Supabase, in our case) and fetch all the required data for a particular layout or page.

For example, let's assume we have a page that displayes a list of tasks from a `tasks` table. This is a Next.js page, and therefore a Server Component. This means, it runs on the server and on the server only, and we can use to fetch data and render it streamed to the client. The client will never run the React code in this component: it will receive it and render it.

```tsx
export default async function TasksPage() {}
```

Let's now fetch some data from Supabase. To do so, we use the server component client.

```tsx
const supabase = getSupabaseServerClient();

const { data, error } = await supabase.from('tasks').select('*');
```

Now, let's put it all together:

```tsx
export default async function TasksPage() {
  const supabase = getSupabaseServerClient();

  const { data, error } = await supabase.from('tasks').select('*');

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

  return <TasksList data={data}>
}
```

As you can see, we are fetching data and rendering it in `TasksList`. All on the server.

Fetching data from Server Components


By default, all POST, PUT, PATCH and DELETE requests to your API routes are protected against CSRF attacks. This means that you need to send a CSRF token with your requests, otherwise they will be rejected.

There are two exceptions to this rule:

1. When using Server Actions, protection is built-in and you don't need to worry about it.
2. When the route is under the `api` path. In this case, the CSRF protection is disabled, since we use this prefix for webhooks or external services that need to access your API.

When using requests against API Route Handlers, you need to pass the CSRF token with your requests, otherwise the middleware will reject them.

To retrieve the CSRF token, you can use the `useGetCsrfToken` function from `@kit/shared/hooks`:

```tsx
'use client';

function MyComponent() {
  const csrfToken = useGetCsrfToken();

  const handleSubmit = async (e) => {
    e.preventDefault();

    const response = await fetch('/my-endpoint', {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'X-CSRF-Token': csrfToken,
      },
      body: JSON.stringify({ message: 'Hello, world!' }),
    });
  };

  // your component code
}
```

CSRF Protection for your API Routes


For captcha protection, we use Cloudflare Turnstile. To enable it, you need to set the following environment variables:

```bash
CAPTCHA_SECRET_TOKEN=
NEXT_PUBLIC_CAPTCHA_SITE_KEY=
```

You can find the `CAPTCHA_SECRET_TOKEN` in the Turnstile configuration. The `NEXT_PUBLIC_CAPTCHA_SITE_KEY` is public and safe to share. Instead, the `CAPTCHA_SECRET_TOKEN` should be kept secret.

This guide assumes you have correctly set up your Turnstile configuration. If you haven't, please refer to the [Turnstile documentation](https://developers.cloudflare.com/turnstile).

## Authentication

When you set the token in the environment variables, the kit will automatically protect your API routes with captcha.

**NB**: you also need to set the token in the Supabase Dashboard!

## Retrieving the Token

To retrieve the captcha token, you can use the `useCaptchaToken` function from `@kit/auth/captcha/client`:

```tsx
import { useCaptchaToken } from '@kit/auth/captcha/client';

function MyComponent() {
  const { captchaToken } = useCaptchaToken();

  const handleSubmit = async (e) => {
    e.preventDefault();

    const response = await fetch('/my-endpoint', {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'x-captcha-token': captchaToken,
      },
      body: JSON.stringify({ message: 'Hello, world!' }),
    });
  };

  // your component code
}
```

When using Server Actions, use `enhanceAction` from `@kit/next/actions`:

```tsx
const MySchema = z.object({
  message: z.string(),
  captchaToken: z.string().min(1),
});

export const myServerAction = enhanceAction(async (data) => {
  // your action code
}, {
  captha: true,
  schema: MySchema
});
```

When calling the server action, you need to pass the captcha:

```tsx
function MyForm() {
  const { captchaToken, resetCaptchaToken } = useCaptchaToken();

  const handleSubmit = async (e) => {
    e.preventDefault();

    try {
       const response = await myServerAction({
        message: 'Hello, world!',
        captchaToken,
      });
    } finally {
      // always reset the token!
      resetCaptchaToken();
    }
  };

  // your component code
}
```

A token is valid for one request only. You need to reset the token after each request.

The library will take care of renewing the token automatically when needed - but you need to reset it manually when consuming the token.

## Resetting the Token

The underlying library [React Turnstile](https://github.com/marsidev/react-turnstile) resets the token automatically - but we need to reset it manually when actually consuming the token since the token is only valid for one request. 

To reset the token, please call `resetCaptchaToken` from the `useCaptchaToken` hook - as shown in the example above.

You should be doing so in all situations, whether the request was successful or not.

## Verifying the Token

To verify the captcha manually server-side, please use the following code:

```tsx
import { verifyCaptchaToken } from '@kit/auth/captcha/server';

function assertCaptchaValidity(request: Request) {
  const token = request.headers.get('x-captcha-token');

  await verifyCaptchaToken(token);
}
```

If you use the utilities provided by the kit `enhanceAction` and `enhanceRouteHandler`, you don't need to worry about this, as the kit will automatically verify the captcha token for you (as long as it is passed).


Captcha Protection for your API Routes


You can use the Account API for retrieving information about the personal user account.

## Using the Account API

To use the Account API, you need to import the `createAccountsApi` function from `@kit/account/api`. We need to pass a valid `SupabaseClient` to the function - so we can interact with the database from the server.

```tsx
import { createAccountsApi } from '@kit/accounts/api';
import { getSupabaseServerClient } from '@kit/supabase/server-client';

async function ServerComponent() {
  const client = getSupabaseServerClient();
  const api = createAccountsApi(client);

  // use api
}
```

If you're in a Server Action context, you'd use:

```tsx
'use server';

import { createAccountsApi } from '@kit/accounts/api';
import { getSupabaseServerClient } from '@kit/supabase/server-client';

export async function myServerAction() {
  const client = getSupabaseServerClient();
  const api = createAccountsApi(client);
  
  // use api
}
```

## Methods

The Account API provides the following methods:

### Get the account workspace data

Get the account workspace data using the `getAccountWorkspace` method. This method returns the workspace data for the user account.

```tsx
const api = createAccountsApi(client);
const workspace = await api.getAccountWorkspace();
```

This is already called in the user account layout, so it's very unlikely you'll need to call this method.

### Load the user accounts

Load the user accounts using the `loadUserAccounts` method.

This method returns an array of user accounts. Each account has a `label`, `value`, and `image` property.

```tsx
const api = createAccountsApi(client);
const accounts = await api.loadUserAccounts();
```

### Get the subscription data

Get the subscription data for the given user using the `getSubscription` method.

This method returns the subscription data for the given user account.

```tsx
const api = createAccountsApi(client);
const subscription = await api.getSubscription(accountId);
```

Returns the table `subscriptions` and `subscription_items`.

### Get the billing customer ID

Get the billing customer ID for the given user using the `getCustomerId` method.

This method returns the billing customer ID for the given user account.

```tsx
const api = createAccountsApi(client);
const customerId = await api.getCustomerId(accountId);
```

A quick introduction to the Account API in Makerkit

Account API


You can use the Team Account API for retrieving information about the team account.

## Using the Team Account API

To use the Team Account API, you need to import the `createTeamAccountsApi` function from `@kit/team-account/api`.

We need to pass a valid `SupabaseClient` to the function - so we can interact with the database from the server.

```tsx
import { createTeamAccountsApi } from '@kit/team-accounts/api';
import { getSupabaseServerClient } from '@kit/supabase/server-client';

async function ServerComponent() {
  const client = getSupabaseServerClient();
  const api = createTeamAccountsApi(client);

  // use api
}
```

If you're in a Server Action context, you'd use:

```tsx
'use server';

import { createTeamAccountsApi } from '@kit/team-accounts/api';
import { getSupabaseServerClient } from '@kit/supabase/server-client';

export async function myServerAction() {
  const client = getSupabaseServerClient();
  const api = createTeamAccountsApi(client);

  // use api
}
```

## Methods

The Account API provides the following methods:

### Get the team account by ID

Retrieves the team account by ID using the `getTeamAccountById` method.

You can also use this method to check if the user is already in the account.

```tsx
const api = createTeamAccountsApi(client);
const account = await api.getTeamAccountById('account-id');
```

### Get the team account subscription

Get the subscription data for the account using the `getSubscription` method.

```tsx
const api = createTeamAccountsApi(client);
const subscription = await api.getSubscription('account-id');
```

### Get the team account order

Get the orders data for the given account using the `getOrder` method.

```tsx
const api = createTeamAccountsApi(client);
const order = await api.getOrder('account-id');
```

### Get the account workspace data

Get the account workspace data.

```tsx
const api = createTeamAccountsApi(client);
const workspace = await api.getAccountWorkspace('account-slug');
```

This method is already called in the account layout and is unlikely to be used in other contexts. This is used to hydrate the workspace data in the context.

Since it's already loaded, you can use the data from the context.

### Checking a user's permission within an account

Check if the user has permission to perform a specific action within the account using the `hasPermission` method.

```tsx
const api = createTeamAccountsApi(client);

const hasPermission = await api.hasPermission({
  accountId: 'account-id',
  userId: 'user-id',
  permission: 'billing.manage',
});
```

### Getting the members count in the account

Get the number of members in the account using the `getMembersCount` method.

```tsx
const api = createTeamAccountsApi(client);
const membersCount = await api.getMembersCount('account-id');
```

### Get the billing customer ID

Get the billing customer ID for the given account using the `getCustomerId` method.

```tsx
const api = createTeamAccountsApi(client);
const customerId = await api.getCustomerId('account-id');
```

### Retrieve an invitation

Get the invitation data from the invite token.

```tsx
const api = createTeamAccountsApi(client);
const invitation = await api.getInvitation(adminClient, 'invite-token');
```

This method is used to get the invitation data from the invite token. It's used when the user is not yet part of the account and needs to be invited. The `adminClient` is used to read the pending membership. The method returns the invitation data if it exists, otherwise `null`.


A quick introduction to the Team Account API in Makerkit

Team Account API


To check if users are authed, or to retrieve information about the currently signed-in user, use the `requireUser` function:

```tsx
import { redirect } from 'next/navigation';
import { requireUser } from '@kit/supabase/require-user';

import { getSupabaseServerClient } from '@kit/supabase/server-client';

async function ServerComponent() {
  const client = getSupabaseServerClient();
  const auth = await requireUser(client);

  // check if the user needs redirect
  if (auth.error) {
    redirect(auth.redirectTo);
  }

  // user is authed!
  const user = auth.data;
}
```

NB: use the correct Supabase client based on the context. In this case, we use the server component client.

```tsx
'use server';

import { redirect } from 'next/navigation';
import { requireUser } from '@kit/supabase/require-user';
import { getSupabaseServerClient } from '@kit/supabase/server-client';

export async function myServerAction() {
  const client = getSupabaseServerClient();
  const auth = await requireUser(client);

  // check if the user needs redirect
  if (auth.error) {
    redirect(auth.redirectTo);
  }

  // user is authed!
  const user = auth.data;
}
```

If the user needs MFA and is not yet verified, the `redirect` function will redirect the user to the MFA verification page. This is why it is important to check the `redirectTo` property in the response.


A quick introduction to the Authentication API in Makerkit

Authentication API


When within the layout `/home/(user)` - you have access to data fetched from the user workspace API.

The data in this layout has most of the information you need around the currently selected account and the user.

To access the data, you can use the `loadUserWorkspace` loader function. This function is cached per-request, so you can call it multiple times without worrying about performance.

While multiple calls to this function are deduped within a single request, bear in mind that this request will be called when navigating to the page. If you only require a small subset of data, it would be best to make more granular requests.

```tsx
import { loadUserWorkspace } from '~/home/(user)/_lib/server/load-user-workspace';

export default async function SomeUserPage() {
  const data = await loadUserWorkspace();

  // use data
}
```

The data returned from the `loadUserWorkspace` function is an object with the following properties:

- `user`: The user object coming from Supabase Auth
- `workspace`: The account object of the user
- `accounts`: An array of all accounts the user is a member of

Here is an example of the data structure:

```tsx
import type { User } from '@supabase/supabase-js';

{
  workspace: {
    id: string | null;
    name: string | null;
    picture_url: string | null;
    public_data: Json | null;
    subscription_status: string | null;
  };

  user: User;

  accounts: Array<{
   id: string | null;
    name: string | null;
    picture_url: string | null;
    role: string | null;
    slug: string | null;
  }>;
}
```

The `workspace` object contains the following properties:
- `id`: The account ID
- `name`: The account name
- `picture_url`: The account picture URL
- `public_data`: The account public data
- `subscription_status`: The subscription status of the account. This can be 'active' | 'trialing' | 'past_due' | 'canceled' | 'unpaid' | 'incomplete' | 'incomplete_expired' | 'paused'.


## Accessing the User Workspace Data in Client Components

The data fetched from the user workspace API is available in the context. You can access this data using the `useUserWorkspace` hook.

```tsx
'use client';

import { useUserWorkspace } from '@kit/accounts/hooks/use-user-workspace';

export default function SomeComponent() {
  const { workspace, user, accounts } = useUserWorkspace();

  // use account, user, and accounts
}
```

The `useUserWorkspace` hook returns the same data structure as the `loadUserWorkspace` function.

NB: the hooks **is not to be used** is Server Components, only in Client Components. Additionally, this is only available in the pages under `/home/(user)` layout.


The user workspace API allows you to retrieve all the data related to the current user.

User Workspace API


When within the layout `/home/[account]` - you have access to data fetched from the account workspace API.

The data in this layout has most of the information you need around the currently selected account and the user.

## Accessing the Team Account Workspace Data in Server Components

To access the data, you can use the `loadTeamWorkspace` loader function. This function is cached per-request, so you can call it multiple times without worrying about performance.

While multiple calls to this function are deduped within a single request, bear in mind that this request will be called when navigating to the page. If you only require a small subset of data, it would be best to make more granular requests.

```tsx
import { loadTeamWorkspace } from '~/home/[account]/_lib/server/team-account-workspace.loader';

export default async function SomeAccountPage() {
  const data = await loadTeamWorkspace();

  // use data
}
```

The data returned from the `loadTeamWorkspace` function is an object with the following properties:

- `account`: The account object
- `user`: The user object coming from Supabase Auth
- `accounts`: An array of all accounts the user is a member of

Here is an example of the data structure:

```tsx
import type { User } from '@supabase/supabase-js';

{
  account: {
    id: string;
    name: string;
    picture_url: string;
    slug: string;
    role: string;
    role_hierarchy_level: number;
    primary_owner_user_id: string;
    subscription_status: string;
    permissions: string[];
  };

  user: User;

  accounts: Array<{
   id: string | null;
    name: string | null;
    picture_url: string | null;
    role: string | null;
    slug: string | null;
  }>;
}
```

The `account` object contains the following properties:
1. `id`: The account ID
2. `name`: The account name
3. `picture_url`: The account picture URL
4. `slug`: The account slug
5. `role`: The user's role in the account
6. `role_hierarchy_level`: The user's role hierarchy level
7. `primary_owner_user_id`: The primary owner user ID
8. `subscription_status`: The subscription status of the account. This can be 'active' | 'trialing' | 'past_due' | 'canceled' | 'unpaid' | 'incomplete' | 'incomplete_expired' | 'paused'.
9. `permissions`: An array of permissions the user has in the account

## Accessing the Account Workspace Data in Client Components

The data fetched from the account workspace API is available in the context. You can access this data using the `useAccountWorkspace` hook.

```tsx
'use client';

import { useTeamAccountWorkspace } from '@kit/team-accounts/hooks/use-team-account-workspace';

export default function SomeComponent() {
  const { account, user, accounts } = useTeamAccountWorkspace();

  // use account, user, and accounts
}
```

The `useTeamAccountWorkspace` hook returns the same data structure as the `loadTeamWorkspace` function.

NB: the hooks **is not to be used** is Server Components, only in Client Components. Additionally, this is only available in the pages under `/home/[account]` layout.

The account workspace API allows you to retrieve all the data related to the current account.

Account Workspace API

Customization


Makerkit uses [Shadcn UI](https://ui.shadcn.com) and it defines the theme according to its guidelines.

You can find the default theme inside the application at `apps/web/styles/global.css`.

If you want to override the default style, either define your own colors or pick a theme from the [Shadcn Themes page](https://ui.shadcn.com/themes), and copy/paste the theme into this file.

How to update the theme in your Makerkit application

Updating the Shadcn theme in your Makerkit Application


Of course - you'd like to have your own logo in your application. To do so, please update the component at `apps/web/components/app-logo.tsx` with your own logo.

You can either use an SVG component, or drop an image, or anything really. As long as it's rendered within this component, it doesn't matter how you do it.

The logo image will be used across the application, including the auth page, the site header, the site footer, and the app sidebar (when team accounts are disabled).


Updating the default application logo in your Makerkit application

Updating the default application logo in your Makerkir application


To install a Shadcn UI component, you can use the following command:

```bash
npx shadcn@latest add <component> -c ./packages/ui
```

For example, to install the `Button` component, you can use the following command:

```bash
npx shadcn@latest add button -c ./packages/ui
```

We pass the `--path` flag to specify the path where the component should be installed. You may need to adjust the path based on your project structure.

### Update the imports

**NB**: you may need to update the imports to the `cn` utility function to use the relative imports because it somehow breaks. Please do that.

### Export the component

To achieve optimal tree-shaking, we export each component individually using the `exports` field in the `package.json` file. This allows you to import the component directly from the package.

Once the component has been created, you can export by adding a new export to the `package.json` file.

We assume that the component is located at `src/shadcn/avatar.tsx`. To export the component, you can append a new export field to the `exports` map inside the `package.json` file:

```json
{
  "exports": {
    "./avatar": "./src/shadcn/avatar.tsx"
  }
}
```

Now you can import it directly from the package:

```tsx
import { Avatar } from '@kit/ui/avatar';
```

**NB**: this is an example, you need to adjust the component name based on the component you are exporting.

Update your Next.js Supabase application with new Shadcn UI components

How to add new Shadcn UI components to your Next.js Supabase application


By default, Makerkit uses two fonts:

1. `font-sans`: using Apple's default font on Apple devices, or `Inter` on others
2. `font-heading`: uses `Urbanist` from Google Fonts

The fonts are defined at `apps/web/lib/fonts.ts`:

```tsx
import { Urbanist as HeadingFont, Inter as SansFont } from 'next/font/google';

/**
 * @sans
 * @description Define here the sans font.
 * By default, it uses the Inter font from Google Fonts.
 */
const sans = SansFont({
  subsets: ['latin'],
  variable: '--font-sans',
  fallback: ['system-ui', 'Helvetica Neue', 'Helvetica', 'Arial'],
  preload: true,
  weight: ['300', '400', '500', '600', '700'],
});

/**
 * @heading
 * @description Define here the heading font.
 * By default, it uses the Urbanist font from Google Fonts.
 */
const heading = HeadingFont({
  subsets: ['latin'],
  variable: '--font-heading',
  fallback: ['system-ui', 'Helvetica Neue', 'Helvetica', 'Arial'],
  preload: true,
  weight: ['500', '700'],
});

// we export these fonts into the root layout
export { sans, heading };
```

To display a different font, please replace the imports from `next/font/google` if the font is there.

## Removing Apple's system as default font on Apple Devices

To set another font instead of Apple's system font, update the Tailwind configuration.

Open `tooling/tailwind/index.ts` and replace the line:

```
sans: ['-apple-system', 'var(--font-sans)', ...fontFamily.sans],
```

to

```
sans: ['var(--font-sans)', ...fontFamily.sans],
```

Learn how to update the fonts of your Makerkit application

Update the default fonts of your SaaS


By default, Makerkit uses the `sidebar` layout style for both the user and the team workspaces.

You can change the layout style by setting the `NEXT_PUBLIC_USER_NAVIGATION_STYLE` and `NEXT_PUBLIC_TEAM_NAVIGATION_STYLE` environment variables. The default style is `sidebar`.

To set the layout style to `header`, update the environment variables:

```bash
NEXT_PUBLIC_TEAM_NAVIGATION_STYLE=header
NEXT_PUBLIC_USER_NAVIGATION_STYLE=header
```

The default layout style is `sidebar`:

<Image src='/assets/images/docs/turbo-sidebar-layout.webp' width="2522" height="1910" />

And here is `header` layout:

<Image src='/assets/images/docs/turbo-header-layout.webp' width="3282" height="1918" />


Learn how to update the default layout style of your Makerkit application

Update the default layout style of your SaaS

Development


In the previous sections, you learned how to clone the repository, set environment variables, customize the look and feel of the app, and some basic API that you'll be using throughout the app. 

In this section, you'll learn how to start developing your app locally.

Buckle up, we have a lot to do!

---

Generally speaking, you will be doing the following:

1. **Customization**: Set environment variables (application name, feature flags). This is a quick starting point that will start turning Makerkit into your very own app.
2. **Database**: Drawing and writing the database schema. Of course, your app will store data and have its schema. It's time to draw it.
3. **Routing**: Adding new routes. Your new pages will need routes - unless you can reuse the "home" pages of the accounts.
4. **Fetching Data**: Fetching data from your DB and displaying it onto the new routes.
5. **Writing Data** Adding new forms. You will need to add forms to create new data.

In 90% of cases, the above is what you will be doing. The remaining 10% is adding new (very specific) features, which are a bit more complex - and not relevant to Makerkit itself.

How to approach local development


Creating a schema for your data is one of the primary tasks when building a new application. In this guide, we'll walk through how to create new migrations and update the database schema in your Next.js Supabase application.

## A quick word on migrations

Supabase's hosted Studio is pretty great - but I don't think it should be used to perform schema changes. Instead, I recommend using your local Supabase Studio to make the changes and then generate the migration file. Then, you can push the migration to the remote Supabase instance.

At this point, you have two options:

1. create a migration with `pnpm --filter web supabase migration new <name>` and update the code manually
2. or, use the local Supabase Studio to make the changes and then run `pnpm --filter web supabase db diff -f <name>` which will generate the migration file for you. DOUBLY CHECK THE FILE!

Once you've tested it all and are happy with your local changes, push the migration to the remote Supabase instance with `pnpm --filter web supabase db push`.

Doing the opposite is also okay - but:

1. You're making changes against the production database - which is risky
2. You're not testing the changes locally - which is risky
3. You need to pull the changes from the remote Supabase instance to your local instance so they are in sync

## Creating a Migration

The first step towards building your app schema is to create a new migration.

To do so, run the command:

```
pnpm --filter web supabase migration new <name>
```

The migration will be generated at `apps/web/supabase/migrations`.

Once added some SQL commands, you need to reset the schema for it to take effect:

```
pnpm run supabase:web:reset
```

The schema is now populated! Yay!

### Generating Supabase types

Now that your schema is populated, you need to generate the types so that your Supabase client can work correctly.

Please run the following command:

```
pnpm run supabase:web:typegen
```

Your Supabase client will now correctly infer the types with your schema changes.

Learn how to create new migrations and update the database schema in your Next.js Supabase application

How to create new migrations and update the database schema in your Next.js Supabase application


After creating your migration, it's time to add the required code.

In our example, we create the schema for a simple tasks application.

### Permissions

Makerkit defines a set of default permissions in an enum named `public.app_permissions`.

To add more permissions for your app, please update the enum:

```sql
-- insert new permissions
alter type public.app_permissions add value 'tasks.write';
alter type public.app_permissions add value 'tasks.delete';
commit;
```

In the case above, we added the permissions `tasks.write` and `tasks.delete`. We can use these in our RLS rules to make sure
the permissions are able to restrict access.

### Tasks Table

Let's now add the new `tasks` table

```sql
-- create tasks table
create table if not exists public.tasks (
  id uuid primary key default gen_random_uuid(),
  title varchar(500) not null,
  description varchar(50000),
  done boolean not null default false,
  account_id uuid not null references public.accounts(id),
  created_at timestamp with time zone not null default now(),
  updated_at timestamp with time zone not null default now()
);

grant select, insert, update, delete on table public.tasks to
    authenticated, service_role;
```

Let's explain:
- 1. `uuid` is a primary key generated automatically
- 2. `title` is a text field constrained to 500 chars. `not null` makes sure it cannot be null.
- 3. `description` is a text field constrained to 50000
- 4. `done` is a boolean field
- 5. `account_id` is the account that owns the task

We then add the required permissions to the roles `authenticated` and `service_role`.

Anonymous users have no access to this table.

### Accounts

Accounts are the primary entities of our schema. An account can be a user or a team.

We can connect an entity to the account that owns it using a foreign key

```sql
account_id uuid not null references public.accounts(id)
```

### Enabling RLS

When you create a new table, always enable RLS.

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

### RLS Policies

RLS Policies are fundamental to protect our tables.

We insert an RLS policy for each action: `select`, `insert`, `update` and `delete`.

#### Selecting Tasks

When writing an RLS policy for selecting data from the `tasks` table, we need to make sure the user is the owner of the task or has the required permission.

Generally speaking, entities belong to `public.accounts` - and we can use the `account_id` to check if the user is the owner.

```sql
create policy select_tasks on public.tasks
    for select
    to authenticated
    using (
      account_id = auth.uid() or
      public.has_role_on_account(account_id)
    );
```

Did you know that an account can be a user or a team? We can use the `public.has_role_on_account` function to check if the user has a role on the account.

Therefore, this RLS policy works in both ways:

1. if the user is the owner of the task - we check that the `account_id` is equal to the `auth.uid()`
2. if the user has a role on the account - we check that the user has a role on the account

#### Inserting Tasks

When writing an RLS policy for inserting data into the `tasks` table, we need to make sure the user is the owner of the task or has the required permission.

```sql
create policy insert_tasks on public.tasks
    for insert
    with check (
        account_id = auth.uid() or
        public.has_permission(auth.uid(), account_id, 'tasks.write'::app_permissions)
    );
```

In th above, we check if the user is the owner of the task or has the `tasks.write` permission.

1. If the `account_id` is equal to the `auth.uid()` - the account is personal - so permissions are not required
2. If the user has the `tasks.write` permission - the user can insert the task

### Updating Tasks

When writing an RLS policy for updating data in the `tasks` table, we need to make sure the user is the owner of the task or has the required permission.

```sql
create policy update_tasks on public.tasks
    for update
    using (
        account_id = auth.uid() or
        public.has_permission(auth.uid(), account_id, 'tasks.write'::app_permissions)
    )
    with check (
        account_id = auth.uid() or
        public.has_permission(auth.uid(), account_id, 'tasks.write'::app_permissions)
    );
```

Did you know that we need to add the `using` and `with check` clauses?

- `using` is used to filter the rows that the user can update
- `with check` is used to check if the user can update the row

In the above, we check if the user is the owner of the task or has the `tasks.write` permission.

### Deleting Tasks

When writing an RLS policy for deleting data from the `tasks` table, we need to make sure the user is the owner of the task or has the required permission.

```sql
create policy delete_tasks on public.tasks
    for delete
    using (
        account_id = auth.uid() or
        public.has_permission(auth.uid(), account_id, 'tasks.delete'::app_permissions)
    );
```

In the above, we check if the user is the owner of the task or has the `tasks.delete` permission.

Our schema is now complete! Yay! 🎉

### Resetting Migrations

When adding a new schema, we need to reset the migrations.

```bash
pnpm run supabase:web:reset
```

Then, we generate the new types using the following command:

```bash
pnpm run supabase:web:typegen
```

You can now use the new types in your application when using the Supabase client.



The database schema contains several functions that you can use so that you can extend your database with custom logic and RLS.

## Check if a user is the Owner of an Account

This function checks if the user is the owner of an account. It is used in the `accounts` table to restrict access to the account owner.

```sql
public.is_account_owner(account_id uuid)
```

This is `true` if the account is the user's account or if the user created a team account.

## Check if a user is a Member of an Account

This function checks if the user is a member of an account. It is used in the `accounts` table to restrict access to the account members.

```sql
public.has_role_on_account(
  account_id uuid,
  account_role varchar(50) default null
)
```

If the `account_role` is not provided, it will return `true` if the user is a member of the account. If the `account_role` is provided, it will return `true` if the user has the specified role on the account.

## Check if a user is a team member of an Account

Check if a user is a member of a team account. It is used in the `accounts` table to restrict access to the team members.

```sql
public.is_team_member(
  account_id uuid,
  user_id uuid
)
```

### Check if an account has permissions to action another account

This function checks if an account has permissions to action another account. It is used in the `accounts` table to restrict access to the account owner.

```sql
public.can_action_account_member(
  target_team_account_id uuid,
  target_user_id uuid
)
```

This function will:

1. check if the current user is the owner of the target account: if so, return `true`
2. check if the target user is the owner of the target account: if so, return `false`
3. compare the hierarchy of the roles between the two accounts: if the current user has a higher role than the target user, return `true`

This is useful to check if a user can remove another user from an account, or any other action that requires permissions.

### Check Permissions

Check if a user has a specific permission on an account.

```sql
public.has_permission(
  user_id uuid,
  account_id uuid,
  permission_name app_permissions
)
```

This function will return `true` if the user has the specified permission on the account.

The permissions are specified in the enum `app_permissions`. You can extend this enum to add more permissions.

### Check if a configuration is set

Check if a configuration is set in the `public.config` table.

```sql
public.is_set(
  field_name text
)
```

### Check if an account has an active subscription

Check if an account has an active subscription.

```sql
public.has_active_subscription(
  account_id uuid
)
```

This means that the subscription status is either `active` or `trialing`. In other words, the account billing is in good standing (eg. no unpaid invoice)

This is important because just checking if the subscription exists is not enough. You need to check if the subscription is active, as the status can vary (eg. `canceled`, `incomplete`, `incomplete_expired`, `past_due`, `unpaid`)

Learn the most useful database functions in your schema

Database Functions available in your Next.js Supabase schema


Now that our database supports the data we need, we can start loading it into our application. We will use the `@makerkit/data-loader-supabase-nextjs` package to load data from the Supabase database.

Please check the [documentation](https://github.com/makerkit/makerkit/tree/main/packages/data-loader/supabase/nextjs) for the `@makerkit/data-loader-supabase-nextjs` package to learn more about how to use it.

This nifty package allows us to load data from the Supabase database and display it in our server components with support for pagination.

In the snippet below, we will

1. Load the user's workspace data from the database. This allows us to get the user's account ID without further round-trips because the workspace is loaded by the user layout.
2. Load the user's tasks from the database.
3. Display the tasks in a table.
4. Use a search input to filter the tasks by title.

Let's take a look at the code:

```tsx
import { use } from 'react';

import { ServerDataLoader } from '@makerkit/data-loader-supabase-nextjs';

import { getSupabaseServerClient } from '@kit/supabase/server-client';
import { Button } from '@kit/ui/button';
import { Heading } from '@kit/ui/heading';
import { If } from '@kit/ui/if';
import { Input } from '@kit/ui/input';
import { PageBody } from '@kit/ui/page';
import { Trans } from '@kit/ui/trans';

import { createI18nServerInstance } from '~/lib/i18n/i18n.server';
import { withI18n } from '~/lib/i18n/with-i18n';

import { TasksTable } from './_components/tasks-table';
import { UserAccountHeader } from './_components/user-account-header';
import { loadUserWorkspace } from './_lib/server/load-user-workspace';

interface SearchParams {
  page?: string;
  query?: string;
}

export const generateMetadata = async () => {
  const i18n = await createI18nServerInstance();
  const title = i18n.t('account:homePage');

  return {
    title,
  };
};

function UserHomePage(props: { searchParams: SearchParams }) {
  const client = getSupabaseServerClient();
  const { user } = use(loadUserWorkspace());

  const page = parseInt(props.searchParams.page ?? '1', 10);
  const query = props.searchParams.query ?? '';

  return (
    <>
      <UserAccountHeader
        title={<Trans i18nKey={'common:homeTabLabel'} />}
        description={<Trans i18nKey={'common:homeTabDescription'} />}
      />

      <PageBody className={'space-y-4'}>
        <div className={'flex items-center justify-between'}>
          <div>
            <Heading level={4}>
              <Trans i18nKey={'tasks:tasksTabLabel'} defaults={'Tasks'} />
            </Heading>
          </div>

          <div className={'flex items-center space-x-2'}>
            <form className={'w-full'}>
              <Input
                name={'query'}
                defaultValue={query}
                className={'w-full lg:w-[18rem]'}
                placeholder={'Search tasks'}
              />
            </form>
          </div>
        </div>

        <ServerDataLoader
          client={client}
          table={'tasks'}
          page={page}
          where={{
            account_id: {
              eq: user.id,
            },
            title: {
              textSearch: query ? `%${query}%` : undefined,
            },
          }}
        >
          {(props) => {
            return (
              <div className={'flex flex-col space-y-8'}>
                <If condition={props.count === 0 && query}>
                  <div className={'flex flex-col space-y-2.5'}>
                    <p>
                      <Trans
                        i18nKey={'tasks:noTasksFound'}
                        values={{ query }}
                      />
                    </p>

                    <form>
                      <input type="hidden" name={'query'} value={''} />

                      <Button variant={'outline'} size={'sm'}>
                        <Trans i18nKey={'tasks:clearSearch'} />
                      </Button>
                    </form>
                  </div>
                </If>

                <TasksTable {...props} />
              </div>
            );
          }}
        </ServerDataLoader>
      </PageBody>
    </>
  );
}

export default withI18n(UserHomePage);
```

Let's break this down a bit, shall we:

1. We import the necessary components and functions.
2. We define the `SearchParams` interface to type the search parameters.
3. We define the `generateMetadata` function to generate the page metadata.
4. We define the `UserHomePage` component that loads the user's workspace and tasks from the database.
5. We define the `ServerDataLoader` component that loads the tasks from the database.
6. We render the tasks in a table and provide a search input to filter the tasks by title.
7. We export the `UserHomePage` component with the `withI18n` HOC. This helps bootstrap the i18n instance for the component.

### Tasks Table

Now, let's show the tasks table component:

```tsx
'use client';

import Link from 'next/link';

import { ColumnDef } from '@tanstack/react-table';
import { Pencil } from 'lucide-react';
import { useTranslation } from 'react-i18next';

import { Button } from '@kit/ui/button';
import { DataTable } from '@kit/ui/enhanced-data-table';

import { Database } from '~/lib/database.types';

type Task = Database['public']['Tables']['tasks']['Row'];

export function TasksTable(props: {
  data: Task[];
  page: number;
  pageSize: number;
  pageCount: number;
}) {
  const columns = useGetColumns();

  return (
    <div>
      <DataTable {...props} columns={columns} />
    </div>
  );
}

function useGetColumns(): ColumnDef<Task>[] {
  const { t } = useTranslation('tasks');

  return [
    {
      header: t('task'),
      cell: ({ row }) => (
        <Link
          className={'hover:underline'}
          href={`/home/tasks/${row.original.id}`}
        >
          {row.original.title}
        </Link>
      ),
    },
    {
      header: t('createdAt'),
      accessorKey: 'created_at',
    },
    {
      header: t('updatedAt'),
      accessorKey: 'updated_at',
    },
    {
      header: '',
      id: 'actions',
      cell: ({ row }) => {
        const id = row.original.id;

        return (
          <div className={'flex justify-end space-x-2'}>
            <Link href={`/home/tasks/${id}`}>
              <Button variant={'ghost'} size={'icon'}>
                <Pencil className={'h-4'} />
              </Button>
            </Link>
          </div>
        );
      },
    },
  ];
}
```

In this snippet, we define the `TasksTable` component that renders the tasks in a table. We use the `DataTable` component from the `@kit/ui/enhanced-data-table` package to render the table.

We also define the `useGetColumns` hook that returns the columns for the table. We use the `useTranslation` hook from the `react-i18next` package to translate the column headers.

In this page we learn how to load data from the Supabase database and display it in our Next.js application.

Learn how to load data from the Supabase database


In this page, we will learn how to write data to the Supabase database in your Next.js app.

## Writing a Server Action to Add a Task

Server Actions are defined by adding `use server` at the top of the function or file. When we define a function as a Server Action, it will be executed on the server-side.

This is useful for various reasons:
1. By using Server Actions, we can revalidate data fetched through Server Components
2. We can execute server side code just by calling the function from the client side

In this example, we will write a Server Action to add a task to the database.

### Defining a Schema for the Task

We use Zod to validate the data that is passed to the Server Action. This ensures that the data is in the correct format before it is written to the database.

The convention in Makerkit is to define the schema in a separate file and import it where needed. We use the convention `file.schema.ts` to define the schema.

```tsx
import { z } from 'zod';

export const WriteTaskSchema = z.object({
  title: z.string().min(1),
  description: z.string().nullable(),
});
```

### Writing the Server Action to Add a Task

In this example, we write a Server Action to add a task to the database. We use the `revalidatePath` function to revalidate the `/home` page after the task is added.

```tsx
'use server';

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

import { z } from 'zod';

import { getLogger } from '@kit/shared/logger';
import { requireUser } from '@kit/supabase/require-user';
import { getSupabaseServerClient } from '@kit/supabase/server-client';

import { WriteTaskSchema } from '~/(dashboard)/home/(user)/_lib/schema/write-task.schema';

export async function addTaskAction(params: z.infer<typeof WriteTaskSchema>) {
  'use server';

  const task = WriteTaskSchema.parse(params);

  const logger = await getLogger();
  const client = getSupabaseServerClient();
  const auth = await requireUser(client);

  if (!auth.data) {
    redirect(auth.redirectTo);
  }

  logger.info(task, `Adding task...`);

  const { data, error } = await client
    .from('tasks')
    .insert({ ...task, account_id: auth.data.id });

  if (error) {
    logger.error(error, `Failed to add task`);

    throw new Error(`Failed to add task`);
  }

  logger.info(data, `Task added successfully`);

  revalidatePath('/home', 'page');

  return null;
}
```

Let's focus on this bit for a second:

```tsx
const { data, error } = await client
    .from('tasks')
    .insert({ ...task, account_id: auth.data.id });
```

Do you see the `account_id` field? This is a foreign key that links the task to the user who created it. This is a common pattern in database design.

Now that we have written the Server Action to add a task, we can call this function from the client side. But we need a form, which we define in the next section.

### Creating a Form to Add a Task

We create a form to add a task. The form is a React component that accepts a `SubmitButton` prop and an `onSubmit` prop.

```tsx
import { zodResolver } from '@hookform/resolvers/zod';
import { useForm } from 'react-hook-form';
import { z } from 'zod';

import {
  Form,
  FormControl,
  FormDescription,
  FormField,
  FormItem,
  FormLabel,
  FormMessage,
} from '@kit/ui/form';
import { Input } from '@kit/ui/input';
import { Textarea } from '@kit/ui/textarea';
import { Trans } from '@kit/ui/trans';

import { WriteTaskSchema } from '../_lib/schema/write-task.schema';

export function TaskForm(props: {
  task?: z.infer<typeof WriteTaskSchema>;
  onSubmit: (task: z.infer<typeof WriteTaskSchema>) => void;
  SubmitButton: React.ComponentType;
}) {
  const form = useForm({
    resolver: zodResolver(WriteTaskSchema),
    defaultValues: props.task,
  });

  return (
    <Form {...form}>
      <form
        className={'flex flex-col space-y-4'}
        onSubmit={form.handleSubmit(props.onSubmit)}
      >
        <FormField
          render={(item) => {
            return (
              <FormItem>
                <FormLabel>
                  <Trans i18nKey={'tasks:taskTitle'} />
                </FormLabel>

                <FormControl>
                  <Input required {...item.field} />
                </FormControl>

                <FormDescription>
                  <Trans i18nKey={'tasks:taskTitleDescription'} />
                </FormDescription>

                <FormMessage />
              </FormItem>
            );
          }}
          name={'title'}
        />

        <FormField
          render={(item) => {
            return (
              <FormItem>
                <FormLabel>
                  <Trans i18nKey={'tasks:taskDescription'} />
                </FormLabel>

                <FormControl>
                  <Textarea {...item.field} />
                </FormControl>

                <FormDescription>
                  <Trans i18nKey={'tasks:taskDescriptionDescription'} />
                </FormDescription>

                <FormMessage />
              </FormItem>
            );
          }}
          name={'description'}
        />

        <props.SubmitButton />
      </form>
    </Form>
  );
}
```

### Using a Dialog component to display the form

We use the Dialog component from the `@kit/ui/dialog` package to display the form in a dialog. The dialog is opened when the user clicks on a button.

```tsx
'use client';

import { useState, useTransition } from 'react';

import { PlusCircle } from 'lucide-react';

import { Button } from '@kit/ui/button';
import {
  Dialog,
  DialogContent,
  DialogDescription,
  DialogHeader,
  DialogTitle,
  DialogTrigger,
} from '@kit/ui/dialog';
import { Trans } from '@kit/ui/trans';

import { TaskForm } from '../_components/task-form';
import { addTaskAction } from '../_lib/server/server-actions';

export function NewTaskDialog() {
  const [pending, startTransition] = useTransition();
  const [isOpen, setIsOpen] = useState(false);

  return (
    <Dialog open={isOpen} onOpenChange={setIsOpen}>
      <DialogTrigger asChild>
        <Button>
          <PlusCircle className={'mr-1 h-4'} />
          <span>
            <Trans i18nKey={'tasks:addNewTask'} />
          </span>
        </Button>
      </DialogTrigger>

      <DialogContent>
        <DialogHeader>
          <DialogTitle>
            <Trans i18nKey={'tasks:addNewTask'} />
          </DialogTitle>

          <DialogDescription>
            <Trans i18nKey={'tasks:addNewTaskDescription'} />
          </DialogDescription>
        </DialogHeader>

        <TaskForm
          SubmitButton={() => (
            <Button>
              {pending ? (
                <Trans i18nKey={'tasks:addingTask'} />
              ) : (
                <Trans i18nKey={'tasks:addTask'} />
              )}
            </Button>
          )}
          onSubmit={(data) => {
            startTransition(async () => {
              await addTaskAction(data);
              setIsOpen(false);
            });
          }}
        />
      </DialogContent>
    </Dialog>
  );
}
```

We can now import `NewTaskDialog` in the `/home` page and display the dialog when the user clicks on a button.

Let's go back to the home page and add the component right next to the input filter:

```tsx {18}
<div className={'flex items-center justify-between'}>
  <div>
    <Heading level={4}>
      <Trans i18nKey={'tasks:tasksTabLabel'} defaults={'Tasks'} />
    </Heading>
  </div>

  <div className={'flex items-center space-x-2'}>
    <form className={'w-full'}>
      <Input
        name={'query'}
        defaultValue={query}
        className={'w-full lg:w-[18rem]'}
        placeholder={'Search tasks'}
      />
    </form>

    <NewTaskDialog />
  </div>
</div>
```

In this page we learn how to write data to the Supabase database in your Next.js app

Learn how to write data to the Supabase database


Database webhooks allow you to listen to changes in your database and trigger custom logic when a change occurs. This is useful for sending notifications, updating caches, or triggering other services.

Makerkit handles some webhooks by default for functionalities such as deleting a subscription following a user deletion, or sending emails after a user signs up.

You can extend this functionality by adding your own webhook handlers:

```tsx title="apps/web/app/api/db/webhook/route.ts"
import {
  getDatabaseWebhookHandlerService,
} from '@kit/database-webhooks';

/**
 * @name POST
 * @description POST handler for the webhook route that handles the webhook event
 */
export async function POST(request: Request) {
  const service = getDatabaseWebhookHandlerService();

  try {
    // handle the webhook event
    await service.handleWebhook(request, {
      handleEvent(change) {
        if (change.type === 'INSERT' && change.table === 'invitations') {
          // do something with the invitation
        }
      },
    });

    return new Response(null, { status: 200 });
  } catch {
    return new Response(null, { status: 500 });
  }
}
```

As you can see above - the `handleEvent` function is where you can add your custom logic to handle the webhook event. In this example, we check if the event is an `INSERT` event on the `invitations` table and then do something with the invitation.

The `change` object is of type `RecordChange` and contains the following properties:

```tsx
import { Database } from '@kit/supabase/database';

export type Tables = Database['public']['Tables'];

export type TableChangeType = 'INSERT' | 'UPDATE' | 'DELETE';

export interface RecordChange<
  Table extends keyof Tables,
  Row = Tables[Table]['Row'],
> {
  type: TableChangeType;
  table: Table;
  record: Row;
  schema: 'public';
  old_record: null | Row;
}
```

You may need to cast the type manually:

```tsx
type AccountChange = RecordChange<'accounts'>;
```

Now, the `AccountChange` type can be used to type the `change` object in the `handleEvent` function and is typed to the `accounts` table.

Learn how to handle custom database webhooks in your Next.js Supabase application

How to handle custom database webhooks in your Next.js Supabase application


Makerkit implements granular RBAC for team members. This allows you to define roles and permissions for each team member - giving you fine-grained control over who can access what.

Makerkit implements two tables for roles and permissions:

- `roles` table: This table stores the roles for each team member.
- `role_permissions` table: This table stores the permissions for each role.

The table `role_permissions` has the following schema:

- `id`: The unique identifier for the role permission.
- `role`: The role for the team member.
- `permission`: The permission for the role.

The `roles` table has the following schema:

- `name`: The name of the role. This must be unique.
- `hierarchy_level`: The hierarchy level of the role.

We can use `hierarchy_level` to define the hierarchy of roles. For example, an `admin` role can have a higher hierarchy level than a `member` role. This will help you understand if a role has more permissions than another role.

And an enum for permissions `app_permissions`:

- `app_permissions` enum: This enum stores the permissions for each role.

By default, Makerkit comes with two roles: `owner` and `member` - and the following permissions:

```sql
create type public.app_permissions as enum(
  'roles.manage',
  'billing.manage',
  'settings.manage',
  'members.manage',
  'invites.manage'
);
```

You can add more roles and permissions as needed.

### Default roles and permissions

The default roles are defined as follows:

1. Members with `owner` role have full access to the application.
2. Members with `member` role have the following permissions: `members.manage` and `invites.manage`.

### Adding new roles and permissions

To add new permissions, you can update the `app_permissions` enum:

```sql
-- insert new permissions
alter type public.app_permissions add value 'tasks.write';
alter type public.app_permissions add value 'tasks.delete';
commit;
```

In the above, we added two new permissions: `tasks.write` and `tasks.delete`.

You can assign these permissions to roles in the `role_permissions` table for fine-grained access control:

```sql
insert into public.role_permissions (role, permission) values ('owner', 'tasks.write');
insert into public.role_permissions (role, permission) values ('owner', 'tasks.delete');
```

Of course - you will need to enforce these permissions in your application code and RLS.

### Using roles and permissions in RLS

To check if a user has a certain permission on an account, we can use the function `has_permission` - which you can use in your RLS to enforce permissions.

In the below, we create an RLS policy `insert_tasks` on the `tasks` table to check if a user can insert a new task. We use `public.has_permission` to check if the current user has the permission `tasks.write`:

```sql
create policy insert_tasks on public.tasks
    for insert
    with check (
        public.has_permission(auth.uid(), account_id, 'tasks.write'::app_permissions)
    );
```

And now we can also add a policy to check if a user can delete a task:

```sql
create policy delete_tasks on public.tasks
    for delete
    using (
        public.has_permission(auth.uid(), account_id, 'tasks.delete'::app_permissions)
    );
```

### Using roles and permissions in application code

You can use the exact same function `has_permission` in your application code to check if a user has a certain permission. You will call the function with the Supabase RPC method:

```tsx
async function hasPermissionToInsertTask(userId: string, accountId: string) {
  const { data: hasPermission, error } = await client.rpc('has_permission', {
    user_id: userId,
    account_id: accountId,
    permission: 'tasks.write',
  });

  if (error || !hasPermission) {
    throw new Error(`User has no permission to insert task`);
  }
}
```

You can now use `hasPermissionToInsertTask` to check if a user has permission to insert a task anywhere in your application code - provided you obtain the user and account IDs.

You can use this function to gate access to certain pages, or verify the user permissions before performing some server-side requests.

Of course, it's always worth making sure RLS is enforced on the database level as well.

### Using permissions client-side

While checks must be done always server-side, it is useful to have the permissions available client-side for UI purposes. For example, you may want to hide a certain button if the user does not have the permission to perform an action.

We fetch the permissions as part of the [Account Workspace API](account-workspace-api) - which is available to the layout around the account routes.

This API fetches the permissions for the current user and account and makes them available to the client-side simply by passing it from a page to the client components that require it.

Let's assume you have a page, and you want to check if the user has the permission to write tasks:

```tsx
import { loadTeamWorkspace } from '~/home/[account]/_lib/server/team-account-workspace.loader';

export default function TasksPage() {
  const data = await loadTeamWorkspace();
  const permissions = data.account.permissions; // string[]

  const canWriteTasks = permissions.includes('tasks.write');

  return (
    <div>
      {canWriteTasks && <button>Create Task</button>}
      // other UI elements // ...
    </div>
  );
}
```

You can also pass the permissions list to the components that need it as a prop.

This way, you can gate access to certain UI elements based on the user's permissions.

```tsx
import { loadTeamWorkspace } from '~/home/[account]/_lib/server/team-account-workspace.loader';

export default function TasksPage() {
  const data = await loadTeamWorkspace();
  const permissions = data.account.permissions; // string[]

  return (
    <div>
      <TaskList permissions={permissions} />
    </div>
  );
}
```

Similarly, you can use the permissions to gate access to certain routes or pages.

```tsx
import { loadTeamWorkspace } from '~/home/[account]/_lib/server/team-account-workspace.loader';

export default function TasksPage() {
  const data = await loadTeamWorkspace();
  const permissions = data.account.permissions; // string[]

  if (!permissions.includes('tasks.read')) {
    return <ErrorPage message="You do not have permission to write tasks" />;
  }

  return (
    <div>
      <TaskList permissions={permissions} />
    </div>
  );
}
```

Easy as that!


Learn how to implement roles and permissions in Next.js Supabase

RBAC: Understanding roles and permissions in Next.js Supabase


Makerkit comes with pre-defined marketing pages to help you get started with your SaaS application. These pages are built with Next.js and Tailwind CSS and are located in the `apps/web/app/(marketing)` directory.

Makerkit comes with the following marketing pages:

- Home Page
- Contact Form
- Pricing Page
- FAQ
- Contact Page (with a contact form)

## Adding a new marketing page

To add a new marketing page to your Makerkit application, you need to follow these steps.

Create a folder in the `apps/web/app/(marketing)` directory with the path you want to use for the page. For example, to create a new page at `/about`, you would create a folder named `about`. Then, create the page file in the folder. For example, to create an `about` page, you would create an `page.tsx` file in the `about` folder.

```tsx
// apps/web/app/(marketing)/about/page.tsx
export default function AboutPage() {
  return <div></div>
}
```

This page inherits the layout at `apps/web/app/(marketing)/layout.tsx`. You can customize the layout by editing this file - but remember that it will affect all marketing pages.

## Contact Form

To make the contact form work, you need to add the following environment variables:

```bash
CONTACT_EMAIL=
```

In this variable, you need to set the email address where you want to receive the contact form submissions. The sender will be the same as the one configured in your [mailing configuration](email-configuration).

Learn how to create and update marketing pages in the Next.js Supabase Turbo Starter Kit.

Marketing Pages in the Next.js Supabase Turbo Starter Kit


Legal pages are defined in the `apps/web/app/(marketing)/(legal)` directory. 

Makerkit comes with the following legal pages:

1. Terms and Conditions
2. Privacy Policy
3. Cookie Policy

For obvious reasons, **these pages are empty and you need to fill in the content**.

Do yourself a favor and do not use ChatGPT to generate these pages.

### Using a CMS for legal pages

You can use a CMS to manage the content of the legal pages. To do this, use the [CMS Client](cms):

```tsx
import { createCmsClient } from '@kit/cms';

export async function MyPage() {
  const cms = await createCmsClient();

  const { title, content } = await cms.getContentBySlug({
    slug: `slug`,
    collection: `pages`
  });

  return (
    <div>
      <h1>{title}</h1>
      <div dangerouslySetInnerHTML={{ __html: content }} />
    </div>
  );
}
```

Learn how to create and update legal pages in the Next.js Supabase Turbo Starter Kit.

Legal Pages in the Next.js Supabase Turbo Starter Kit


Many teams prefer to create an external marketing website for their SaaS application. This allows them to have more control over the design and content of the website. For example, using services such as Framer, Webflow, or Wordpress.

In this case, we have to redirect all marketing pages to the external marketing website. You can do so tweaking the middleware in the `apps/web/middleware.ts` file.

Take the list of all your marketing pages, and then add a middleware to redirect all those pages to the external marketing website.

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

export function middleware(req: NextRequest) {
  if (isMarketingPage(req)) {
    return NextResponse.redirect('https://your-external-website.com' + req.nextUrl.pathname);
  }

  // leave the rest of the middleware unchanged
}

function isMarketingPage(req: NextRequest) {
  const marketingPages = [
    '/pricing',
    '/faq',
    '/contact',
    '/about',
    '/home',
    '/privacy-policy',
    '/terms-and-conditions',
    '/cookie-policy',
  ];

  return marketingPages.includes(req.nextUrl.pathname);
}
```

Should you add a new marketing page, you need to update the `isMarketingPage` function with the new page path.

Learn how to configure Makerkit to work with an external marketing website in the Next.js Supabase Turbo Starter Kit.

External Marketing Website in the Next.js Supabase Turbo Starter Kit


SEO is an important part of building a website. It helps search engines understand your website and rank it higher in search results. In this guide, you'll learn how to improve your Makerkit application's search engine optimization (SEO).

Makerkit is already optimized for SEO out of the box. However, there are a few things you can do to improve your application's SEO:

1. **Content**: The most important thing you can do to improve your application's SEO is to **create high-quality content**. No amount of technical optimization can replace good content. Make sure your content is relevant, useful, and engaging - and make sure it's updated regularly.
2. **Write content helpful to your customers**: To write good content, the kit comes with a blog and documentation feature. You can use these features to create high-quality content that will help your website rank higher in search results - and help your customers find what they're looking for.
3. **Use the correct keywords**: Use descriptive titles and meta descriptions for your pages. Titles and meta descriptions are the first things users see in search results, so make sure they are descriptive and relevant to the content on the page. Use keywords that your customers are likely to search for.
4. **Optimize images**: Use descriptive filenames and alt text for your images. This helps search engines understand what the image is about and can improve your website's ranking in image search results.
5. **Website Speed**: This is much less important than it used to be, but it's still a factor. Make sure your website loads quickly and is mobile-friendly. You can use tools like Google's PageSpeed Insights to check your website's speed and get suggestions for improvement. Optimize all images and assets to reduce load times.
6. **Mobile Optimization**: Make sure your website is mobile-friendly. Google ranks mobile-friendly websites higher in search results. You can use Google's Mobile-Friendly Test to check if your website is mobile-friendly.
7. **Sitemap and Robots.txt**: Makerkit generates a sitemap and robots.txt file for your website. These files help search engines understand your website's structure and what pages they should index. Make sure to update the sitemap as you add new pages to your website.
8. **Backlinks**: Backlinks are links from other websites to your website. It's touted to be **the single most important factor in SEO** these days. The more backlinks you have from high-quality websites, the higher your website will rank in search results. You can get backlinks by creating high-quality content that other websites want to link to.

### Adding pages to the sitemap

Generally speaking, Google will find your pages without a sitemap as it follows the link in your website. However, you can add pages to the sitemap by adding them to the `apps/web/app/server-sitemap.xml/route.ts` route, which is used to generate the sitemap.

If you add more static pages to your website, you can add them to the `getPaths` function in the `apps/web/app/server-sitemap.xml/route.ts` file. For example, if you add a new page at `/about`, you can add it to the `getPaths` function like this:

```tsx title="apps/web/app/server-sitemap.xml/route.ts"
function getPaths() {
  const paths = [
    '/',
    '/faq',
    '/blog',
    '/docs',
    '/pricing',
    '/contact',
    '/cookie-policy',
    '/terms-of-service',
    '/privacy-policy',
    // add more paths here,
    '/about', // <-- add the new page here
  ];

  return paths.map((path) => {
    return {
      loc: new URL(path, appConfig.url).href,
      lastmod: new Date().toISOString(),
    };
  });
}
```

All the blog and documentation pages are automatically added to the sitemap. You don't need to add them manually.

### Adding your website to Google Search Console

Once you've optimized your website for SEO, you can add it to Google Search Console. Google Search Console is a free tool that helps you monitor and maintain your website's presence in Google search results.

You can use it to check your website's indexing status, submit sitemaps, and get insights into how Google sees your website.

The first thing you need to do is verify your website in Google Search Console. You can do this by adding a meta tag to your website's HTML or by uploading an HTML file to your website.

Once you've verified your website, you can submit your sitemap to Google Search Console. This will help Google find and index your website's pages faster.

Please submit your sitemap to Google Search Console by going to the `Sitemaps` section and adding the URL of your sitemap. The URL of your sitemap is `https://your-website.com/server-sitemap.xml`.

Of course, please replace `your-website.com` with your actual website URL.

### Backlinks

Backlinks are said to be the most important factor in modern SEO. The more backlinks you have from high-quality websites, the higher your website will rank in search results - and the more traffic you'll get.

How do you get backlinks? The best way to get backlinks is to create high-quality content that other websites want to link to. However, you can also get backlinks by:

1. **Guest posting**: Write guest posts for other websites in your niche. This is a great way to get backlinks and reach a new audience.
2. **Link building**: Reach out to other websites and ask them to link to your website. You can offer to write a guest post or provide a testimonial in exchange for a backlink.
3. **Social media**: Share your content on social media to reach a wider audience and get more backlinks.
4. **Directories**: Submit your website to online directories to get backlinks. Make sure to choose high-quality directories that are relevant to your niche.

All these methods can help you get more backlinks and improve your website's SEO - and help you rank higher in search results.

### Content

When it comes to internal factors, content is king. Make sure your content is relevant, useful, and engaging. Make sure it's updated regularly and optimized for SEO.

What should you write about? Most importantly, you want to think about how your customers will search for the problem your SaaS is solving. For example, if you're building a project management tool, you might want to write about project management best practices, how to manage a remote team, or how to use your tool to improve productivity.

You can use the blog and documentation features in Makerkit to create high-quality content that will help your website rank higher in search results - and help your customers find what they're looking for.

### Indexing and ranking take time

New websites can take a while to get indexed by search engines. It can take anywhere from a few days to a few weeks (in some cases, even months!) for your website to show up in search results. Be patient and keep updating your content and optimizing your website for search engines.

---

By following these tips, you can improve your Makerkit application's search engine optimization (SEO) and help your website rank higher in search results. Remember, SEO is an ongoing process, so make sure to keep updating your content and optimizing your website for search engines. Good luck!


Learn how to improve your Makerkit application's search engine optimization (SEO)

SEO - Improve your Next.js application's search engine optimization"


This is an **advanced topic** - you should only follow these instructions if you are sure you want to add a new package to your Makerkit application instead of adding a folder to your application in `apps/web`. You don't need to do this to add a new page or component to your application.

---

To add a new package to your Makerkit application, you need to follow these steps.

First, enter the command below to create a new package in your Makerkit application:

```bash
turbo gen
```

Turborepo will ask you to enter the name of the package you want to create. Enter the name of the package you want to create and press enter.

If you don't want to add dependencies to your package, you can skip this step by pressing enter.

The command will have generated a new package under `packages` named `@kit/<package-name>`. If you named it `my-package`, the package will be named `@kit/my-package`.

Finally, to make fast refresh work when you make changes to the package, you need to add the package to the `next.config.mjs` file in the root of your Makerkit application `apps/web`.

```tsx
const INTERNAL_PACKAGES = [
  // all internal packages,
  '@kit/my-package',
];
```

## Exporting a module from a package

By default, the package exports a single module using the `index.ts` file. You can add more exports by creating new files in the package directory and exporting them from the `index.ts` file or creating export files in the package directory and adding them to the `exports` field in the `package.json` file.

### Exporting a module from index.ts

The easiest way to export a module from a package is to create a new file in the package directory and export it from the `index.ts` file.

```tsx
// packages/@kit/my-package/src/my-module.ts

export function myModule() {
  return 'Hello from my module';
}
```

Then, export the module from the `index.ts` file.

```tsx
// packages/@kit/my-package/src/index.ts
export * from './my-module';
```

### Exporting using the exports field in package.json

This can be very useful for tree-shaking. Assuming you have a file named `my-module.ts` in the package directory, you can export it by adding it to the `exports` field in the `package.json` file.

```json
{
  "exports": {
    ".": "./src/index.ts",
    "./my-module": "./src/my-module.ts"
  }
}
```

When to do this?

1. when exporting two modules that don't share dependencies to ensure better tree-shaking. For example, if your exports contains both client and server modules.
2. for better organization of your package


For example, create two exports `client` and `server` in the package directory and add them to the `exports` field in the `package.json` file.

```json
{
  "exports": {
    ".": "./src/index.ts",
    "./client": "./src/client.ts",
    "./server": "./src/server.ts"
  }
}
```

1. The `client` module can be imported using `import { client } from '@kit/my-package/client'`
2. The `server` module can be imported using `import { server } from '@kit/my-package/server'`

You can now use the package in your application by importing it using the package name.

```tsx
import { myModule } from '@kit/my-package';

console.log(myModule());
```

Et voilà! You have successfully added a new package to your Makerkit application. 🎉


Learn how to add a new Turborepo package to your Makerkit application

Add a new Turborepo package to your Makerkit application


This is an **advanced topic** - you should only follow these instructions if you are placing a new app within your monorepo and want to keep pulling updates from the Makerkit repository.

In some ways - creating a new repository may be the easiest way to manage your application. However, if you want to keep your application within the monorepo and pull updates from the Makerkit repository, you can follow these instructions.

---

To pull updates into a separate application outside of `web` - we can use `git subtree`.

Basically, we will create a subtree at `apps/web` and create a new remote branch for the subtree. When we create a new application, we will pull the subtree into the new application. This allows us to keep it in sync with the `apps/web` folder.

### 1. Create a subtree

First, we need to create a subtree for the `apps/web` folder. We will create a new branch called `web` and create a subtree for the `apps/web` folder. We will create a branch named `web-branch` and create a subtree for the `apps/web` folder.

```bash
git subtree split --prefix=apps/web --branch web-branch
```

### 2. Create a new application

Now, we can create a new application in the `apps` folder. For example, let's create a new application called `api`.

Let's say we want to create a new app `pdf-chat` at `apps/pdf-chat` with the same structure as the `apps/web` folder (which acts as the template for all new apps).

```bash
git subtree add --prefix=apps/pdf-chat origin web-branch --squash
```

You should now be able to see the `apps/pdf-chat` folder with the contents of the `apps/web` folder.

### 3. Update the new application

When you want to update the new application, follow these steps:

#### Pull updates from the Makerkit repository

The command below will update all the changes from the Makerkit repository:

```bash
git pull upstream main
```

#### Push the web-branch updates

After you have pulled the updates from the Makerkit repository, you can split the branch again and push the updates to the `web-branch`:

```bash
git subtree split --prefix=apps/web --branch web-branch
```

Now, you can push the updates to the `web-branch`:

```bash
git push origin web-branch
```

#### Pull the updates to the new application

Now, you can pull the updates to the new application:

```bash
git subtree pull --prefix=apps/pdf-chat origin web-branch --squash
```


Learn how to add a new Turborepo application to your Makerkit application

Add a new Turborepo application to your Makerkit application

Billing



The billing package is used to manage subscriptions, one-off payments, and more.

The billing package is abstracted from the billing gateway package, which is used to manage the payment gateway (e.g., Stripe, Lemon Squeezy, etc.).

To set up the billing package, you need to set the following environment variables:

```bash
NEXT_PUBLIC_BILLING_PROVIDER=stripe # or lemon-squeezy
```

## Billing in Makerkit

Makerkit implements two packages for managing billing:

1. `core`: this package is responsible for exporting the billing service and the schema getFontDefinitionFromNetwork
2. `gateway`: the gateway is a router that handles the billing service and the billing provider (e.g., Stripe, Lemon Squeezy, etc.)

Then, we define a package for each provider:

1. `stripe`: this package is responsible for handling the Stripe API
2. `lemon-squeezy`: this package is responsible for handling the Lemon Squeezy API
3. `paddle`: this package is responsible for handling the Paddle API (Coming soon)

To summarize:

1. core defines the service and the schema
2. the provider's packages define the API calls based on the provider's API
3. the gateway package is responsible for routing the requests to the correct provider

Whatever provider you choose, you need to set the environment variable `NEXT_PUBLIC_BILLING_PROVIDER` to the provider you want to use. The Gateway Service will then route the requests to the correct provider. This means you can switch between providers without changing the code. The schema is the same for all providers - but the details of the API calls are different - so some details apply.

## Subscriptions vs. One-off payments

Makerkit supports both one-off payments and subscriptions. You have the choice to use one or both. What Makerkit cannot assume with certainty is the billing mode you want to use. By default, we assume you want to use subscriptions, as this is the most common billing mode for SaaS applications.

This means that - by default - Makerkit will be looking for a subscription plan when visiting the billing section of the personal or team account. This means we fetch data from the tables `subscriptions` and `subscription_items`.

If you want to use one-off payments, you need to set the billing mode to `one-time`:

```bash
BILLING_MODE=one-time
```

By doing so, Makerkit will be looking for one-off payments when visiting the billing section of the personal or team account. This means we fetch data from the tables `orders` and `order_items`.

### But - I want to use both

Perfect - you can, but you need to customize the pages to display the correct data.

---

Depending on the service you use, you will need to set the environment variables accordingly. By default - the billing package uses Stripe. Alternatively, you can use Lemon Squeezy. In the future, we will also add Paddle.

A quick introduction to billing in Makerkit and how to set it up in the Next.js Supabase SaaS kit

How Billing works in the Next.js Supabase SaaS kit


The billing schema replicates your billing provider's schema, so that:

1. we can display the data in the UI (pricing table, billing section, etc.)
2. create the correct checkout session
3. make some features work correctly - such as per-seat billing

The billing schema is common to all billing providers. Some billing providers have some differences in what you can or cannot do. In these cases, the schema will try to validate and enforce the rules - but it's up to you to make sure the data is correct.

The schema is based on three main entities:

1. **Products**: The main product you are selling (e.g., "Pro Plan", "Starter Plan", etc.)
2. **Plans**: The pricing plan for the product (e.g., "Monthly", "Yearly", etc.)
3. **Line Items**: The line items for the plan (e.g., "flat subscription", "metered usage", "per seat", etc.)

#### Getting the schema right is important

Getting the IDs of your plans is extremely important - as these are used to:
1. create the correct checkout
2. populate the data in the DB

Please take it easy while you configure this, do one step at a time, and test it thoroughly.

#### Setting the Billing Provider

The billing provider is already set as `process.env.NEXT_PUBLIC_BILLING_PROVIDER` and defaults to `stripe`.

For clarity - this is set in the `apps/web/config/billing.config.ts` file:

```tsx
export default createBillingSchema({
  // also update config.billing_provider in the DB to match the selected
  provider,
  // products configuration
  products: []
});
```

We will now add the products to the configuration.

#### Products

Products are the main product you are selling. They are defined by the following fields:

```tsx
export default createBillingSchema({
  provider,
  products: [
    {
      id: 'starter',
      name: 'Starter',
      description: 'The perfect plan to get started',
      currency: 'USD',
      badge: `Value`,
      plans: [],
    }
  ]
});
```

Let's break down the fields:

1. **id**: The unique identifier for the product. **This is chosen by you, it doesn't need to be the same one as the one in the provider**.
2. **name**: The name of the product
3. **description**: The description of the product
4. **currency**: The currency of the product
5. **badge**: A badge to display on the product (e.g., "Value", "Popular", etc.)

The majority of these fields are going to populate the pricing table in the UI.

#### Plans

Plans are the pricing plans for the product. They are defined by the following fields:

```tsx
export default createBillingSchema({
  provider,
  products: [
    {
      id: 'starter',
      name: 'Starter',
      description: 'The perfect plan to get started',
      currency: 'USD',
      badge: `Value`,
      plans: [
        {
          name: 'Starter Monthly',
          id: 'starter-monthly',
          trialDays: 7,
          paymentType: 'recurring',
          interval: 'month',
          lineItems: [],
        }
      ],
    }
  ]
});
```

Let's break down the fields:
- **name**: The name of the plan
- **id**: The unique identifier for the plan. **This is chosen by you, it doesn't need to be the same one as the one in the provider**.
- **trialDays**: The number of days for the trial period
- **paymentType**: The payment type (e.g., `recurring`, `one-time`)
- **interval**: The interval of the payment (e.g., `month`, `year`)
- **lineItems**: The line items for the plan

Now, we will be looking at the line items. The line items are the items that make up the plan, and can be of different types:
1. **Flat Subscription**: A flat subscription (e.g., $10/month) - specified as `flat`
2. **Metered Billing**: Metered billing (e.g., $0.10 per 1,000 requests) - specified as `metered`
3. **Per-Seat Billing**: Per-seat billing (e.g., $10 per seat) - specified as `per-seat`

You can add one or more line items to the plan when using Stripe. When using Lemon Squeezy, you can only add one line item - but you can decorate it with the necessary metadata to achieve a similar result.

#### Flat Subscriptions

Flat subscriptions are defined by the following fields:

```tsx

export default createBillingSchema({
  provider,
  products: [
    {
      id: 'starter',
      name: 'Starter',
      description: 'The perfect plan to get started',
      currency: 'USD',
      badge: `Value`,
      plans: [
        {
          name: 'Starter Monthly',
          id: 'starter-monthly',
          trialDays: 7,
          paymentType: 'recurring',
          interval: 'month',
          lineItems: [
            {
              id: 'price_1NNwYHI1i3VnbZTqI2UzaHIe',
              name: 'Addon 2',
              cost: 9.99,
              type: 'flat',
            },
          ],
        }
      ],
    }
  ]
});
```

Let's break down the fields:
- **id**: The unique identifier for the line item. **This must match the price ID in the billing provider**. The schema will validate this, but please remember to set it correctly.
- **name**: The name of the line item
- **cost**: The cost of the line item
- **type**: The type of the line item (e.g., `flat`, `metered`, `per-seat`). In this case, it's `flat`.

The cost is set for UI purposes. **The billing provider will handle the actual billing** - therefore, **please make sure the cost is correctly set in the billing provider**.

#### Metered Billing

Metered billing is defined by the following fields:

```tsx
export default createBillingSchema({
  provider,
  products: [
    {
      id: 'starter',
      name: 'Starter',
      description: 'The perfect plan to get started',
      currency: 'USD',
      badge: `Value`,
      plans: [
        {
          name: 'Starter Monthly',
          id: 'starter-monthly',
          trialDays: 7,
          paymentType: 'recurring',
          interval: 'month',
          lineItems: [
            {
              id: 'price_1NNwYHI1i3VnbZTqI2UzaHIe',
              name: 'Addon 2',
              cost: 0,
              type: 'metered',
              unit: 'GBs',
              tiers: [
                {
                    upTo: 10,
                    cost: 0.1,
                },
                {
                    upTo: 100,
                    cost: 0.05,
                },
                {
                    upTo: 'unlimited',
                    cost: 0.01,
                }
              ]
            },
          ],
        }
      ],
    }
  ]
});
```

Let's break down the fields:
- **id**: The unique identifier for the line item. **This must match the price ID in the billing provider**. The schema will validate this, but please remember to set it correctly.
- **name**: The name of the line item
- **cost**: The cost of the line item. This can be set to `0` as the cost is calculated based on the tiers.
- **type**: The type of the line item (e.g., `flat`, `metered`, `per-seat`). In this case, it's `metered`.
- **unit**: The unit of the line item (e.g., `GBs`, `requests`, etc.). You can use a translation key here.
- **tiers**: The tiers of the line item. Each tier is defined by the following fields:
  - **upTo**: The upper limit of the tier. If the usage is below this limit, the cost is calculated based on this tier.
  - **cost**: The cost of the tier. This is the cost per unit.
  
The tiers data is used exclusively for UI purposes. **The billing provider will handle the actual billing** - therefore, **please make sure the tiers are correctly set in the billing provider**.

#### Per-Seat Billing

Per-seat billing is defined by the following fields:

```tsx
export default createBillingSchema({
  provider,
  products: [
    {
      id: 'starter',
      name: 'Starter',
      description: 'The perfect plan to get started',
      currency: 'USD',
      badge: `Value`,
      plans: [
        {
          name: 'Starter Monthly',
          id: 'starter-monthly',
          trialDays: 7,
          paymentType: 'recurring',
          interval: 'month',
          lineItems: [
            {
              id: 'price_1NNwYHI1i3VnbZTqI2UzaHIe',
              name: 'Addon 2',
              cost: 0,
              type: 'per_seat',
              tiers: [
                {
                    upTo: 3,
                    cost: 0,
                },
                {
                    upTo: 5,
                    cost: 7.99,
                },
                {
                    upTo: 'unlimited',
                    cost: 5.99,
                }
              ]
            },
          ],
        }
      ],
    }
  ]
});
```

Let's break down the fields:
- **id**: The unique identifier for the line item. **This must match the price ID in the billing provider**. The schema will validate this, but please remember to set it correctly.
- **name**: The name of the line item
- **cost**: The cost of the line item. This can be set to `0` as the cost is calculated based on the tiers.
- **type**: The type of the line item (e.g., `flat`, `metered`, `per-seat`). In this case, it's `per-seat`.
- **tiers**: The tiers of the line item. Each tier is defined by the following fields:
  - **upTo**: The upper limit of the tier. If the usage is below this limit, the cost is calculated based on this tier.
  - **cost**: The cost of the tier. This is the cost per unit.

If you set the first tier to `0`, it basically means that the first `n` seats are free. This is a common practice in per-seat billing.

Please remember that the cost is set for UI purposes. **The billing provider will handle the actual billing** - therefore, **please make sure the cost is correctly set in the billing provider**.

#### One-Off Payments

One-off payments are defined by the following fields:

```tsx
export default createBillingSchema({
  provider,
  products: [
    {
      id: 'starter',
      name: 'Starter',
      description: 'The perfect plan to get started',
      currency: 'USD',
      badge: `Value`,
      plans: [
        {
          name: 'Starter Monthly',
          id: 'starter-monthly',
          paymentType: 'one-time',
          lineItems: [
            {
              id: 'price_1NNwYHI1i3VnbZTqI2UzaHIe',
              name: 'Addon 2',
              cost: 9.99,
              type: 'flat',
            },
          ],
        }
      ],
    }
  ]
});
```

Let's break down the fields:
- **name**: The name of the plan
- **id**: The unique identifier for the line item. **This must match the price ID in the billing provider**. The schema will validate this, but please remember to set it correctly.
- **paymentType**: The payment type (e.g., `recurring`, `one-time`). In this case, it's `one-time`.
- **lineItems**: The line items for the plan
  - **id**: The unique identifier for the line item. **This must match the price ID in the billing provider**. The schema will validate this, but please remember to set it correctly.
  - **name**: The name of the line item
  - **cost**: The cost of the line item
  - **type**: The type of the line item (e.g., `flat`). It can only be `flat` for one-off payments.

### Adding more Products, Plans, and Line Items

Simply add more products, plans, and line items to the arrays. The UI **should** be able to handle it in most traditional cases. If you have a more complex billing schema, you may need to adjust the UI accordingly.

## Custom Plans

Sometimes - you want to display a plan in the pricing table - but not actually have it in the billing provider. This is common for custom plans, free plans that don't require the billing provider subscription, or plans that are not yet available.

To do so, let's add the `custom` flag to the plan:

```tsx
{
  name: 'Enterprise Monthly',
  id: 'enterprise-monthly',
  paymentType: 'recurring',
  label: 'common:contactUs',
  href: '/contact',
  custom: true,
  interval: 'month',
  lineItems: [],
}
```

Here's the full example:

```tsx
export default createBillingSchema({
  provider,
  products: [
    {
      id: 'starter',
      name: 'Starter',
      description: 'The perfect plan to get started',
      currency: 'USD',
      badge: `Value`,
      plans: [
        {
          name: 'Enterprise',
          id: 'enterprise',
          paymentType: 'recurring',
          label: 'common:contactUs',
          href: '/contact',
          custom: true,
          interval: 'month',
          lineItems: [],
        }
      ],
    }
  ]
});
```

As you can see, the plan is now a custom plan. The UI will display the plan in the pricing table, but it won't be available for purchase.

We do this by adding the following fields:

- **custom**: A flag to indicate that the plan is custom. This will prevent the plan from being available for purchase.
- **label**: The translation key for the label. This is used to display the label in the pricing table.
- **href**: The link to the page where the user can contact you. This is used in the pricing table.
- **lineItems**: The line items for the plan. This is empty as there are no line items for the plan. It must be an empty array.

### Custom Button Label
You can also provide a custom button label for the plan. This is done by adding the `buttonLabel` field:

```tsx
{
  name: 'Enterprise',
  id: 'enterprise',
  paymentType: 'recurring',
  label: 'common:contactUs',
  href: '/contact',
  custom: true,
  interval: 'month',
  lineItems: [],
  buttonLabel: 'common:contactUs',
}
```

As usual, strings can either be a translation key or a string. If it's a translation key, it will be translated using the `i18n` library.

Learn how to configure the plans in your Makerkit application

Writing the billing schema in the Next.js Supabase Kit


Stripe is the default billing provider in both the local config and the DB, so you don't need to set these values if you want to use Stripe.

For Stripe, you'll need to set the following environment variables:

```bash
STRIPE_SECRET_KEY=
STRIPE_WEBHOOK_SECRET=
NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY=
```

While the `NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY` is public and can be added anywhere - **please do not add the secret keys** to the `.env` file.

During development, you can place them in `.env.local` as it's not committed to the repository. In production, you can set them in the environment variables of your hosting provider.

## Stripe CLI

The Stripe CLI which allows you to listen to Stripe events straight to your own localhost. You can install and use the CLI using a variety of methods, but we recommend using Docker - since you already have it installed.

First - login to your Stripe account using the project you want to run:

```bash
docker run --rm -it --name=stripe -v ~/.config/stripe:/root/.config/stripe stripe/stripe-cli:latest login
```

Copy the webhook secret displayed in the terminal and set it as the `STRIPE_WEBHOOK_SECRET` environment variable in your `.env.local` file:

```bash
STRIPE_WEBHOOK_SECRET=*your_webhook_secret*
```

Now, you can listen to Stripe events running the following command:

```bash
pnpm run stripe:listen
```

**If you have not logged in - the first time you set it up, you are required to sign in**. This is a one-time process. Once you sign in, you can use the CLI to listen to Stripe events.

**Please sign in and then re-run the command**. Now, you can listen to Stripe events.

If you're not receiving events, please make sure that:

1. the webhook secret is correct
2. the account you signed in is the same as the one you're using in your app

## Configuring the Stripe Customer Portal

Stripe requires you to set up the Customer Portal so that users can manage their billing information, invoices and plan settings from there.

<Image src='/assets/images/docs/stripe-customer-portal.webp' width="2712" height="1870" />

1. Please make sure to enable the setting that lets users switch plans
2. Configure the behavior of the cancellation according to your needs

## Setting Production Webhooks in Stripe

When going to production, you will need to set the webhook URL and the events you want to listen to in Stripe.

The webhook path is `/api/billing/webhook`. If your app is hosted at `https://myapp.com` then you need to enter `https://myapp.com/api/billing/webhook`.

Makerkit needs the following events to work:

1. `checkout.session.completed`
2. `customer.subscription.updated`
3. `customer.subscription.deleted`

Only if you're using one-off payments, please add:

1. `checkout.session.async_payment_failed`
2. `checkout.session.async_payment_succeeded`

If your application needs more events, please add them, [but remember to handle them](billing-webhooks).

You can [handle additional events](billing-webhooks) by adding the required handlers in the `api/billing/webhook/route.ts` file.

### Setting Stripe Trials without collecting a card

Makerkit allows you to set trials without collecting a card. This is useful if you want to offer a free trial for your users.

To do so, you need to set the `STRIPE_ENABLE_TRIAL_WITHOUT_CC` environment variable to `true`.

```bash
STRIPE_ENABLE_TRIAL_WITHOUT_CC=true
```

Of course - you also must set a trial period for the plan you want to offer a free trial for.


Learn how to configure Stripe in the Makerkit Next.js Supabase SaaS Kit

Configuring Stripe Billing


For using Lemon Squeezy, we need to first set it as the default billing provider:

```bash
NEXT_PUBLIC_BILLING_PROVIDER=lemon-squeezy
```

Also, we need to switch the DB config to use Lemon Squeezy

```sql
update config set billing_provider = 'lemon-squeezy';
```

Then, you'll need to set the following environment variables:

```bash
LEMON_SQUEEZY_SECRET_KEY=
LEMON_SQUEEZY_SIGNING_SECRET=
LEMON_SQUEEZY_STORE_ID=
```

I am aware you know this, but never add these variables to the `.env` file. Instead, add them to the environment variables of your CI/CD system.

To test locally, you can add them to the `.env.local` file. This file is not committed to Git, therefore it is safe to store sensitive information in it.

### Schema Definition

Makerkit's billing configuration allows adding multiple line items into a single subscription: for example, you can mix flat fees, metered usage, and per-seat billing.

Lemon Squeezy **does not support multiple line items** like Stripe. The billing schema will fail validation if you do so, and you will need to adjust it.

However, with Lemon Squeezy, you can adjust various fields to fit your needs, albeit with very limited flexibility.

#### Metered Usage

Metered Usage can only be applied to the entire subscription, not to individual line items. For example, if you have a plan that charges $1 per 1000 requests, you can set the `tiers` property to charge $1 per 1000 requests.

However, you cannot have a plan that charges $1 per 1000 requests for one line item and $2 per 1000 requests for another line item. Or using a flat fee for one line item and metered usage for another.

#### Setup Fee + Metered Usage

Lemon Squeezy has support for the property `setupFee`: this property allows you to create a metered usage plan with a setup fee. That is, assuming you have a plan that charges a flat fee of $10 and then $1 per 1000 requests, you can set the `setupFee` to 10 and then set up the `tiers` to charge $1 per 1000 requests.

NB: the setup fee is only charged once, when the subscription is created.

### Testing locally

To receive webhooks from Lemon Squeezy, you need a proxy. You can create one for free with `ngrok` (or others). Once set up, create a webhook in Lemon Squeezy pointing to `{proxy-url}/api/billing/webhook` where `{proxy-url}` is a valid URL pointing to your local machine.

If your proxy is for example `https://myawesomeproxy.com` you will use `https://myawesomeproxy.com/api/billing/webhook` as the endpoint in Lemon Squeezy.

### Production

When going to production, you will set your exact application URL and scratch `{proxy-url}`. Don't forget, please.

Please set the following webhook events in Lemon Squeezy:

1. `order_created`
2. `subscription_created`
3. `subscription_updated`
4. `subscription_expired`


Lemon Squeezy is a payment processor that allows you to charge your users for your SaaS product. It is a Merchant of Record, which means they handle all the billing and compliance for you.

Configuring Lemon Squeezy Billing


Hi, Paddle is not yet available.

The integration will be developed after Paddle releases their Customer Portal.

Stay tuned!


Paddle is a payment processor that allows you to charge your users for your SaaS product. It is a Merchant of Record, which means they handle all the billing and compliance for you.

Configuring Paddle Billing


Metered usage billing is a billing model where you charge your customers based on their usage of your product. This model is common in APIs, where you charge based on the number of requests made to your API.

As we have already seen in the schema definition section, we can define a metered usage plan in the billing schema. This plan will charge the customer based on the number of requests they make to your API.

### Providers Differences

NB: different providers (Stripe, Lemon Squeezy, etc.) have different ways of handling metered usage billing: we keep the API consistent across all providers - but the details of how you report usage to the billing provider may differ. Please read the provider's documentation to understand how to report usage to the billing provider.

### Defining a Metered Usage Plan

Let's assume we have the following schema:

```tsx

export default createBillingSchema({
  provider,
  products: [
    {
      id: 'starter',
      name: 'Starter',
      description: 'The perfect plan to get started',
      currency: 'USD',
      badge: `Value`,
      plans: [
        {
          name: 'Starter Monthly',
          id: 'starter-monthly',
          trialDays: 7,
          paymentType: 'recurring',
          interval: 'month',
          lineItems: [
            {
              id: 'price_1NNwYHI1i3VnbZTqI2UzaHIe',
              name: 'Addon 2',
              cost: 0,
              type: 'metered',
              unit: 'GBs',
              tiers: [
                {
                    upTo: 10,
                    cost: 0.1,
                },
                {
                    upTo: 100,
                    cost: 0.05,
                },
                {
                    upTo: 'unlimited',
                    cost: 0.01,
                }
              ]
            },
          ],
        }
      ],
    }
  ]
});
```

What happens here is that we create a checkout in Stripe that charges the customer based on the number of GBs they use. The first 10 GBs are free, the next 90 GBs are charged at $0.05 per GB, and anything above 100 GBs is charged at $0.01 per GB.

When the checkout succeeds, we store two records:

1. A `subscriptions` record that represents the subscription the customer has to the plan. This is the overall subscription record - and contains details like the customer's ID, the plan ID, the status of the subscription, etc.
2. A `subscription_items` record that represents the line item the customer is subscribed to. This is needed for reporting charges to the billing provider.

The billing service in Makerkit has a unified interface for interacting with your billing provider - whichever it may be. This means that you can switch from Stripe to Lemon Squeezy or any other billing provider without changing your code. As such - this is valid for all billing providers supported by Makerkit.

When we report a charge, we need three things:
1. the subscription ID (and billing provider it is associated with) or the Customer ID (Stripe)
2. the line item ID (Lemon Squeezy only)
3. the next quantity of the line item

The billing service will then calculate the charge based on the quantity and the cost of the line item and charge the user accordingly.

On our side, we need to identify what the user is being charged for. This is why we store the `subscription_items` record. This record contains the `subscription_id`, the `product_id`, the `variant_id` (price ID in Stripe) and the `line_item_id` - which we can use to identify what the user is being charged for. You can query the items using these details to retrieve the ID of the line item the user is being charged for.

We assume an account uses a function `consumeApi` to consume the API. This (hypothetical) function will be called every time the user makes a request to the API. We can then use this function to report the usage to the billing provider.

```tsx
export async function consumeApi(accountId: string): number {}
```

When the user makes a request to the API, we can call this function to report the usage to the billing provider.

```tsx
async function apiHandler(accountId: string) {
  try {
    // assume consumeApi returns the number of requests made
    const quantity = await consumeApi(accountId);

    await reportUsage(accountId, quantity);
  } catch (error) {
    console.error(error);
  }
}
```

### Reporting Usage in Stripe

Makerkit uses the newest [usage reporting API in Stripe](https://docs.stripe.com/billing/subscriptions/usage-based/implementation-guide). This API allows you to report usage for a subscription item. You can report usage for a subscription item by calling the `reportUsage` method on the billing service.

Unlike the previous version of the API, you don't need a subscription item ID, but the customer ID and the metric name you're reporting.

We assume you have created a metric in Stripe named `api_requests` that you use to report the usage.

```tsx
import { getBillingGatewayProvider } from '@kit/billing-gateway';
import { getSupabaseServerClient } from '@kit/supabase/server-client';
import { createAccountsApi } from '@kit/accounts/api';

async function reportUsage(
  accountId: string,
  quantity: number
) {
  // use the correct client: in this case, the server action client
  const client = getSupabaseServerClient();
  const api = createAccountsApi(client);

  const subscription = await api.getSubscription(accountId);

  // if the subscription is not active, we don't report usage
  if (!subscription) {
    throw new Error('No active subscription found');
  }

  // get the billing provider
  const service = await getBillingGatewayProvider(this.client);
  const customerId = await api.getCustomerId(accountId);

  if (!customerId) {
    throw new Error(`No customer ID found for account ${accountId}`);
  }

  // now we can report the usage to the billing provider
  return service.reportUsage({
    id: customerId,
    eventName: 'api_requests',
    usage: {
      quantity,
    }
  });
}
```

As you can see, we use the following parameters to report usage:
1. `id`: the customer ID of the user/account in Stripe
2. `eventName`: the name of the metric you're reporting
3. `usage`: the quantity of the metric you're reporting

### Reporting Usage in Lemon Squeezy

In Lemon Squeezy, you need to report usage for a subscription item.

Given an account ID - we need to retrieve the subscription ID and the line item ID. We can then report the usage to the billing provider.

```tsx
import { getBillingGatewayProvider } from '@kit/billing-gateway';
import { getSupabaseServerClient } from '@kit/supabase/server-client';
import { createAccountsApi } from '@kit/accounts/api';

async function reportUsage(
  accountId: string, 
  quantity: number
) {
  // use the correct client: in this case, the server action client
  const client = getSupabaseServerClient();
  const api = createAccountsApi(client);

  const subscription = await api.getSubscription(accountId);

  // if the subscription is not active, we don't report usage
  if (!subscription) {
    console.error('No active subscription found');
    return;
  }

  // now, we need to find the line item the user is being charged for
  // let's use Supabase for this!
  // we use the product ID to identify the line item
  // in your case, you have more choices to identify the line item
  const {
    data: subscriptionItem,
    error
  } = await client.from('subscription_items')
    .select('id')
    .eq('subscription_id', subscription.id)
    .eq('product_id', 'starter-pro')
    .eq('type', 'metered')
    .single();

  // get the billing provider
  const service = await getBillingGatewayProvider(this.client);

  // now we can report the usage to the billing provider
  return service.reportUsage({
    id: subscriptionItem.id,
    usage: {
      quantity,
      action: 'increment'
    }
  });
}
```

Metered usage billing is a billing model where you charge your customers based on their usage of your product. This model is common in APIs, where you charge based on the number of requests made to your API.

Configuring Metered Usage Billing


Per Seat billing is a common pricing model for SaaS applications where customers are charged based on the number of seats (users) they have in the application. In this guide, we'll show you how to configure per seat billing in Makerkit.

Makerkit will automatically:
1. understand if your pricing model depends on the number of seats (using the `per_seat` line item type in your pricing model)
2. calculate the number of seats based on the members count in a Team account
3. report the number of seats to your billing system when subscribing
4. report the number of seats to your billing system when adding or removing members

## Define a per-seat billing schema

Per-seat billing is defined by the following fields:

```tsx
export default createBillingSchema({
  provider,
  products: [
    {
      id: 'starter',
      name: 'Starter',
      description: 'The perfect plan to get started',
      currency: 'USD',
      badge: `Value`,
      plans: [
        {
          name: 'Starter Monthly',
          id: 'starter-monthly',
          trialDays: 7,
          paymentType: 'recurring',
          interval: 'month',
          lineItems: [
            {
              id: 'price_1NNwYHI1i3VnbZTqI2UzaHIe',
              name: 'Addon 2',
              cost: 0,
              type: 'per_seat',
              tiers: [
                {
                    upTo: 3,
                    cost: 0,
                },
                {
                    upTo: 5,
                    cost: 7.99,
                },
                {
                    upTo: 'unlimited',
                    cost: 5.99,
                }
              ]
            },
          ],
        }
      ],
    }
  ]
});
```

Let's break down the fields:
- **id**: The unique identifier for the line item. **This must match the price ID in the billing provider**. The schema will validate this, but please remember to set it correctly.
- **name**: The name of the line item
- **cost**: The cost of the line item. This can be set to `0` as the cost is calculated based on the tiers.
- **type**: The type of the line item (e.g., `flat`, `metered`, `per-seat`). In this case, it's `per-seat`.
- **tiers**: The tiers of the line item. Each tier is defined by the following fields:
- **upTo**: The upper limit of the tier. If the usage is below this limit, the cost is calculated based on this tier.
- **cost**: The cost of the tier. This is the cost per unit.

If you set the first tier to `0`, it basically means that the first `n` seats are free. This is a common practice in per-seat billing.

Please remember that the cost is set for UI purposes. **The billing provider will handle the actual billing** - therefore, **please make sure the cost is correctly set in the billing provider**.

## Report the number of seats

This is done automatically for you. Makerkit will report the number of seats to your billing provider when subscribing, and when adding or removing members.

Learn how to setup per seat billing in Makerkit to charge customers for additional seats (users) in your application.

How to configure per seat billing in Makerkit


Credit-based billing is a billing model where you charge your users based on the number of credits they consume. This model is useful when you want to charge your users based on the number of actions they perform in your application.

As you may know, this is extremely popular for AI SaaS products, where users may have a limited amount of tokens (or credits) to perform actions - such as requesting data from an LLM.

Makerkit doesn't have a built-in credit-based billing system, but you can easily implement it using the existing billing system.

To do so, we can introduce two new tables to our database: `plans` and `credits`. The `plans` table will store the pricing information for each plan, and the `credits` table will store the credits consumed by each user.

Here's how you can set it up:

### Step 1: Create the `plans` table

First we need to create a `plans` table to store the pricing information for each plan.

```sql
create table public.plans (
  id serial primary key,
  name text not null,
  variant_id text not null
);

alter table public.plans enable row level security;

-- allow authenticated users to read plans
create policy read_plans
  on public.plans
  for select
  to authenticated
  using (true);
```

We've created a `plans` table with two columns: `name` and `variant_id`. The `name` column stores the name of the plan, and the `variant_id` column stores the ID of the plan variant.

We also enabled row-level security on the `plans` table and created a policy that allows authenticated users to read the plans.

### Step 2: Create the `credits` table

Next, we need to create a `credits` table to store the credits consumed by each user.

```sql
create table public.credits (
  account_id uuid not null references public.accounts(id),
  tokens integer not null
);

alter table public.credits enable row level security;

-- allow authenticated users to read their credits
create policy read_credits
  on public.credits
  for select
  to authenticated
  using (
    account_id = (select auth.uid())
  );
```

In the above SQL, we create two tables: `plans` and `credits`. The `plans` table stores the pricing information for each plan, and the `credits` table stores the credits consumed by each user.

We also enabled row-level security on the `credits` table and created a policy that allows authenticated users to read their credits.

### Step 3: Functions to manage credits

Next, we need to create functions to manage the credits. We'll call these functions `has_credits` and `consume_credits`.

```sql
create or replace function public.has_credits(account_id uuid, tokens integer)
  returns boolean
  set search_path = ''
  as $$
  begin
    return (select tokens >= tokens from public.credits where account_id = account_id);
  end;
  $$ language plpgsql;

grant execute on function public.has_credits to authenticated, service_role;
```

The `has_credits` function checks if the user has enough credits to perform an action. It takes the `account_id` and the number of tokens required as arguments and returns `true` if the user has enough credits, `false` otherwise.

```sql
create or replace function public.consume_credits(account_id uuid, tokens integer)
  returns void
  set search_path = ''
  as $$
  begin
    update public.credits set tokens = tokens - tokens where account_id = account_id;
  end;
  $$ language plpgsql;

grant execute on function public.has_credits to service_role;
```

You can now use these functions in your RLS policies, or in your application code to manage credits.

NB: we only allow authenticated users to read their credits. To update the credits, we use the service role key, since we lock down the `credits` table to only allow authenticated users to read their credits.

### Step 4: Using credits in your application

Now that you have set up the `plans` and `credits` tables, you can use them in your application to manage credits.

For example, when a user performs an action that consumes credits, you can call the `consume_credits` function to deduct the credits from the user's account. You can use the Supabase client to call the function from your application code.

NB: the `callOpenAIApi` is a placeholder for your API call to OpenAI. You should replace it with your actual API call.

NB: we assume this is in a route handler, so we use the `getSupabaseRouteHandlerClient` client. If you're in a server action, you should use the `getSupabaseServerClient` client. [Learn more about the Supabase clients here](supabase-clients).

```tsx
export function async consumeApi(accountId: string) {
  // Call the OpenAI API to get the usage
  const { usage, data } = await callOpenAIApi();

  const client = getSupabaseRouteHandlerClient({
    admin: true,
  });

  await client.rpc('consume_credits', {
    account_id: accountId,
    tokens: usage,
  });

  return data;
}
```

You can also use the function `has_credits` as part of your RLS policy to restrict access to certain resources based on the user's credits.

```sql
create policy tasks_write_policy
  on public.tasks
  for select
  using (
    (select auth.uid()) === account_id and
    public.has_credits((select auth.uid()), 1)
  );
```

### Step 5: Recharge credits

You can use webhooks from your billing provider to recharge credits when a user makes a payment. To do so, listen to events and update the `credits` table accordingly.

In the example below, we extend the webook handler to listen to the `onInvoicePaid` event and update the `credits` table with the new credits.

1. First, update the existing webhook handler to listen to the `onInvoicePaid` event.
2. Then, update the `credits` table with the new credits.

```tsx title="apps/web/app/api/billing/webhook.ts"
import { getBillingEventHandlerService } from '@kit/billing-gateway';
import { enhanceRouteHandler } from '@kit/next/routes';
import { getLogger } from '@kit/shared/logger';
import { getSupabaseServerAdminClient } from '@kit/supabase/server-admin-client';

import billingConfig from '~/config/billing.config';
import { Database } from '~/lib/database.types';

/**
 * @description Handle the webhooks from Stripe related to checkouts
 */
export const POST = enhanceRouteHandler(
  async ({ request }) => {
    const provider = billingConfig.provider;
    const logger = await getLogger();

    const ctx = {
      name: 'billing.webhook',
      provider,
    };

    logger.info(ctx, `Received billing webhook. Processing...`);

    const supabaseClientProvider = () =>
      getSupabaseServerAdminClient();

    const service = await getBillingEventHandlerService(
      supabaseClientProvider,
      provider,
      billingConfig,
    );

    try {
      await service.handleWebhookEvent(request, {
        onInvoicePaid: async (data) => {
          const accountId = data.target_account_id;
          const lineItems = data.line_items;

          // we only expect one line item in the invoice
          // if you add more than one, you need to handle that here
          // by finding the correct line item to get the variant ID
          const variantId = lineItems[0]?.variant_id;

          if (!variantId) {
            logger.error(
              {
                accountId,
              },
              'Variant ID not found in line items',
            );

            throw new Error('Variant ID not found in invoice');
          }

          await updateMessagesCountQuota({
            variantId,
            accountId,
          });
        },
      });

      logger.info(ctx, `Successfully processed billing webhook`);

      return new Response('OK', { status: 200 });
    } catch (error) {
      logger.error({ ...ctx, error }, `Failed to process billing webhook`);

      return new Response('Failed to process billing webhook', {
        status: 500,
      });
    }
  },
  {
    auth: false,
  },
);

async function updateMessagesCountQuota(params: {
  variantId: string;
  accountId: string;
}) {
  const client = getSupabaseRouteHandlerClient<Database>({ admin: true });

  // get the max messages for the price based on the price ID
  const plan = await client
    .from('plans')
    .select('tokens_quota')
    .eq('variant_id', params.variantId)
    .single();

  if (plan.error) {
    throw plan.error;
  }

  const { tokens_quota } = plan.data;

  // upsert the message count for the account
  // and set the period start and end dates (from the subscription)
  const response = await client
    .from('credits')
    .update({
      tokens_quota,
    })
    .eq('account_id', params.accountId);

  if (response.error) {
    throw response.error;
  }
}
```

We assume that we have a table named `plans` that stores the pricing information for each plan. We also assume that we have a table named `credits` that stores the credits consumed by each user.
The `credits` table has a column named `tokens_quota` that stores the number of credits available to the user.

In the `onInvoicePaid` event handler, we get the variant ID from the invoice line items and update the `credits` table with the new credits.

Learn how to configure credit based usage in your Next.js Supabase application


While not exactly a common SaaS billing mode, Makerkit offers support for one-off payments.

You can use the tables `orders` and `orders_items` to store single orders for products not recurring in nature. You can use this in two ways:

1. **Lifetime Access**: for products that are not recurring but offer lifetime access.
2. **Multiple one-off payments**: for products that are not recurring but can be purchased multiple times. For example, you have multiple add-ons that can be purchased separately.

Some of this will require custom code, but generally speaking, Makerkit does its best to support this use case in a broad sense. The specifics of your implementation will depend on your product and business model and may require additional customization.

## Schema Definition

One-off payments are defined by the following fields:

```tsx
export default createBillingSchema({
  provider,
  products: [
    {
      id: 'starter',
      name: 'Starter',
      description: 'The perfect plan to get started',
      currency: 'USD',
      badge: `Value`,
      plans: [
        {
          name: 'Starter Monthly',
          id: 'starter-monthly',
          paymentType: 'one-time',
          lineItems: [
            {
              id: 'price_1NNwYHI1i3VnbZTqI2UzaHIe',
              name: 'Addon 2',
              cost: 9.99,
              type: 'flat',
            },
          ],
        }
      ],
    }
  ]
});
```

Let's break down the fields:
- **name**: The name of the plan
- **id**: The unique identifier for the line item. **This must match the price ID in the billing provider**. The schema will validate this, but please remember to set it correctly.
- **paymentType**: The payment type (e.g., `recurring`, `one-time`). In this case, it's `one-time`.
- **lineItems**: The line items for the plan
  - **id**: The unique identifier for the line item. **This must match the price ID in the billing provider**. The schema will validate this, but please remember to set it correctly.
  - **name**: The name of the line item
  - **cost**: The cost of the line item
  - **type**: The type of the line item (e.g., `flat`). It can only be `flat` for one-off payments.

When a products gets purchased, Makerkit will create an order in the `orders` table and an order item in the `orders_items` table. You can use this data to fulfill the order and grant access to the product.

If you would like to switch from `subscriptions` to `orders` as your primary billing mechanism, you can do so by setting the following environment variable:

```bash
BILLING_MODE=one-time
```

When this flags in set to `one-time`, Makerkit's plan's page will be looking for a valid order in the `orders` table instead of a subscription in the `subscriptions` table. This means that the billing section will display one-off payments instead of subscriptions.

As mentioned - this is a best-effort implementation. You may need to customize the billing pages to fit your specific use case.

How to configure one-off payments in Makerkit for products that are not recurring in nature.

Configuring One Off Payments


Makerkit takes care of handling billing webhooks to update the Database based on the events received from Stripe.

Sometimes - you will need to set more webhooks, or do something custom with the webhooks.

In these cases, you can customize the billing webhook handler in Makerkit at `api/billing/webhooks/route.ts`.

By default, the webhook handler is set to `service.handleWebhookEvent(request)`:

```tsx
await service.handleWebhookEvent(request);
```

However, you can extend it using the callbacks provided by the `BillingService`:

```tsx
await service.handleWebhookEvent(request, {
  onPaymentFailed: async (sessionId) => {},
  onPaymentSucceeded: async (sessionId) => {},
  onCheckoutSessionCompleted: async (subscription, customerId) => {},
  onSubscriptionUpdated: async (subscription) => {},
  onSubscriptionDeleted: async (subscriptionId) => {},
});
```

You can provide one or more of the callbacks to handle the events you are interested in.

If the event is not in one of these methods, you can handle it in the `onEvent` method:

```tsx
await service.handleWebhookEvent(request, {
  async onEvent(data: unknown) {
    logger.info(
      `Received billing event`,
    );

    // Your custom code here
  }
});
```

However, you need to set the correct interface for the `data` parameter to handle the event correctly.

For example, to handle the `invoice.payment_succeeded` event, you can use the `onEvent` method:

```tsx
await service.handleWebhookEvent(request, {
  async onEvent(data: unknown) {
    if (data.type === 'invoice.payment_succeeded') {
      const invoice = data as Stripe.Invoice;
      // Your custom code here
    }
  }
});
```

You can find the list of events and their data in the [Stripe documentation](https://stripe.com/docs/api/events/types).


Learn how to handle billing webhooks with your custom code in Makerkit


The Billing service API allows you to communicate with the billing service in Makerkit. You can use the API to manage billing for your preferred payment gateway.

To instantiate the billing service, you need to import the `createBillingGatewayService` function from the `@kit/billing-gateway` package. You can then use this service to manage subscriptions, one-off payments, and more.

```tsx
import { createBillingGatewayService } from '@kit/billing-gateway';

const service = createBillingGatewayService('stripe');
```

Of course - it's best to get the billing provider from the `subscriptions` record. This way, you can switch between providers without changing the code.

The `createBillingGatewayService` instantiates a class that provides a set of methods for managing billing operations. The provider is determined by the `BillingProviderSchema` passed to the constructor. The `BillingGatewayService` class is a TypeScript class that provides a set of methods for managing billing operations. It uses the Strategy design pattern to delegate the actual implementation of these operations to a provider-specific strategy. The provider is determined by the BillingProviderSchema passed to the constructor.

The class provides methods for creating and retrieving checkout sessions, creating a billing portal session, cancelling a subscription, reporting and querying usage, and updating a subscription. Each of these methods accepts a parameter object that is validated and parsed using the corresponding Zod schema.

## Methods

### Creating a checkout session

The `createCheckoutSession` method creates a checkout session for billing. It takes an object of type CreateBillingCheckoutSchema as a parameter, which contains the necessary information for creating a checkout session.

Below is the Zod schema accepted by the `createCheckoutSession` method:

```tsx
returnUrl: z.string().url(),
accountId: z.string().uuid(),
plan: PlanSchema,
customerId: z.string().optional(),
customerEmail: z.string().email().optional(),
enableDiscountField: z.boolean().optional(),
variantQuantities: z.array(
  z.object({
    variantId: z.string().min(1),
    quantity: z.number(),
  }),
)
```

### Retrieving a checkout session

The `retrieveCheckoutSession` method retrieves the checkout session from the specified provider. It takes an object of type RetrieveCheckoutSessionSchema as a parameter, which contains the necessary information to retrieve the checkout session.

The method accepts the following Zod schema:

```tsx
sessionId: z.string(),
```

### Creating a billing portal session

The `createBillingPortalSession` method creates a billing portal session. It takes an object of type CreateBillingPortalSessionSchema as a parameter, which contains the necessary information to create a billing portal session.

```tsx
returnUrl: z.string().url(),
customerId: z.string().min(1),
```

### Cancelling a subscription

The `cancelSubscription` method cancels a subscription. It takes an object of type CancelSubscriptionParamsSchema as a parameter, which contains the necessary information to cancel a subscription.

The method accepts the Zod schema:

```tsx
subscriptionId: z.string(),
invoiceNow: z.boolean().optional(),
```

### Reporting metered usage

The `reportUsage` method reports the usage of the billing to the provider. It takes an object of type ReportBillingUsageSchema as a parameter, which contains the necessary information to report the usage.

The method accepts the following Zod schema:

```tsx
id: z.string({
  description:
    'The id of the usage record. For Stripe a customer ID, for LS a subscription item ID.',
}),
eventName: z
  .string({
    description: 'The name of the event that triggered the usage',
  })
  .optional(),
usage: z.object({
  quantity: z.number(),
  action: z.enum(['increment', 'set']).optional(),
}),
```

### Querying metered usage

The `queryUsage` method queries the usage of the metered billing. It takes an object of type QueryBillingUsageSchema as a parameter, which contains the necessary information to query the usage.

To query usage, please provide the following Zod schema:

```tsx

const TimeFilter = z.object(
  {
    startTime: z.number(),
    endTime: z.number(),
  },
  {
    description: `The time range to filter the usage records. Used for Stripe`,
  },
);

const PageFilter = z.object(
  {
    page: z.number(),
    size: z.number(),
  },
  {
    description: `The page and size to filter the usage records. Used for LS`,
  },
);

export const QueryBillingUsageSchema = z.object({
  id: z.string({
    description:
      'The id of the usage record. For Stripe a meter ID, for LS a subscription item ID.',
  }),
  customerId: z.string({
    description: 'The id of the customer in the billing system',
  }),
  filter: z.union([TimeFilter, PageFilter]),
});

```

### Updating a subscription

The `updateSubscriptionItem` method updates a subscription with the specified parameters. It takes an object of type UpdateSubscriptionParamsSchema as a parameter, which contains the necessary information to update a subscription.

The method acceps the following Zod schema:

```tsx
subscriptionId: z.string().min(1),
subscriptionItemId: z.string().min(1),
quantity: z.number().min(1),
```

Learn how to use the Billing service API in Makerkit to manage billing for your preferred payment gateway

The Billing service API allows you to communicate with the billing service in Makerkit

Content


Makerkit implements a CMS interface that abstracts the implementation from where you store your data. It provides a simple API to interact with your data, and it's easy to extend and customize.

By default, Makerkit ships with two CMS implementations: 

1. [Keystatic](https://keystatic.com) - a CMS that stores data in a JSON file or on your Github repository
2. [Wordpress](https://wordpress.org) - needs no introduction

You can also create your own CMS implementation by extending the `CMS` class.

By default, we use Keystatic using `local` mode (eg. storing data in a JSON file). You can change the mode to `github` to store data in your Github repository or `cloud` to use their cloud service.

Local mode is the easiest way to get started since you need no setup. However, assuming you want to use edge-rendering, you'll need to switch to a remote mode (eg. Github) or a remote-only CMS (eg. Wordpress).


The CMS library in Makerkit abstracts the implementation from where you store your data. It provides a simple API to interact with your data, and it's easy to extend and customize.

Using the CMS interface in Makerkit


This implementation is used when the host app's environment variable is set as:

```bash
CMS_CLIENT=keystatic
```

Additionally, the following environment variables may be required:

```bash
NEXT_PUBLIC_KEYSTATIC_STORAGE_KIND=local # local, cloud, github
KEYSTATIC_PATH_PREFIX=apps/web
NEXT_PUBLIC_KEYSTATIC_CONTENT_PATH=./content # apps/web/content
```

You can also use Keystatic Cloud or GitHub as the storage kind as remote storage.

If `KEYSTATIC_STORAGE_KIND` is set to `cloud`, the following environment variables are required:

```bash
KEYSTATIC_STORAGE_KIND=cloud
KEYSTATIC_STORAGE_PROJECT=project-id
```

If `KEYSTATIC_STORAGE_KIND` is set to `github`, the following environment variables are required:

```bash
NEXT_PUBLIC_KEYSTATIC_STORAGE_KIND=github
NEXT_PUBLIC_KEYSTATIC_STORAGE_REPO=makerkit/next-supabase-saas-kit-turbo-demo
NEXT_PUBLIC_KEYSTATIC_CONTENT_PATH=./content
KEYSTATIC_GITHUB_TOKEN=github_**********************************************
KEYSTATIC_PATH_PREFIX=apps/web
```

Of course, you need to replace the `NEXT_PUBLIC_KEYSTATIC_STORAGE_REPO` and `KEYSTATIC_GITHUB_TOKEN` with your own values.

GitHub mode requires the installation of a GitHub app for displaying the admin.

Please refer to the [Keystatic documentation](https://keystatic.com/docs/github-model) for more information.

If your content folder is not at `content`, you can set the `NEXT_PUBLIC_KEYSTATIC_CONTENT_PATH` environment variable to the correct path. For example, if your content folder is at `data/content`, you can set the `NEXT_PUBLIC_KEYSTATIC_CONTENT_PATH` environment variable as:

```bash
NEXT_PUBLIC_KEYSTATIC_CONTENT_PATH=data/content
```

## Adding the Keystatic admin to your app

To add the Keystatic admin to your app, please run the following command:

```bash
turbo gen keystatic
```

Your app will now have a new route at `/keystatic` where you can manage your content.

**Note**: your Github token must have permissions to read to the repository (for read-only).


KeyStatic is a CMS that stores data in a JSON file or on your Github repository. It's the default CMS implementation in Makerkit.

Using KeyStatic in Makerkit


The Wordpress implementation is used when the host app's environment variable is set as:

```bash
CMS_CLIENT=wordpress
```

Additionally, please set the following environment variables:

```bash
WORDPRESS_API_URL=http://localhost:8080
```

For development purposes, we ship a Docker container that runs a Wordpress instance. To start the container, run:

```bash
docker-compose up
```

or

```bash
pnpm run start
```

from this package's root directory.

The credentials for the Wordpress instance are:

```bash
WORDPRESS_DB_HOST=db
WORDPRESS_DB_USER=wordpress
WORDPRESS_DB_PASSWORD=wordpress
WORDPRESS_DB_NAME=wordpress
```

You will be asked to set up the Wordpress instance when you visit `http://localhost:8080` for the first time.

## Note for Wordpress REST API

To make the REST API in your Wordpress instance work, please change the permalink structure to `/%post%/` from the Wordpress admin panel.

## Blog

To include Blog Posts from Wordpress - please create a **post** with category named `blog` and add posts to it.

## Documentation

To include Documentation from Wordpress - please create a **page** with category named `documentation` and add pages to it.

This **involves enabling categories for pages. To do this, add the following code to your theme's `functions.php` file:

```php
function add_categories_to_pages() {
    register_taxonomy_for_object_type('category', 'page');
}
add_action('init', 'add_categories_to_pages');
```

Please refer to `wp-content/themes/twentytwentyfour/functions.php` for an example of a theme that includes this code.

## Language Filtering

To make the language filtering work, please add a tag with the language name to the post. For example, if you have a post in English, add the tag `en` to it, and if you have a post in German, add the tag `de` to it.

Wordpress is a popular CMS that you can use with Makerkit. Learn how to set it up and use it in your project.

Using Wordpress in Makerkit


To fetch content from your CMS, you can use the CMS API. The CMS API is an interface that allows you to pull content from your CMS and display it on your website. This is useful if you want to display dynamic content on your website that is stored in your CMS.

### Creating a CMS client

To create a CMS client, you can use the `createCmsClient` function. This function returns a client that you can use to fetch content from your CMS.

```tsx
import { createCmsClient } from '@kit/cms';

const client = await createCmsClient();
```

The implementation depends on the CMS you are using. By default, the CMS client uses the `keystatic` CMS. If you are using a different CMS, you can specify the CMS client to use by setting the `CMS_CLIENT` environment variable.

```
CMS_CLIENT=keystatic
```

### Fetching content items

To fetch content items from your CMS, you can use the `getContentItems` function.

```tsx
// import the createCmsClient function
import { createCmsClient } from '@kit/cms';

// create a client
const client = await createCmsClient();

// Fetch content items
const { items, count } = await client.getContentItems({
  collection: 'posts',
});
```

The `getContentItems` function takes an object with the following properties:

1. `collection` - The collection to fetch content items from.
2. `limit` - The number of content items to fetch.
3. `offset` - The offset to start fetching content items from.
4. `language` - The language to fetch content items in.
5. `sortBy` - The field to sort content items by.
6. `sortDirection` - The direction to sort content items in.
7. `status` - The status of the content items to fetch. It can be one of `published`, `draft`, `pending` or `review`. By default, only `published` content items are fetched.

```tsx
import { createCmsClient } from '@kit/cms';

const getContentItems = cache(
  async (language: string | undefined, limit: number, offset: number) => {
    const client = await createCmsClient();

    return client.getContentItems({
      collection: 'posts',
      limit,
      offset,
      language,
      sortBy: 'publishedAt',
      sortDirection: 'desc',
    });
  },
);
```

NB: how these values are used is entirely dependent on the CMS you are using. For example, Wordpress will only support `posts` or `pages` as collections.

Additionally: how the language filtering is implemented is also dependent on the CMS you are using.

### Fetching a single content item

To fetch a single content item from your CMS, you can use the `getContentItemBySlug` function.

```tsx
import { createCmsClient } from '@kit/cms';

const client = await createCmsClient();

// Fetch a single content item
const item = await client.getContentItemBySlug({
  slug: 'hello-world',
  collection: 'posts'
});
```

The `getContentItemBySlug` function takes an object with the following properties:

1. `slug` - The slug of the content item to fetch.
2. `collection` - The collection to fetch the content item from.
3. `status` (optional): The status of the content item to fetch. It can be one of `published`, `draft`, `pending` or `review`. By default, only `published` content items are fetched.

#### Rendering pages using content from your CMS

You can use the `getContentItemBySlug` function to fetch content from your CMS and render pages using that content.

For example, if you want to store your Terms and Conditions in your CMS, you can fetch the content item for the Terms and Conditions page and render the page using that content.

```tsx
import { createCmsClient } from '@kit/cms';

async function TermsAndConditionsPage() {
  const client = await createCmsClient();

  const { content, title } = await client.getContentItemBySlug({
    slug: 'terms-and-conditions',
    collection: 'pages',
  });

  return (
    <div>
      <h1>{title}</h1>
      <div>{content}</div>
    </div>
  );
}
```

Introducing the CMS API that allows you to pull content from your CMS


Makerkit may not be able to accomodate everyone's preferences when it comes to CMSs. After all - there are too many to support! But that's okay - you can create your own CMS client using the CMS API in Makerkit.

To create your own CMS API, you need to implement the following methods:

```tsx
export abstract class CmsClient {
  /**
   * Retrieves content items based on the provided options.
   * @param options - Options for filtering and pagination.
   * @returns A promise that resolves to an array of content items.
   */
  abstract getContentItems(options?: Cms.GetContentItemsOptions): Promise<{
    total: number;
    items: Cms.ContentItem[];
  }>;

  /**
   * Retrieves a content item by its ID and type.
   * @returns A promise that resolves to the content item, or undefined if not found.
   */
  abstract getContentItemBySlug(params: {
    slug: string;
    collection: string;
  }): Promise<Cms.ContentItem | undefined>;

  /**
   * Retrieves categories based on the provided options.
   * @param options - Options for filtering and pagination.
   * @returns A promise that resolves to an array of categories.
   */
  abstract getCategories(
    options?: Cms.GetCategoriesOptions,
  ): Promise<Cms.Category[]>;

  /**
   * Retrieves a category by its slug.
   * @param slug - The slug of the category.
   * @returns A promise that resolves to the category, or undefined if not found.
   */
  abstract getCategoryBySlug(slug: string): Promise<Cms.Category | undefined>;

  /**
   * Retrieves tags based on the provided options.
   * @param options - Options for filtering and pagination.
   * @returns A promise that resolves to an array of tags.
   */
  abstract getTags(options?: Cms.GetTagsOptions): Promise<Cms.Tag[]>;

  /**
   * Retrieves a tag by its slug.
   * @param slug - The slug of the tag.
   * @returns A promise that resolves to the tag, or undefined if not found.
   */
  abstract getTagBySlug(slug: string): Promise<Cms.Tag | undefined>;
}
```

For a detailed view of the CMS interface, please refer to the API at `packages/cms/core/src/cms-client.ts`.

For example, let' assume you have an HTTP API to a private repository you can access at `https://my-cms-api.com`. You can create a CMS client that interacts with this API as follows:

```tsx
import { CmsClient } from '@kit/cms';

export class MyCmsClient implements CmsClient {
  async getContentItems(options) {
    const response = await fetch('https://my-cms-api.com/content', {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
      },
      body: JSON.stringify(options),
    });

    const { total, items } = await response.json();

    return { total, items };
  }

  async getContentItemBySlug({ slug, collection }) {
    const response = await fetch(
      `https://my-cms-api.com/content/${collection}/${slug}`,
    );

    if (response.status === 404) {
      return undefined;
    }

    return response.json();
  }

  async getCategories(options) {
    const response = await fetch('https://my-cms-api.com/categories', {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
      },
      body: JSON.stringify(options),
    });

    return response.json();
  }

  async getCategoryBySlug(slug) {
    const response = await fetch(`https://my-cms-api.com/categories/${slug}`);

    if (response.status === 404) {
      return undefined;
    }

    return response.json();
  }

  async getTags(options) {
    const response = await fetch('https://my-cms-api.com/tags', {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
      },
      body: JSON.stringify(options),
    });

    return response.json();
  }

  async getTagBySlug(slug) {
    const response = await fetch(`https://my-cms-api.com/tags/${slug}`);

    if (response.status === 404) {
      return undefined;
    }

    return response.json();
  }
}
```

Of course, you can do the same using SDKs of your preferred CMS client, such as Payload CMS, Strapi, Sanity, and so on.


Learn how to create your own CMS client using the CMS API in Makerkit to fetch content from your CMS

Creating your own CMS client with the CMS API

Components


The Multi-Step Form Component is a powerful and flexible wrapper around React Hook Form, Zod, and Shadcn UI. It provides a simple API to create multi-step forms with ease, perfect for complex registration processes, surveys, or any scenario where you need to break down a long form into manageable steps.

## Features

- Easy integration with React Hook Form and Zod for form management and validation
- Built-in step management
- Customizable layout and styling
- Progress tracking with optional Stepper component
- TypeScript support for type-safe form schemas

## Usage

Here's a basic example of how to use the Multi-Step Form Component:

```tsx
import { MultiStepForm, MultiStepFormStep } from '@kit/ui/multi-step-form';
import { useForm } from 'react-hook-form';
import { zodResolver } from '@hookform/resolvers/zod';
import { z } from 'zod';

const FormSchema = createStepSchema({
  step1: z.object({ /* ... */ }),
  step2: z.object({ /* ... */ }),
});

export function MyForm() {
  const form = useForm({
    resolver: zodResolver(FormSchema),
    // ...
  });

  const onSubmit = (data) => {
    // Handle form submission
  };

  return (
    <MultiStepForm schema={FormSchema} form={form} onSubmit={onSubmit}>
      <MultiStepFormStep name="step1">
        {/* Step 1 fields */}
      </MultiStepFormStep>
      <MultiStepFormStep name="step2">
        {/* Step 2 fields */}
      </MultiStepFormStep>
    </MultiStepForm>
  );
}
```

## Key Components

### MultiStepForm

The main wrapper component that manages the form state and step progression.

Props:
- `schema`: Zod schema for form validation
- `form`: React Hook Form's `useForm` instance
- `onSubmit`: Function to handle form submission
- `className`: Optional CSS classes

### MultiStepFormStep

Represents an individual step in the form.

Props:
- `name`: Unique identifier for the step (should match a key in your schema)
- `children`: Step content

### MultiStepFormHeader

Optional component for adding a header to your form, often used with the Stepper component.

### MultiStepFormContextProvider

Provides access to form context within child components.

### useMultiStepFormContext

The hook returns an object with the following properties:

- `form: UseFormReturn<z.infer<Schema>>` - The original form object.
- `currentStep: string` - The name of the current step.
- `currentStepIndex: number` - The index of the current step (0-based).
- `totalSteps: number` - The total number of steps in the form.
- `isFirstStep: boolean` - Whether the current step is the first step.
- `isLastStep: boolean` - Whether the current step is the last step.
- `nextStep: (e: React.SyntheticEvent) => void` - Function to move to the next step.
- `prevStep: (e: React.SyntheticEvent) => void` - Function to move to the previous step.
- `goToStep: (index: number) => void` - Function to jump to a specific step by index.
- `direction: 'forward' | 'backward' | undefined` - The direction of the last step change.
- `isStepValid: () => boolean` - Function to check if the current step is valid.
- `isValid: boolean` - Whether the entire form is valid.
- `errors: FieldErrors<z.infer<Schema>>` - Form errors from React Hook Form.
- `mutation: UseMutationResult` - A mutation object for handling form submission.

## Example

Here's a more complete example of a multi-step form with three steps: Account, Profile, and Review. The form uses Zod for schema validation and React Hook Form for form management.

```tsx
'use client';

import { zodResolver } from '@hookform/resolvers/zod';
import { useForm } from 'react-hook-form';
import { z } from 'zod';

import { Button } from '@kit/ui/button';
import {
  Form,
  FormControl,
  FormField,
  FormItem,
  FormLabel,
  FormMessage,
} from '@kit/ui/form';
import { Input } from '@kit/ui/input';
import {
  MultiStepForm,
  MultiStepFormContextProvider,
  MultiStepFormHeader,
  MultiStepFormStep,
  createStepSchema,
  useMultiStepFormContext,
} from '@kit/ui/multi-step-form';
import { Stepper } from '@kit/ui/stepper';

const FormSchema = createStepSchema({
  account: z.object({
    username: z.string().min(3),
    email: z.string().email(),
  }),
  profile: z.object({
    password: z.string().min(8),
    age: z.coerce.number().min(18),
  }),
});

type FormValues = z.infer<typeof FormSchema>;

export function MultiStepFormDemo() {
  const form = useForm<FormValues>({
    resolver: zodResolver(FormSchema),
    defaultValues: {
      account: {
        username: '',
        email: '',
      },
      profile: {
        password: '',
      },
    },
    reValidateMode: 'onBlur',
    mode: 'onBlur',
  });

  const onSubmit = (data: FormValues) => {
    console.log('Form submitted:', data);
  };

  return (
    <MultiStepForm
      className={'space-y-10 p-8 rounded-xl border'}
      schema={FormSchema}
      form={form}
      onSubmit={onSubmit}
    >
      <MultiStepFormHeader
        className={'flex w-full flex-col justify-center space-y-6'}
      >
        <h2 className={'text-xl font-bold'}>Create your account</h2>

        <MultiStepFormContextProvider>
          {({ currentStepIndex }) => (
            <Stepper
              variant={'numbers'}
              steps={['Account', 'Profile', 'Review']}
              currentStep={currentStepIndex}
            />
          )}
        </MultiStepFormContextProvider>
      </MultiStepFormHeader>

      <MultiStepFormStep name="account">
        <AccountStep />
      </MultiStepFormStep>

      <MultiStepFormStep name="profile">
        <ProfileStep />
      </MultiStepFormStep>

      <MultiStepFormStep name="review">
        <ReviewStep />
      </MultiStepFormStep>
    </MultiStepForm>
  );
}

function AccountStep() {
  const { form, nextStep, isStepValid } = useMultiStepFormContext();

  return (
    <Form {...form}>
      <div className={'flex flex-col gap-4'}>
        <FormField
          name="account.username"
          render={({ field }) => (
            <FormItem>
              <FormLabel>Username</FormLabel>
              <FormControl>
                <Input {...field} />
              </FormControl>
              <FormMessage />
            </FormItem>
          )}
        />

        <FormField
          name="account.email"
          render={({ field }) => (
            <FormItem>
              <FormLabel>Email</FormLabel>
              <FormControl>
                <Input type="email" {...field} />
              </FormControl>
              <FormMessage />
            </FormItem>
          )}
        />

        <div className="flex justify-end">
          <Button onClick={nextStep} disabled={!isStepValid()}>
            Next
          </Button>
        </div>
      </div>
    </Form>
  );
}

function ProfileStep() {
  const { form, nextStep, prevStep } = useMultiStepFormContext();

  return (
    <Form {...form}>
      <div className={'flex flex-col gap-4'}>
        <FormField
          name="profile.password"
          render={({ field }) => (
            <FormItem>
              <FormLabel>Password</FormLabel>
              <FormControl>
                <Input type="password" {...field} />
              </FormControl>
              <FormMessage />
            </FormItem>
          )}
        />

        <FormField
          name="profile.age"
          render={({ field }) => (
            <FormItem>
              <FormLabel>Age</FormLabel>
              <FormControl>
                <Input type="number" {...field} />
              </FormControl>
              <FormMessage />
            </FormItem>
          )}
        />

        <div className="flex justify-end space-x-2">
          <Button type={'button'} variant={'outline'} onClick={prevStep}>
            Previous
          </Button>

          <Button onClick={nextStep}>Next</Button>
        </div>
      </div>
    </Form>
  );
}

function ReviewStep() {
  const { prevStep, form } = useMultiStepFormContext<typeof FormSchema>();
  const values = form.getValues();

  return (
    <div className={'flex flex-col space-y-4'}>
      <div className={'flex flex-col space-y-4'}>
        <div>Great! Please review the values.</div>

        <div className={'flex flex-col space-y-2 text-sm'}>
          <div>
            <span>Username</span>: <span>{values.account.username}</span>
          </div>
          <div>
            <span>Email</span>: <span>{values.account.email}</span>
          </div>
          <div>
            <span>Age</span>: <span>{values.profile.age}</span>
          </div>
        </div>
      </div>

      <div className="flex justify-end space-x-2">
        <Button type={'button'} variant={'outline'} onClick={prevStep}>
          Back
        </Button>

        <Button type={'submit'}>Create Account</Button>
      </div>
    </div>
  );
}
```

The inner components `AccountStep`, `ProfileStep`, and `ReviewStep` represent the individual steps of the form. They use the `useMultiStepFormContext` hook to access form utilities like `nextStep`, `prevStep`, and `isStepValid`.

These are built using ShadcnUI - so please [do refer to the ShadcnUI documentation](https://ui.shadcn.com/docs/components/form) for more information on how to use the components.

## Tips

1. Use the `createStepSchema` helper to easily create Zod schemas for your multi-step form.
2. Leverage the `useMultiStepFormContext` hook in your step components to access form utilities.
3. Combine with the Stepper component for visual progress indication.
4. Customize the look and feel using the provided `className` props and your own CSS.

The Multi-Step Form Component simplifies the creation of complex, multi-step forms while providing a great user experience. It's flexible enough to handle a wide variety of use cases while keeping your code clean and maintainable.




Building multi-step forms in the Next.js Supabase SaaS kit

Multi Step Forms in the Next.js Supabase SaaS kit


The Stepper component is a versatile UI element designed to display a series of steps in a process or form. It provides visual feedback on the current step and supports different visual styles.

## Usage

```jsx
import { Stepper } from '@kit/ui/stepper';

function MyComponent() {
  return (
    <Stepper
      steps={['Step 1', 'Step 2', 'Step 3']}
      currentStep={1}
      variant="default"
    />
  );
}
```

## Props

The Stepper component accepts the following props:

- `steps: string[]` (required): An array of strings representing the labels for each step.
- `currentStep: number` (required): The index of the currently active step (0-based).
- `variant?: 'numbers' | 'default'` (optional): The visual style of the stepper. Defaults to 'default'.

## Variants

The Stepper component supports two visual variants:

1. `default`: Displays steps as a horizontal line with labels underneath.
2. `numbers`: Displays steps as numbered circles with labels between them.

## Features

- Responsive design that adapts to different screen sizes
- Dark mode support
- Customizable appearance through CSS classes and variants
- Accessibility support with proper ARIA attributes

## Component Breakdown

### Main Stepper Component

The main `Stepper` function renders the overall structure of the component. It:

- Handles prop validation and default values
- Renders nothing if there are fewer than two steps
- Uses a callback to render individual steps
- Applies different CSS classes based on the chosen variant

### Steps Rendering

Steps are rendered using a combination of divs and spans, with different styling applied based on:

- Whether the step is currently selected
- The chosen variant (default or numbers)

### StepDivider Component

For the 'numbers' variant, a `StepDivider` component is used to render the labels between numbered steps. It includes:

- Styling for selected and non-selected states
- A divider line between steps (except for the last step)

## Styling

The component uses a combination of:

- Tailwind CSS classes for basic styling
- `cva` (Class Variance Authority) for managing variant-based styling
- `classNames` function for conditional class application

## Accessibility

- The component uses `aria-selected` to indicate the current step
- Labels are associated with their respective steps for screen readers

## Customization

You can further customize the appearance of the Stepper by:

1. Modifying the `classNameBuilder` function to add or change CSS classes
2. Adjusting the Tailwind CSS classes in the component JSX
3. Creating new variants in the `cva` configuration

## Example

```jsx
<Stepper
  steps={['Account', 'Personal Info', 'Review']}
  currentStep={1}
  variant="numbers"
/>
```

This will render a numbered stepper with three steps, where "Personal Info" is the current (selected) step.

The Stepper component provides a flexible and visually appealing way to guide users through multi-step processes in your application. Its support for different variants and easy customization makes it adaptable to various design requirements.

Learn how to use the Stepper component in the Next.js Supabase SaaS kit

Installation

Configuration

Communicating with the Server

API

Customization

Development

Billing

Content

Components

Notifications

Translations

Emails

Monitoring

Super Admin

Analytics

Plugins

Going to Production

Recipes

Troubleshooting

Layout Style

Learn how to update the default layout style of your Makerkit application

Subscribe to our Newsletter