Tutorials

Full walkthrough to building an application with Makerkit

Building a tasks application with Makerkit

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

Getting Started


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

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

MakerKit is ideal for any SaaS application or dynamic websites such as walled Online Publications.

It particularly shines when you wish to provide uniform navigation between your marketing site, documentation, and application.

## What does the boilerplate provide?

### Tech Stack

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

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

### Template Features

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

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

### Marketing

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

- **Newsletter Sign-up form** for *ConvertKit*, but easy to adapt to more
providers
- **Google Analytics** script baked-in
- **Email Templates** you can write with React

### Debugging and Testing

Never waste time chasing bugs again.

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

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

### After you buy

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

- **Resources, examples, and guides** for building a SaaS using *MakerKit*
- Access to the team for feedback, requests, and general support. **We're here to support you build your SaaS**.

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

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


Introduction to MakerKit: a SaaS starter built with Remix and Supabase

Introduction to MakerKit: a SaaS boilerplate for Remix and Supabase


MakerKit is built primarily with Remix, Supabase, and Tailwind CSS.

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

### 1) A Scalable Remix Application
The codebase is entirely built with [Remix](https://remix.run).

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

### 2) Built on top of Supabase

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

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

This kit **does not use Prisma**. We will release a Prisma version in the future.

### 3) Theme built with Tailwind 3

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

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

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

### 4) Radix UI UI Components

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

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

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

### 5) Fully and Strictly Typed with Typescript

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

### 6) Payload validation with Zod

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

### 7) E2E testing with Cypress

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

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

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

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

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

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

### 9) Multi-language by default with remix-i18n

We configured the application to be translated by default thanks to the
`remix-i18n` package.

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

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

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

### 10) Logging with Pino

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

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

### 11) React Query

MakerKit uses Tanstack's React Query to coordinate data fetching and caching.


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

The technologies that make up a MakerKit application


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

### Requirements

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

- Node.js
- Git
- Docker

### Cloning the repository

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

```
git clone --depth=1 git@github.com:makerkit/remix-supabase-saas-kit.git my-saas
```

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

### Initializing Git

Now, run the following commands for:

1. Moving into the folder
2. Reinitialize your git repository
3. Adding the original Makerkit repository as "upstream" so we can fetch updates from the main repository:

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

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

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

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

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

### Installing the Node dependencies

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

```
npm i
```

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

So let's jump on to the next step!


Learn how to clone the MakerKit repository

Clone the MakerKit SaaS boilerplate repository


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

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

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

### Running the Supabase Environment

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

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

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

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

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

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

```bash
> supabase start

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

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

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

```
SUPABASE_ANON_KEY=****************************************************
SUPABASE_SERVICE_ROLE_KEY=****************************************************
```

### Running the Remix Server

And now, the Remix server:

```bash
npm run dev
```

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

### Running the Stripe CLI

Run the Stripe CLI with the following command:

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

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

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

```bash filename=.env.development
STRIPE_WEBHOOKS_KEY=<PASTE_KEY_HERE>
```



Learn how to run a Remix and Supabase MakerKit application

How to run a Remix and Supabase MakerKit application

Configuration


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

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

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

The configuration has the following structure:

```typescript filename=configuration.ts
export default {
  site: {
    title: '',
    description: '',
    themeColor: '',
    siteUrl: '',
    siteName: '',
    twitterHandle: '',
    language: 'en',
  },
  paths: {
    signIn: '/auth/sign-in',
    signUp: '/auth/sign-up',
    emailLinkSignIn: '/auth/link',
    onboarding: `/onboarding`,
    appHome: '/tasks',
    settings: {
      profile: '/settings/profile',
      authentication: '/settings/profile/authentication',
      email: '/settings/profile/email',
      password: '/settings/profile/password',
    },
    api: {
      checkout: `/api/stripe/checkout`,
      billingPortal: `/api/stripe/portal`,
    },
    searchIndex: `/public/search-index`,
  },
  auth: {
    requireEmailConfirmation: false,
    // NB: Enable the providers below in the Firebase Console
    // in your production project
    providers: {
      emailPassword: true,
      phoneNumber: false,
      emailLink: false,
      oAuth: [GoogleAuthProvider],
    },
  },
  appCheckSiteKey: process.env.APPCHECK_KEY,
  navigation: {
    style: NavigationStyle.TopHeader,
  },
  email: {
    host: '',
    port: 0,
    user: '',
    password: '',
  },
  emailEtherealTestAccount: {
    email: process.env.ETHEREAL_EMAIL,
    password: process.env.ETHEREAL_PASSWORD,
  },
  environment: process.env.VERCEL_ENV ?? 'development',
  emulatorHost: process.env.EMULATOR_HOST,
  emulator: process.env.EMULATOR === 'true',
  production: process.env.NODE_ENV === 'production',
  stripe: {
    products: [
      {
        name: 'Basic',
        description: 'Describe your basic plan',
        plans: [
          {
            price: '$249/year',
            stripePriceId: '<STRIPE_PRICE_ID>',
          }
        ],
      },
      {
        name: 'Pro',
        description: 'Describe your pro plan',
        plans: [
          {
            price: '$249/year',
            stripePriceId: '<STRIPE_PRICE_ID>',
          }
        ],
      },
    ],
  },
};
```

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

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

## Environment Variables

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

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

### Development Environment Variables

The development environment variables set your application up for the Firebase Emulators:

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

# SUPABASE
SUPABASE_URL=http://localhost:54321
SUPABASE_ANON_KEY=
SUPABASE_SERVICE_ROLE_KEY=

# STRIPE
STRIPE_WEBHOOK_SECRET=
STRIPE_SECRET_KEY=

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

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

```

### Production Environment Variables

<Alert type='warn'>
  When you go to production, ensure you add the required environment variables using your CI or service provider. 
</Alert>

Remix does not bundle your `.env` variables when building your application in production mode, so you need to ensure you are providing these variables.


Learn how to define the global configuration of a MakerKit application with Remix and Supabase

Define the global configuration of your MakerKit SaaS application with Remix and Supabase

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

Architecture


MakerKit's primary goals are:

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

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

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

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

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

### Framework Architecture

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

```
- app
  - routes
    - __site
    - __app
    - __auth
  - lib
  - components
```

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

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

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

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

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

### Lib and Components

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

- `lib`: here is where we write most domain-related business logic (hooks, contexts, queries, mutations, etc.)
- `components`: here is where we write the domain-related components (ex. Profile Page, Create Project form, etc.)

MakerKit comes with some business logic (it would be nearly impossible otherwise to build a genuinely functioning SaaS). You should customize the existing business logic for your application, and it is likely where you will add most of your code.

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

### Routes

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

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

The kit splits the routes into three separate layouts:
- `__site`: the routes that are accessible to everyone, even if they are not logged in
- `__app`: the routes that are accessible only to logged-in users
- `__auth`: the routes that are accessible only to logged-in users, but only if they are not already logged in

## Import Flow

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

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



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

Architecture and Folder Structure for your Remix SaaS application


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

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

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

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

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

```txt filename=Structure
- app
  - components
    - events
      - EventsContainerComponent.tsx
      - ...

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

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

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

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

#### Types

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

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

#### Custom Hooks

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

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

```tsx filename=src/lib/events/hooks/use-fetch-events.ts
import EventModel from '~/lib/events/types/event-model.ts'

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

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

    if (error) {
      throw error;
    }

    return data;
  })
}
```

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

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

### 2) Components

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

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

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

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

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

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

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

export default EventsListContainer;
```

### 3) Routes

Finally, we can add the events component `EventsListContainer` to a page. To do so, let's create a page component at `routes/__app/events/index.tsx`:

```tsx filename=routes/__app/events/index.tsx
import EventsListContainer from '~/components/EventsListContainer';

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

export default EventsPage;
```

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

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

Structure your Makerkit Application


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

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

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

## Users

Users are, of course, foundational to any application.

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

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

Below is the `users` table:

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

## Organizations

`Organizations` are groups of users.

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

Below is what the `Organizations` schema looks like:

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

## Memberships

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

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

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

Below is what the `Organizations` schema looks like:

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

### Invites

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

### User Roles

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

This enum is hierarchical and associated with a number:

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

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

## Subscriptions

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

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

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

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

```sql
create table organizations_subscriptions (
  organization_id bigint not null references public.organizations (id) on delete cascade,
  subscription_id text unique references public.subscriptions (id) on delete set null,
  customer_id text not null unique,
  primary key (organization_id)
);
```

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

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


## Storage

By default, the kit also creates two Storage buckets: `logos` and `avatars`:

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

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

Learn how MakerKit defines the model of your SaaS application with Remix and Supabase

The MakerKit Data Model for your SaaS project built with Remix and Supabase

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

Authentication


MakerKit uses Supabase to manage authentication within your application.

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

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

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

## Configuration

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

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

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

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

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

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

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

## Requiring Email Verification

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

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

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

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

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

Setting up Supabase and Remix authentication with MakerKit

Learn the MakerKit best practices for building and shipping your app

Data Fetching


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

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

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

```ts
export const TASKS_TABLE = `tasks`;
```

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

```ts
export function createTask(
  client: Client,
  task: Task,
) {
  return client.from(TASKS_TABLE).insert(task).throwOnError();
}
````

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

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

```tsx filename=lib/tasks/hooks/use-create-task.ts
function useCreateTaskMutation(task: Task) {
  const client = useSupabase();

  return useMutation(
    async (task: Task) => {
      return createTask(client, task);
    }
  );
}

export default useCreateTaskMutation;
```

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

```tsx filename=components/tasks/CreateTaskForm.tsx
import { useNavigate } from '@remix-run/react';
import type { FormEventHandler } from 'react';
import { useCallback } from 'react';
import toaster from 'react-hot-toast';

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

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

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

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

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

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

        return;
      }

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

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

      // redirect to /tasks
      return navigate(`/tasks`);
    },
    [navigate, createTaskMutation, organizationId]
  );

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

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

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

export default CreateTaskForm;

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

  return date.toDateString();
}
```


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

Writing data to Database


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

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

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

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

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

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

Now, if we want to use a React Hook to fetch the organization from one of
our components, we can use the `useQuery` hook from `react-query`:

```tsx
import useSupabase from '~/core/hooks/use-supabase';
import { getOrganizationById } from '~/lib/organizations/database/queries';
import { useQuery } from '@tanstack/react-query';

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

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

export default useOrganizationQuery;
```

### Retrieving data using a React hook

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

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

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

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

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

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

### Retrieving data from the server

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

```tsx
import {
  throwInternalServerErrorException,
} from '~/core/http-exceptions';

import { json } from '@remix-run/node';
import getSupabaseServerClient from '~/core/supabase/server-client';
import { parseOrganizationIdCookie } from '~/lib/server/cookies/organization.cookie';

export async function loader({ request }: LoaderArgs) {
  const client = getServerSupabaseClient(request);
  const organizationId = Number(await parseOrganizationIdCookie(request));

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

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

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

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

Learn how fetch data from your Supabase database in Makerkit

Fetching data from Supabase


<Alert type={'info'}>
  Coming soon
</Alert>

Learn how to make requests to your Remix API in Makerkit

API requests


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

## Uploading a file

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

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

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

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

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

  throw result.error;
}
```

You can also combine the above with `useMutation` from `react-query` when you use the code above from a React component:

```ts
export function useUploadUserProfilePhotoMutation() {
  const client = useSupabase();

  return useMutation(async (file: File, userId: string) => {
    return uploadUserProfilePhoto(client, file, userId);
  });
}
```

And then, you can use it like this:

```tsx
const updateProfilePhoto = useUploadUserProfilePhotoMutation();

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

Uploading data to Storage

Development


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

### Run the development server

Run the command:

```
npm run dev
```

### Build a production bundle

Run the command:

```
npm build
```

### Start a production server

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

```
npm start
```

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

### Format all the files

Run the command:

```
npm run format
```

### Type checking

Run the command:

```
npm run typecheck
```

### Linting

Run the command:

```
npm run lint
```

### Start the Supabase Local Environment

Run the command:

```
npm run supabase:start
```

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

### Stopping the Supabase Local Environment

Run the command:

```
npm run supabase:stop
```

### Reset the Supabase Local Environment Database

Run the command:

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

### Running the Supabase Database Tests

Run the command:

```
npm run test:db
```

### Running and resetting the Supabase Database Tests

Run the command:

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

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

Run the command:

```
npm run cypress
```

### Run Cypress for E2E Tests (Headless)

Run the command:

```
npm run cypress:headless
```

### Run E2E Tests and Exit

Run the command:

```
npm test:e2e
```

### Run the Local Stripe Webhooks Server

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

Run the command:

```
npm run stripe:listen
```

### Run the Mock Stripe Server

Run the command:

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

### Kill Ports

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

Run the command:

```
npm run killports
```


All the commands to use for your Makerkit app


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

The default settings look like the below:

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

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

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

```
npm run format
```


Adjust the codebase style according to your preferences


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

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

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

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

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

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

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

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

### Adding new languages

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

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

The configuration will look like the below:

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

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

#### Setting the default Locale

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

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

```txt filename=.env
DEFAULT_LOCALE=de
```


Adding and updating locales in your Makerkit application


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

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

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

## Email Configuration

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

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

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

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

## Sending Emails

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

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

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

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

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

## Using MJML to render emails

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

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

Makerkit provides two MJML emails:

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

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

#### Using MJML with React

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

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

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

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

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

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

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

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

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

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

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

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

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

## Testing Emails

By default, when running the Firebase Emulators, Makerkit will use [Ethereal](https://ethereal.mail) as an email transport provider. This service allows us to test our emails for free.

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

```
ETHEREAL_EMAIL=
ETHEREAL_PASSWORD=
```

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


Sending emails with a Makerkit application


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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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


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

Validating the Remix API inputs with Zod and Typescript


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

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

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

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

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

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

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

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

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

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

  try {
    await writeToFirestore(data);

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

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

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

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

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

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


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

Logging


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

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

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

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

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

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

  return headers;
}
```

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

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

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

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

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

export const action: ActionFunction = async ({}) => {
  withCors();
  // your logic
}

export default apiHandler;
```


Enable CORS


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

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

MakerKit provides some utilities to encrypt and decrypt your data. 

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

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

  return storeKeyInFirestore(encryptedKey);
}

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

  return decrypt(encryptedKey);
}
```


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

Encrypting Secrets


The MakerKit Starter has three default roles:

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

export default MembershipRole;
```

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

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

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

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

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

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

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

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

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

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

Extend User Roles

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

Payments


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

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

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

## Configuration

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

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

- `STRIPE_SECRET_KEY`
- `STRIPE_WEBHOOK_SECRET`

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

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

## Creating your SaaS plans in Stripe

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

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

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

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

### Pricing Table Configuration

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

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

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

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

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

### Additional Configuration

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

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

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

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

### Install The Stripe CLI

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

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

### Connect CLI with your account

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

```
npm run stripe:listen
```

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

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

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

Restart the next.js server to apply the changes.

## Billing Portal

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

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

### Enabling the Billing Portal in test mode

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

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

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

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


Learn how to configure Stripe with your MakerKit application

Set up Stripe Payments for Remix and Firebase SaaS applications


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

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

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

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

This route is responsible for:

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

## Validating Stripe's Webhooks

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

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

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

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

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

## Handling Stripe's Webhooks

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

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

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

As described above, we handle 5 events:

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

### Checkout Completed

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

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

The subscription's object has the following interface:

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

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

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

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

This interface is added to the `Organization` object.

### Subscription Updated

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

### Subscription Deleted

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

## Adding additional webhooks

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

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

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

## Adding additional data to the subscription object

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

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

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

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

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

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

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

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

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

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

  return row as SubscriptionRow;
}
```

Learn how MakerKit handles Stripe Webhooks in your application

How Makerkit handles Stripe Webhooks


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

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

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

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

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

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

// some code here...

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

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

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

// some code here...

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

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

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

## Handling the Payment Method dynamically

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

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

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

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

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

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

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

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

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

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

// some code here...

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

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


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

Enabling One-Time Payments with Stripe

Learn about Makerkit's Organizations' model and members invites

Organizations


The Makerkit boilerplate's data model is modeled around *Organizations*. 

Organizations are groups of users, which can also be named Projects, Teams, and so on: it really depends on your application's domain.

The data model of an organization looks like the following:

```tsx filename=organization.ts
type UserId = string;

interface Organization {
  name: string;
  timezone?: string;
  logoURL?: string | null;
  subscription?: OrganizationSubscription;
  customerId?: string;

  members: Record<UserId, {
    role: number;
    user: Reference;
  }>;
}
```

### Renaming "Organizations" to another entity

Makerkit uses "organizations" to refer to a group of users. However, the name "organizations" may not make sense to your application's domain, even with a similar technical data model. 

For example, you may want to call them "Teams", or "Workspaces". In this case, we suggest you keep using "organization" as a technical concept (otherwise, you'd have to rename every instance) within the codebase while changing the labels in the UI using the i18n files at `public/locales`. 

To do so, simply rename all "Organization" instances according to your preferred choice.

MakerKit's Organizations


There are many ways you can extend the organization's data model in your applications: you will use this entity for the objects that are shared among the group's users.

For example, here is a popular scenario: we assume users can install integrations for their organizations. Integrations can have the following interface:

```tsx filename=integration.ts
enum IntegrationType {
  Zapier,
  Notion,
  // etc
}

interface Integration<IntegrationData = unknown> {
  type: IntegrationType;
  data: IntegrationData;
}
```

Then, you can extend the organization's interface and add an `integrations` property to `Organization`, and initialize it as an empty array `[]` when you create a new integration:

```tsx filename=organization.ts
interface Organization {
  // ...
  integrations: Integration[];
}
```

Extending Organizations


Most permissions are written in a single file at `src/lib/organizations/permissions.ts`.

Here, you can find some of the examples used in the boilerplate so that you can start writing your own.

Why are permissions written in a single file? Because it's easy to write inline logic and lose track of it. Therefore, we will write all the business logic within the same file and encapsulated as simple functions.

Let's take a look at a simple permission function in the boilerplate:

```tsx filename=src/lib/organizations/permissions.ts
/**
 *
 * @param currentUserRole The current logged-in user
 * @param targetUser The role of the target of the action
 * @description Checks if a user can perform actions (such as update a role) of another user
 * @name canUpdateUser
 */
export function canUpdateUser(
  currentUserRole: MembershipRole,
  targetUser: MembershipRole
) {
  return currentUserRole > targetUser;
}
```

The function takes two parameters: the current user's role and the target user's role, and checks if the current user can update the target user's role (or anything).

Now, we can use the function above with the `IfHasPermissions` component to display or hide some parts of the application. This component automatically injects the current user's role, such as below:

```tsx
<IfHasPermissions
  condition={(currentUserRole) =>
    canInviteUser(currentUserRole, targetUserRole)
  }
>
  <InviteUserComponent />
</IfHasPermissions>
```

The `InviteUserComponent` component will be displayed if the condition is truthy.

Otherwise, you can use these functions throughout the application on both the client and the server.


Learn how to write a simple permissions system based on the users' role in your Makerkit applications

Managing User Permissions


Makerkit provides some utilities to retrieve the current organization's
subscription: you can use these utilities to allow or gate access to
specific features, pages, or to perform certain actions.

1. On the client side, we can use the hook `useIsSubscriptionActive`
2. On the server-side, we can use the functions
`isOrganizationSubscriptionActive` and `getOrganizationSubscription`

## Client Side Gating

Let's assume we want to allow only users who belong to paying organizations to
perform a certain action:

```tsx filename=src/lib/organizations/permissions.ts
function isAdmin(
  role: MembershipRole
) {
  return role === MembershipRole.Admin;
}
```

Now, combine this function with other conditions:

```tsx filename=src/lib/organizations/permissions.ts
export function useCreateNewThing(
  userRole: MembershipRole,
) {
  const isPayingUser = useIsSubscriptionActive();

  return isPayingUser && isAdmin(userRole);
}
```

As you may know, I recommend adding all the permissions logic to the file
`permissions.ts` (or similar files), and never inline it: this makes it easy to
store logic in one single place rather than scattered across the
application.

Inlining logic in our code will make it hard to track logic
down and debugging it.

Once defined out logic functions in `permissions.ts`, we can then use these
in our components to hide the sections that users do
not have access to:

```tsx
function Feature() {
  const userRole = useCurrentUserRole();
  const canCreateThing = useCreateNewThing(userRole);

  if (!canCreateThing) {
    return <div>Sorry, you do not have access to this feature. Subscribe?</div>
  }

  return <FeatureContainer />;
}
```

### Firestore Rules

Another essential thing to take into account is securing our Firestore
rules using the organization's subscription.

For example, let's assume your application requires organizations to be
paying customers to write to a certain collection:

```js
function getOrganizationSubscription() {
  let organization = getOrganization(organizationId);

  return organization.subscription;
}

function isPayingOrganization(subscription) {
  return subscription != null && subscription.status === 'paid';
}

function isProPlan(subscription) {
  let organization = getOrganization(organizationId);

  return subscription.stripePriceId == 'pro-plan-id';
}

function canWriteToCollection(organizationId) {
  let subscription = getOrganizationSubscription();

  return isPayingOrganization(subscription) && isProPlan(subscription);
}

match /organizations/{organizationId} {
  match /tasks/{task} {
    allow create: canWriteToCollection(organizationId);
    allow list: if userIsMemberByOrganizationId(organizationId);
  }
}
```

## Server Side Gating

When gating access on the server side, we can use two utilities that allow
us to get the organization's subscription by its ID.

### Using Firestore utilities

When you need to check the user's subscription in your API functions, you can
use the functions `isOrganizationSubscriptionActive` and
`getOrganizationSubscription` exported from
`src/lib/server/organizations/memberships.ts`.

For example, let's assume we have an API handler that performs an action:

```tsx
export default async function action({ request }) {
  const organization = await parseOrganizationCookie(request);

  const isSubscriptionActive =
    await isOrganizationSubscriptionActive(organization);

  if (!isSubscriptionActive) {
    return throwForbiddenError();
  }

  // all good! perform action
}
```


Learn how to gate access to certain features or pagess based on the organization's subscription

Subscription Permissions

Learn about the various utilities that come with Makerkit

Utilities


Makerkit uses various React Hooks for very common tasks, such as a simple
reducer for asynchronous tasks, or for executing HTTP requests.

## useRequestState

You can use this hook as a simple reducer for asynchronous tasks, like HTTP
requests or asynchronous operations with Firestore.

To create the hook, you can use the following snippet:

```tsx
const { state, setError, setData, setLoading } =
    useRequestState<Data>();
```

This hooks returns the current state `state` and the methods to update it.
The `state` variable has the following interface:

```tsx
type State<Data, ErrorType> =
  | {
      data: Data;
      loading: false;
      success: true;
      error: Maybe<ErrorType>;
    }
  | {
      data: undefined;
      loading: true;
      success: false;
      error: Maybe<ErrorType>;
    }
  | {
      data: undefined;
      loading: false;
      success: false;
      error: Maybe<ErrorType>;
    };
```

## useApiRequest

You can use this hook to perform HTTP requests from your UI to your API and
uses `useRequestState` under the hood for managing the state.

The function has the following interface:

```tsx
function useApiRequest<Resp = unknown, Body = void>(
  path: string,
  method: HttpMethod = 'POST'
)
```

For example, if we wanted to make an API request to an endpoint, we could do
the following:

```tsx
function SignIn() {
  const [signIn, signInState] = useApiRequest(`/api/sign-in`);

  useEffect(() => {
    if (signInState.success) {
      window.location.href = '/dashboard';
    }
  }, [signInState]);

  if (signInState.loading) {
    return <span>Loading...</span>
  }

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


Reusable React Hooks utilities for common tasks

Reusable React Hooks

Learn how to run and update the Cypress E2E tests

Testing


The Makerkit SaaS boilerplate comes with a set of predefined tests with the following goals:

1. Verify that the boilerplate application works well
2. Provide instructions for building your own tests

As your application grows, the tests will inevitably need to be updated and
maintained. We hope that our tests will be simple to understand and to
change when you will need them.

## Running the Remix development server

First, we have to run the following command to run Remix with a testing
environment (i.e. using `.env.test`):

```
npm run dev
```

This command will start a Remix dev server at http://localhost:3000, so
it's important to make sure you have no other Remix server running at the
same port.

Additionally, we have to start the **Supabase local instance**:

```
npm run supabase:start
```

## Running Cypress in development mode

While you build your tests, it can be handy to use a windowed version of the
Cypress testing suite, so that you can easily retry the tests without having
to re-run the while tests suite.

To do that, run the following command:

```
npm run cypress
```

## Running All Cypress tests

Whenever you want to run all your tests at once, you can use the following commands:

```
npm run cypress:headless
```

This will run all the tests and exit.

## Running Cypress in CI mode

Whenever you want to run all your tests in a CI
environment, you can use the following commands:

```
npm test
```

The command above will:

1. Start the Supabase local instance
2. Start the Remix environment
3. Run the tests in headless mode
4. Exit and close all the processes

As you may have noticed, this is the command to run in your CI environment.

## Testing Stripe

Testing Stripe requires one more process to start, i.e. the official Stripe
emulator.

The command below **will require Docker installed**, which is why you can
choose to disable it by setting the environment variable `ENABLE_STRIPE_TESTING`
to `false` from the `.env.test` environment file:

```bash filename=.env.test
ENABLE_STRIPE_TESTING=false
```

If instead, you want to test Stripe Checkout as well, run the command below:

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

As we've mentioned, this will require Docker running. Of course, we think
it's worth it.


Learn how to run Cypress E2E tests for your Makerkit application

Running Cypress Tests with Supabase and Remix


To run your tests in any CI, we recommend you simply run the following command:

```
npm test
```

This command takes care of running all the required services, importing the test data, executing the tests and then exiting.

### The Makerkit testing pipeline

As mentioned in the previous section, testing a Makerkit requires a few services to be up and running:

- the Remix server
- the Firebase emulators
- optionally, the Stripe Mock server

While executing these tests in your CI, this can get cumbersome. Therefore, we provided a single script to execute all your tests in one simple command: you can find the script at `scripts/test.sh`, which will contain the following content:

```
set -e

npm run dev:test & npm run stripe:mock-server &
npm run cypress:headless
sh scripts/kill-ports.sh
```

Let's explain it, so you can add your own modifications to it.

The first command will run (in parallel and in the background) the Remix server and the Stripe mock server:

```
npm run dev:test & npm run stripe:mock-server &
```

Afterward, we execute the Cypress tests in headless mode:

```
npm run cypress:headless
```

Finally, we clean up all the ports that may have remained open after executing the script:

```
sh scripts/kill-ports.sh
```

If you update your ports, remember to change them also in `scripts/kill-ports.sh`.

### Running the Tests in CI mode

Finally, the tests can be executed with the command `npm test`.

This command **will automatically run the Firebase emulators** and the `test.sh` script, and is defined as:

```
"test": "firebase emulators:exec --project demo-makerkit --import ./firebase-seed \"sh ./scripts/test.sh\"",
```

When finished, the emulators will exit.


Learn how to test your Makerkit in your CI

CI Tests

Learn how to prepare your application for shipping to production

Going to Production


Before going to production, it's essential to follow certain precautions to avoid failures.

## 1) Environment Variables

First, we must safely inject the correct environment variables into their
relative environment. MakerKit has predefined templates that allow you to understand where each variable should be added.

Before publishing your SaaS, or if you are making a production release after
a change and this included an environment variable; ensure your CI provider is
up to date with the correct variable in the right environments.

Since the `.env` file will not be committed to your repository, you will
need to add the environment variables beforehand.

## 2) Supabase Postgres Row Level Security (RLS) Policies

If you are using Supabase, you will need to ensure that your RLS policies
are set up correctly, and that the changes are propagated to the production
database.

## 3) Enable your Stripe account Billing Status

Remember to complete your Stripe account's information and enable billing
(of course, also replacing the correct environment variables) and not to
forget it in `Testing Mode`.

## 4) Enable Google Analytics (Optional)

Understand how visitors find your website early on.

## 5) Enable Sentry (Optional)

With 4000 events for free per month, we recommend that you use [Sentry.io](https://sentry.io) for
ensuring you can catch, analyze and fix any runtime errors in your application that your users will encounter.


Checklist to ship a MakerKit application to Production


If you want to deploy your Remix app to Vercel, you can do so by following these steps.

### 1) Install the Remix Vercel package

```bash
npm i -D @remix-run/vercel
```

### 2) Add a `server.js` file in the root of your project

Then, add the following file to the root of your project:


```js filename=server.js
import { createRequestHandler } from '@remix-run/vercel';
import * as build from '@remix-run/dev/server-build';

export default createRequestHandler({ build, mode: process.env.NODE_ENV });
```

### 3) Update the Remix configuration

Finally, update your `remix.config.js` file to include the following:

```js filename=remix.config.js
/**
 * @type {import('@remix-run/dev').AppConfig}
 */
module.exports = {
  serverBuildTarget: 'vercel',
  server: ['test', 'development'].includes(process.env.NODE_ENV)
    ? undefined
    : './server.js',
  cacheDirectory: './node_modules/.cache/remix',
  ignoredRouteFiles: ['**/.*', '**/*.css', '**/*.test.{js,jsx,ts,tsx}'],
  future: {},
};
```

 🎉 Et voilà! You should now be able to deploy your Remix app to Vercel.


Learn how to deploy your Remix app to Vercel

Deploying Remix to Vercel

/*@jsxRuntime automatic @jsxImportSource react*/
const {Fragment: _Fragment, jsx: _jsx, jsxs: _jsxs} = arguments[0];
function _createMdxContent(props) {
  const _components = Object.assign({
    p: "p",
    h3: "h3",
    a: "a",
    span: "span",
    pre: "pre",
    code: "code"
  }, props.components);
  return _jsxs(_Fragment, {
    children: [_jsx(_components.p, {
      children: "If you want to deploy your Remix app to Vercel, you can do so by following these steps."
    }), "\n", _jsxs(_components.h3, {
      id: "1-install-the-remix-vercel-package",
      children: [_jsx(_components.a, {
        "aria-hidden": "true",
        tabIndex: "-1",
        href: "#1-install-the-remix-vercel-package",
        children: _jsx(_components.span, {
          className: "icon icon-link"
        })
      }), "1) Install the Remix Vercel package"]
    }), "\n", _jsx(_components.pre, {
      children: _jsx(_components.code, {
        className: "hljs language-bash",
        children: "npm i -D @remix-run/vercel\n"
      })
    }), "\n", _jsxs(_components.h3, {
      id: "2-add-a-serverjs-file-in-the-root-of-your-project",
      children: [_jsx(_components.a, {
        "aria-hidden": "true",
        tabIndex: "-1",
        href: "#2-add-a-serverjs-file-in-the-root-of-your-project",
        children: _jsx(_components.span, {
          className: "icon icon-link"
        })
      }), "2) Add a ", _jsx(_components.code, {
        children: "server.js"
      }), " file in the root of your project"]
    }), "\n", _jsx(_components.p, {
      children: "Then, add the following file to the root of your project:"
    }), "\n", _jsx(_components.pre, {
      filename: "server.js",
      children: _jsxs(_components.code, {
        className: "hljs language-js",
        children: [_jsx(_components.span, {
          className: "hljs-keyword",
          children: "import"
        }), " { createRequestHandler } ", _jsx(_components.span, {
          className: "hljs-keyword",
          children: "from"
        }), " ", _jsx(_components.span, {
          className: "hljs-string",
          children: "'@remix-run/vercel'"
        }), ";\n", _jsx(_components.span, {
          className: "hljs-keyword",
          children: "import"
        }), " * ", _jsx(_components.span, {
          className: "hljs-keyword",
          children: "as"
        }), " build ", _jsx(_components.span, {
          className: "hljs-keyword",
          children: "from"
        }), " ", _jsx(_components.span, {
          className: "hljs-string",
          children: "'@remix-run/dev/server-build'"
        }), ";\n\n", _jsx(_components.span, {
          className: "hljs-keyword",
          children: "export"
        }), " ", _jsx(_components.span, {
          className: "hljs-keyword",
          children: "default"
        }), " ", _jsx(_components.span, {
          className: "hljs-title hljs-function",
          children: "createRequestHandler"
        }), "({ build, ", _jsx(_components.span, {
          className: "hljs-attr",
          children: "mode"
        }), ": process.", _jsx(_components.span, {
          className: "hljs-property",
          children: "env"
        }), ".", _jsx(_components.span, {
          className: "hljs-property",
          children: "NODE_ENV"
        }), " });\n"]
      })
    }), "\n", _jsxs(_components.h3, {
      id: "3-update-the-remix-configuration",
      children: [_jsx(_components.a, {
        "aria-hidden": "true",
        tabIndex: "-1",
        href: "#3-update-the-remix-configuration",
        children: _jsx(_components.span, {
          className: "icon icon-link"
        })
      }), "3) Update the Remix configuration"]
    }), "\n", _jsxs(_components.p, {
      children: ["Finally, update your ", _jsx(_components.code, {
        children: "remix.config.js"
      }), " file to include the following:"]
    }), "\n", _jsx(_components.pre, {
      filename: "remix.config.js",
      children: _jsxs(_components.code, {
        className: "hljs language-js",
        children: [_jsxs(_components.span, {
          className: "hljs-comment",
          children: ["/**\n * ", _jsx(_components.span, {
            className: "hljs-doctag",
            children: "@type"
          }), " {", _jsx(_components.span, {
            className: "hljs-type",
            children: "import('@remix-run/dev').AppConfig"
          }), "}\n */"]
        }), "\n", _jsx(_components.span, {
          className: "hljs-variable hljs-language",
          children: "module"
        }), ".", _jsx(_components.span, {
          className: "hljs-property",
          children: "exports"
        }), " = {\n  ", _jsx(_components.span, {
          className: "hljs-attr",
          children: "serverBuildTarget"
        }), ": ", _jsx(_components.span, {
          className: "hljs-string",
          children: "'vercel'"
        }), ",\n  ", _jsx(_components.span, {
          className: "hljs-attr",
          children: "server"
        }), ": [", _jsx(_components.span, {
          className: "hljs-string",
          children: "'test'"
        }), ", ", _jsx(_components.span, {
          className: "hljs-string",
          children: "'development'"
        }), "].", _jsx(_components.span, {
          className: "hljs-title hljs-function",
          children: "includes"
        }), "(process.", _jsx(_components.span, {
          className: "hljs-property",
          children: "env"
        }), ".", _jsx(_components.span, {
          className: "hljs-property",
          children: "NODE_ENV"
        }), ")\n    ? ", _jsx(_components.span, {
          className: "hljs-literal",
          children: "undefined"
        }), "\n    : ", _jsx(_components.span, {
          className: "hljs-string",
          children: "'./server.js'"
        }), ",\n  ", _jsx(_components.span, {
          className: "hljs-attr",
          children: "cacheDirectory"
        }), ": ", _jsx(_components.span, {
          className: "hljs-string",
          children: "'./node_modules/.cache/remix'"
        }), ",\n  ", _jsx(_components.span, {
          className: "hljs-attr",
          children: "ignoredRouteFiles"
        }), ": [", _jsx(_components.span, {
          className: "hljs-string",
          children: "'**/.*'"
        }), ", ", _jsx(_components.span, {
          className: "hljs-string",
          children: "'**/*.css'"
        }), ", ", _jsx(_components.span, {
          className: "hljs-string",
          children: "'**/*.test.{js,jsx,ts,tsx}'"
        }), "],\n  ", _jsx(_components.span, {
          className: "hljs-attr",
          children: "future"
        }), ": {},\n};\n"]
      })
    }), "\n", _jsx(_components.p, {
      children: "🎉 Et voilà! You should now be able to deploy your Remix app to Vercel."
    })]
  });
}
function MDXContent(props = {}) {
  const {wrapper: MDXLayout} = props.components || ({});
  return MDXLayout ? _jsx(MDXLayout, Object.assign({}, props, {
    children: _jsx(_createMdxContent, props)
  })) : _createMdxContent(props);
}
return {
  default: MDXContent
};


2) Add a `server.js` file in the root of your project

Tutorials

Getting Started

Configuration

Architecture

Authentication

Data Fetching

Development

Payments

Organizations

Utilities

Testing

Going to Production

Deploying to Vercel

Learn how to deploy your Remix app to Vercel

1) Install the Remix Vercel package

2) Add a `server.js` file in the root of your project

3) Update the Remix configuration

Stay informed with our latest resources for building a SaaS

Table of Contents

Tutorials

Getting Started

Configuration

Architecture

Authentication

Data Fetching

Development

Payments

Organizations

Utilities

Testing

Going to Production

Deploying to Vercel

Learn how to deploy your Remix app to Vercel

1) Install the Remix Vercel package

2) Add a server.js file in the root of your project

3) Update the Remix configuration

Stay informed with our latest resources for building a SaaS

Table of Contents

2) Add a `server.js` file in the root of your project