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

How to


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

## What you will learn


1. Setting up your Makerkit Remix Supabase project
2. Authentication
3. Updating the marketing pages of your SaaS
4. Interacting with the Database
5. Updating the Marketing pages of your SaaS
6. Updating the Internal pages of your SaaS
7. Setting up Payments
8. Updating Translations
9. ... and a lot more.

This documentation is under development and will be updated regularly. If you have any questions, please contact me.

Here is a brief introduction to the How to section of the Makerkit Remix Supabase documentation.

Introduction to the How to section of the Makerkit Remix Supabase documentation


Makerkit stores your project configuration in a Typescript file named `configuration.ts`, in which we store **non-secret** data needed in the client-side bundles of your project.

## What is stored in the configuration file?

In this configuration file, we store data that is safe to be exposed in the client-side bundles of your project.

The configuration file contains the following data:

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

const env = getEnv() ?? {};
const production = env.NODE_ENV === 'production';

enum Themes {
  Light = 'light',
  Dark = 'dark',
}

const configuration = {
  site: {
    name: 'Awesomely - Your SaaS Title',
    description: 'Your SaaS Description',
    themeColor: '#ffffff',
    themeColorDark: '#0a0a0a',
    siteUrl: env.SITE_URL,
    siteName: 'Awesomely',
    twitterHandle: '',
    githubHandle: '',
    language: 'en',
    convertKitFormId: '',
    locale: env.DEFAULT_LOCALE,
  },
  auth: {
    // ensure this is the same as your Supabase project
    requireEmailConfirmation: true,
    // NB: Enable the providers below in the Supabase Console
    // in your production project
    providers: {
      emailPassword: true,
      phoneNumber: false,
      emailLink: false,
      oAuth: ['google'] as Provider[],
    },
  },
  production,
  environment: env.ENVIRONMENT,
  features: {
    enableThemeSwitcher: true,
  },
  theme: Themes.Light,
  paths: {
    signIn: '/auth/sign-in',
    signUp: '/auth/sign-up',
    signInMfa: '/auth/verify',
    signInFromLink: '/auth/link',
    callback: '/auth/callback',
    onboarding: `/onboarding`,
    appHome: '/dashboard',
    settings: {
      profile: '/settings/profile',
      authentication: '/settings/profile/authentication',
      email: '/settings/profile/email',
      password: '/settings/profile/password',
    },
    api: {
      checkout: `/resources/ls/checkout`,
      customerPortal: `/resources/ls/customer-portal`,
      organizations: {
        create: `/resources/organizations/create`,
        transferOwnership: `/resources/organizations/transfer-ownership`,
        members: `/resources/organizations/members`,
      },
    },
  },
  sentry: {
    dsn: env.SENTRY_DSN,
  },
  subscriptions: {
    products: [
      {
        name: 'Basic',
        productId: 57713,
        description: 'Description of your Basic plan',
        badge: `Up to 20 users`,
        features: [
          'Basic Reporting',
          'Up to 20 users',
          '1GB for each user',
          'Chat Support',
        ],
        plans: [
          {
            name: 'Monthly',
            price: '$9',
            variantId: 55476,
          },
          {
            name: 'Yearly',
            price: '$90',
            variantId: 55512,
          },
        ],
      },
      {
        name: 'Pro',
        badge: `Most Popular`,
        recommended: true,
        productId: 57719,
        description: 'Description of your Pro plan',
        features: [
          'Advanced Reporting',
          'Up to 50 users',
          '5GB for each user',
          'Chat and Phone Support',
        ],
        plans: [
          {
            name: 'Monthly',
            price: '$29',
            variantId: 55483,
            trialPeriodDays: 0,
          },
          {
            name: 'Yearly',
            price: '$200',
            variantId: 55482,
            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',
            variantId: 0,
            label: `Contact us`,
            href: `/contact`,
          },
        ],
      },
    ],
  },
};

export default configuration;
```

## How should I store my secrets?

You should store your secrets in your **non public** environment variables, and ideally set up from your CI or Hosting Provider (such as Vercel).

Never add secrets to the configuration file, as it is exposed in the client-side bundles of your project.

Please refer to the Remix official documentation on how to best store your
secrets.

Learn how and where to edit your project configuration in your Makerkit SaaS application.

How to edit your Makerkit project configuration


Most of the branding details of your SaaS will be stored in the main configuration file of your application. This file is located at `src/configurations.ts`.

The `site` object contains most of your branding details. You can update the following properties:

```tsx
site: {
  name: 'Awesomely - Your SaaS Title',
  description: 'Your SaaS Description',
  themeColor: '#ffffff',
  themeColorDark: '#0a0a0a',
  siteUrl: process.env.NEXT_PUBLIC_SITE_URL,
  siteName: 'Awesomely',
  twitterHandle: '',
  githubHandle: '',
  language: 'en',
  convertKitFormId: '',
  locale: process.env.NEXT_PUBLIC_DEFAULT_LOCALE,
},
```

1. The `name` and `description` properties will be used in the meta tags of your application
2. The `themeColor` and `themeColorDark` properties will be used to update the color of the browser bar on mobile devices.
3. The `siteName` property is a short version of your SaaS title, without the subtitle.
4. The `twitterHandle` and `githubHandle` properties will be used to link to your social media accounts (if you have any).
5. The `locale` property is the default language of your application
6. The `language` property is deprecated and will be removed in a future version of Makerkit. Please use the `locale` property instead.
7. The `convertKitFormId` property is used to link your application to your ConvertKit account if you use the Newsletter form.

## Design Branding

Please refer to the [Theming](theming) section to learn how to update the design of your application.

A unique branding is essential to any SaaS. Learn how to update your Makerkit application branding.

Update your Makerkit application Branding


Makerkit by default provides an SVG logo with the default Makerkit logo. In addition, we also provide a `mini` version of the logo that is used when the sidebar is collapsed.

You should change both the `LogoImage` and `LogoImageMini` to match your brand.

### Where are the logos defined?

The logos are defined in two files:

1. `app/core/ui/Logo/LogoImage.tsx`
2. `app/core/ui/Logo/LogoImageMini.tsx`

Feel free to replace the default logo with your own logo.

### What sizes should my logo be?

The optimal sizes for the logs are:

1. The logos should be 20px tall to fit well in the header.
2. The logo mini should be 20px tall and 20px wide.

### I like Makerkit's logo! How can I reuse it for my own logo?

[Download the Makerkit Figma file from here](/assets/makerkit.fig) and use the logo from there.

Learn how to update the logos of your Makerkit site

Updating the logo of your Makerkit site


### What fonts are used by default?

By default, **Makerkit uses the system Apple font on Apple devices**, the `Inter` font as fallback.

### Removing Apple font as default

If you want to remove the `Apple` font as default, update the fonts in the Tailwind config file.

```js
fontFamily: {
  serif: ['serif'],
  heading: ['system-ui', 'Helvetica Neue', 'Helvetica', 'Arial'],
  sans: [
    'system-ui',
    'BlinkMacSystemFont',
    'Inter',
    'Segoe UI',
    'Roboto',
    'Ubuntu',
  ],
  monospace: [`SF Mono`, `ui-monospace`, `Monaco`, 'Monospace'],
}
```

If you are importing a font from Google Fonts, update the font in the `index.css` file.

```css title="app/styles/index.css"
@import url('//fonts.googleapis.com/css2?family=Inter:wght@300;400;500;700;800&display=swap&display=swap');
```

The above uses Inter, but you can update with the value set in the Tailwind config file.

NB: the font loaded in the CSS file **must match the font name in the Tailwind config file**.

Learn how to update the fonts of your Makerkit landing pages

Updating the fonts of your Makerkit site


If you have a logo for your company, you can easily update the favicons of your Makerkit applications. Favicons are the small icons that appear in the browser tab of your website.

### Where to find the favicons

Favicons are stored at `public/assets/images/favicon`. You can replace the existing files with your own images. If you keep the same names and sizes, then you don't need to update the code.

### How to generate favicons

If you do, I suggest to generate them using any o the online favicon generator, and then dropping the resulting images in the `public/assets/images/favicon` folder.

If you have different sizes and names, then you need to update the code to reflect these changes.

## How to update the favicons in Makerkit

This code is stored in the root `Head` component at `app/core/ui/Head.tsx`. You can update the code to match your new favicons.

```tsx title="app/core/ui/Head.tsx"
<link rel="shortcut icon" href="/assets/images/favicon/favicon.ico" />

<link
  rel="apple-touch-icon"
  sizes="144x144"
  href="/assets/images/favicon/apple-touch-icon.png"
/>

<link
  rel="icon"
  type="image/png"
  sizes="16x16"
  href="/assets/images/favicon/favicon-16x16.png"
/>

<link
  rel="icon"
  type="image/png"
  sizes="32x32"
  href="/assets/images/favicon/favicon-32x32.png"
/>

<link rel="manifest" href="/assets/images/favicon/site.webmanifest" />

<link
  rel="mask-icon"
  href="/assets/images/favicon/safari-pinned-tab.svg"
  color="#000000"
/>
```

Update the paths to match your new favicons.


Learn how to update the favicons of your Makerkit landing pages

Updating the favicons of your Makerkit site


Makerkit ships with some environment variables pre-configured for you.

If you don't have experience with environment variables, you can think of them as a way to store configuration values for your project.

Remix ships with a `.env` file that contains the following variables:

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

# set the below to "production" in your production environment
ENVIRONMENT=development

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

# STRIPE
STRIPE_WEBHOOK_SECRET=
STRIPE_SECRET_KEY=
NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY=

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

NB: Remix only used the `.env` file during development. If you want to use environment variables in production, you need to set them in your hosting provider.

## If I set mt variables in Vercel/another hosting provider, do I still need to set them in my project?

No. If you set your environment variables in your hosting provider, you don't need to set them in your project.

## Can I add secrets to my environment variables, like my OpenAI API key?

**No.** You should never add secrets to your environment variables. Instead, you should use your CI provider to set them.

## Does Remix automatically load my environment variables?

No - or better - only during development. Which means that you need to set them in your hosting provider if you want to use them in production.


Learn how to set environment variables in your Remix project and how to use them in your code.

Understanding and setting the environment variables in your Remix project


Sending emails is a critical part of your SaaS application. Makerkit uses emails to send invites to your users only, but it's likely you'll want to send other emails to your users.

To set up emails in your Makerkit application, you should add the following environment variables to your project, using a secure environment:

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

Makerkit will use these values to send emails on your behalf using the node library `nodemailer`.

NB: this does not refer to emails sent by Supabase. These have to be setup
from within the Supabase Dashboard. You can reuse the same SMTP settings.

### Where do I get these values?

These values are normally provided by your service provider.

### Which services are supported?

Any service that supports SMTP should work. We recommend using [Resend](https://resend.com/).

### How do I test emails locally?

Makerkit uses InBucket to test emails locally without the need for an SMTP
service. You can access InBucket at [localhost:54324](https://localhost:54324).

How to setup emails in your Makerkit SaaS application

Setup


The navigation menu of your Makerkit SaaS application's landing pages (or marketing side) is defined in the `SiteNavigation` component defined at `src/components/SiteNavigation.tsx`.

### Adding a new menu entry to the navigation menu

To add a new menu entry, simply add a new entry to the `links` object.

The key of the object is the name of the menu entry, and the value is an object with the `label` and `path` properties.

```tsx title="src/components/SiteNavigation.tsx" {22-25}
const links = {
  SignIn: {
    label: 'Sign In',
    path: '/auth/sign-in',
  },
  Blog: {
    label: 'Blog',
    path: '/blog',
  },
  Docs: {
    label: 'Docs',
    path: '/docs',
  },
  Pricing: {
    label: 'Pricing',
    path: '/pricing',
  },
  FAQ: {
    label: 'FAQ',
    path: '/faq',
  },
  NewPage: {
    label: 'New Page',
    path: '/new-page',
  },
};
```

Then, add a new `NavigationMenuItem` component to the `NavigationMenu` component.

```tsx title="src/components/SiteNavigation.tsx" {12}
<NavigationMenu>
  <NavigationMenuItem
    className={'flex lg:hidden'}
    link={links.SignIn}
  />

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

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

Et voilà! Your new menu entry is now available in the navigation menu.

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

Updating the navigation menu of your Makerkit SaaS application


To add a new page to the marketing site of your Remix project, you can create a new page in the `app/routes/_site` layout.

By "marketing site", we mean the public pages of your project, such as the homepage, the about page, the contact page, etc.

<div>
  <Alert type={'warn'}>
    <div>
      Use the below code only for public pages accessible by everyone, such as the homepage, the about page, the contact
      page, etc.
    </div>
  </Alert>
</div>

### Adding a new page to the marketing site

For example, if you want to add a page at `/about`, you can create a new file at `app/routes/_site.about._index.tsx` with the following content:

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

export default AboutPage;
```

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

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

If you don't want to use the site layout, create a new group inside `app/routes`, and add your page there. This replaces the `_site` layout with your own layout.


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

Adding pages to the marketing site of your Makerkit Remix Supabase project

Marketing Pages


Makerkit supports by default a dark theme. With that said, you can decide to opt-out of the dark theme and use the light theme only instead using the configuration below.

## Using the dark theme by default

To use the dark theme by default, you need to edit the following configuration to your `src/configuration.ts` file:

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

Users can still opt-out of the dark theme by using the theme switcher in the top right corner of the page.

## Using only the dark theme

To switch to the dark theme, you need to edit the following configuration to your `src/configuration.ts` file:

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

## Disabling the dark theme

To disable the dark theme and only use the light theme - you need to edit the following configuration to your `src/configuration.ts` file:

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

In the above, we flipped the `enableThemeSwitcher` to `false` and set the `theme` to `Themes.Light`.

Setting up the dark theme in Makerkit


Makerkit's theming is defined in two places:

1. the `global.css` file
2. the `tailwind.config.js` file.

## Colors

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

### Using the ShadCN themes

The ShadCN UI themes are predefined themes that you can use in your Makerkit project too.

You can [copy/paste the ShadCN themes](https://ui.shadcn.com/themes) into your `global.css` file and update the CSS variables to use the Makerkit color palette.

Next - you need to update the `tailwind.config.js` file in your project and update the `colors` object. These should match the CSS variables you have defined in the `global.css` file.

### Updating the Tailwind configuration

Additionally, we need to update the Tailwind configuration: since Makerkit uses a color palette based on Tailwind's palette system, we need to update the `tailwind.config.js` file in your project and update the `colors` object.

For example, since the default color for the `primary` color is `violet.500`, we need to update the `colors` object to:

```js
primary: {
  DEFAULT: 'hsl(var(--primary))',
  foreground: 'hsl(var(--primary-foreground))',
  ...colors.violet,
}
```

The code above spreads the `violet` color palette into the `primary` object, which means that the `primary` color will be the `violet.500` color.

The variable `--primary` is the hsl value of the `violet.500` color.

Additionally, we can access other colors of the `primary` palette using `primary-500`, `primary-600`, etc. This helps us to access the color palette in a more semantic way.

### Dark Mode

We need to do the same for the dark mode. Makerkit has historically used the `dark` color palette convention to define the dark mode colors.

By default, Makerkit uses `slate` as the dark mode color palette, so we need to update the `colors` object to:

```js
dark: {
  ...colors.slate,
  DEFAULT: colors.slate[950],
  foreground: colors.slate[100],
}
```

As you can see, we spread the `slate` color palette into the `dark` object, which means that the `dark` color will be the `slate.950` color.

If you were to use another color such as `zinc`, you would need to update the `colors` object to:

```js
dark: {
  ...colors.zinc,
  DEFAULT: colors.zinc[950],
  foreground: colors.zinc[100],
}
```

## Icons

While ShadCN UI uses `lucide` as their icons library, Makerkit has historically used `heroicons`. We have configured ShadCN UI to use `heroicons` instead of `lucide` in all Makerkit projects, but for new components, you will need to use `lucide` instead if you don't want to make changes. As such, please install `lucide` as a dependency in your project.

Discover how to apply the ShadCN UI theme to your Makerkit project.

Theming

User Interface


API routes are a way to create a custom API endpoint for your application. You can use API routes to create RESTful endpoints that return JSON data.

Adding an API route to a Makerkit application is no different than any other Remix project. Let's see how.

## Creating an API Route

To create an API route, will export an `action` function from your routes.

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

```ts title="app/routes/hello._index.ts"
import { json } from "@remix-run/node";

export async function loader() {
  return json({ text: 'Hello' });
}
```

This is kinda simple, right? Let's see how we can use this API route in our application.

### Protecting API Routes

It's very likely that you want to ensure only authenticated users can access your API routes. To do that, you can use the `requireSession` function.

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

```ts title="app/routes/route._index.ts"
import { LoaderFunctionArgs } from "@remix-run/node";

import getSupabaseServerClient from '~/core/supabase/server-client';
import requireSession from '~/lib/user/require-session.server';

export async function loader(args: LoaderFunctionArgs) {
  const client = getSupabaseServerClient(args.request);
  const session = await requireSession(client);

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


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

Adding API Routes in your Remix application


Makerkit includes the library React Query, a data-fetching React utility library.

This library is useful for making asynchronous requests from your React components. For example:

1. When interacting with the Supabase Client (DB, Storage, Auth, etc.)
2. When making requests to API Routes

Why is it useful? React Query makes it simpler to fetch and mutate data, caching and revalidating. Let's see how we can use it to make requests to our endpoints.

### Should I use React Query or Remix's useFetcher/useSubmit?

No exact answer - but here is what I do:

1. For actions that need to trigger a refresh of the UI, I use Remix's `useSubmit/useRefresh` hook.
2. For pulling data from the server-side as a result of user interactions, I use SWR.

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

## Using SWR for fetching data from an API Route Handler

Let's assume we have a very simple API Route at `routes/resources.data.ts`:

```tsx title="app/routes/resources.data.ts"
import { json } from "@remix-run/node";

export async function loader() {
  return json({
    hello: "world"
  });
}
```

As you may know, we can call the endpoint `/resources/data` using a GET request and will receive the JSON response `{ "hello": "world" }`.

Now, we want to call this from our Remix application using React Query, and use
it within a React component.

We proceed building a React Hook with SWR which is able to fetch the data from our endpoint `/api/data`:

```tsx
import { useQuery } from '@tanstack/react-query';

export function useFetchData() {
  const key = '/api/data';

  return useQuery([key], async () => {
    return fetch(key).then(res => res.json())
  });
}
```

Now, we can call this endpoint from any React component:

```tsx
function MyComponent() {
  const { data, loading, error } = useFetchData();

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

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

  return <div>{data.hello}</div>
}
```

## Mutating data with React Query

When it comes to mutating data, we can use the `useMutation` utility, designed to make mutations simple.

As you may know, mutations will likely use the method `POST`, `PUT`, `PATCH`, or `DELETE`. In these cases, the middleware in the kit will require us to send a CSRF token for security reasons.

As such, we provide a handy wrapper around `fetch`.

Let's write a very simple API Route that makes a mutation: we add a new record in the `tasks` table, and return the ID back to the client.

```tsx
import { ActionFunctionArgs, json } from "@remix-run/node";

export async function action(args: ActionFunctionArgs) {
  const client = getSupabaseServerClient(args.request);
  const session = await requireSession(client);
  const task = args.request.json();

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

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

Now, let's write a React Hook that calls this endpoint using React Query.

```tsx
import { useMutation } from '@tanstack/react-query';
import useFetch from '~/core/hooks/use-fetch';

interface Task {
  name: string;
}

function useInsertTask() {
  const fetcher = useFetch();
  const path = '/api/task';

  return useMutation(
    path, async (data: Task) => {
      return fetcher({
        path,
        body: data,
        method: 'POST'
      });
    }
  );
}
```

What does `useFetch` do? This hook automatically inserts the CSRF token in our fetch requests, so that you don't have to.

If you prefer not using it, you can manually add the CSRF token instead:

```tsx
import { useMutation } from '@tanstack/react-query';
import useCsrfToken from '~/core/hooks/use-csrf-token';

interface Task {
  name: string;
}

function useInsertTask() {
  const csrfToken = useCsrfToken();
  const path = '/api/task';

  return useMutation((data: Task) => {
      return fetch(path, {
        body: JSON.stringify(data),
        method: 'POST',
        headers: {
          'x-csrf-token': csrfToken
        }
    });
  });
}
```

We can now call the mutation from a React component:

```tsx
function TaskForm() {
  const insertTaskMutation = useInsertTask();

  const onSubmit: React.FormEventHandler<HTMLFormElement> = (event) => {
    const name = new FormData(event.currentTarget).get('name') ?? 'No Name';
    const task = { name };

    return insertTaskMutation.mutateAsync(task);
  };

  return (
    <form onSubmit={onSubmit}>
      <input type={'name'} required />

      <button disabled={insertTaskMutation.loading}>
        Submit
      </button>
    </form>
  );
}
```


Learn how to use SWR to call your API route handlers from React components

Calling API Routes from the client-side using SWE

API Routes


To add a new page to the application site of your Remix project, you can create a new page in the `app/routes` directory under the layout `_app`. This means your new pages will follow the convention `_app.<page>.tsx`.

For example, the tasks page of the application is located at `app/routes/_app.tasks._index.tsx`.

### What does the `_app` layout do?

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

This directory contains the pages that are **only accessible to authenticated users**.

### Layout and Sidebar

Pages created within the layout `_app` will inherit the layout of the directory and will be displayed together with the Sidebar menu.

### Example - Creating a new page

For example, let's create a `Tasks` application located at `/tasks`. We will then create a new page at `_app.tasks._index.tsx`.

```tsx title="app/routes/_app.tasks._index.tsx"
import type {
  LoaderFunctionArgs,
  MetaFunction,
} from '@remix-run/node';

import { useLoaderData } from '@remix-run/react';
import { RectangleStackIcon } from '@heroicons/react/24/outline';

import { Trans } from 'react-i18next';

import AppHeader from '~/components/AppHeader';
import AppContainer from '~/components/AppContainer';

export const meta: MetaFunction = () => {
  return [
    {
      title: 'Tasks',
    },
  ];
};

export async function loader(args: LoaderFunctionArgs) {
  await requireSession(
    getSupabaseServerClient(args.request),
  );
  // return tasks
}

function TasksPage() {
  const { tasks } = useLoaderData<typeof loader>();

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

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

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

export default TasksPage;
```

### Remember: always validate the session in every page

The parallel loading done by Remix to optimize the loading of the application means we cannot rely on parent routes to validate the session. This means that we need to validate the session in every page.

If your page needs authentication, add a loader and protect it with `requireSession`:

```tsx
export async function loader(
  args: LoaderFunctionArgs
) {
  await requireSession(
    getSupabaseServerClient(args.request),
  );
}
```

### Layout

Layout-wise, we added the following components:

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

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


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

Adding pages to the application of your Makerkit Remix Supabase project


The Sidebar of your Makerkit SaaS application is defined in the `src/navigation.config.tsx` configuration file.

This allows you to easily add, remove, or update the menu entries of your application and automatically generate a responsive sidebar menu for your users.

### Adding a new menu entry to the Sidebar

To add a new menu entry to the sidebar, simply add a new entry to the `NAVIGATION_CONFIG.items` array in the `src/navigation.config.tsx` file.

A menu entry is defined by the following properties:
```tsx
{
  label: string;
  path: string;
  Icon: (props: { className: string }) => JSX.Element;
}
```

- `label`: The label of the menu entry. This label will be displayed in the sidebar of your application. This can be either a reference to a translation key or a string.
- `path`: The path of the menu entry. This path will be used to generate the `href` attribute of the menu entry.
- `Icon`: The icon of the menu entry. This icon will be displayed in the sidebar of your application.

Consider the default schema below:

```tsx
import configuration from '~/configuration';

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

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

export default NAVIGATION_CONFIG;
```

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

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

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

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

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

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

Updating the sidebar menu of your Makerkit SaaS application


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

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

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

```tsx
import { LoaderFunctionArgs } from "@remix-run/node";

async function loader(args: LoaderFunctionArgs) {
  const data = await loadAppData(args);
  const userRole = data.role;

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

  // return props to the page
}

async function OnlyOwnersPage() {
  const data = await useLoaderData<typeof loader>();
  // render the page
}
```

As you can see above:

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

## Guarding Application Pages with Organization Subscriptions

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

To do so, we check the `subscription` property of the `Organization` object and redirect the user to the dashboard if the subscription is `active` or `trialing`.

```tsx
import { LoaderFunctionArgs, redirect } from "@remix-run/node";

async function loader(args: LoaderFunctionArgs) {
  const data = await loadAppData(args);
  const status = data.organization.subscription?.data?.status;

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

  // return props to the page
}

async function OnlySubscribersPage() {
  const data = await useLoaderData<typeof loader>();
  // render the page
}

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

Learn how to guard pages in your Remix Supabase application

Guarding Pages

Application Pages


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

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

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

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

We will need to edit this file to change the authentication strategy.

### Enabling Email and Password Authentication

This is the default authentication strategy. It allows users to sign up and sign in using their email and password.

To enable this strategy, set `providers.emailPassword` to `true`.

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

### Enabling Phone Number Authentication

This strategy allows users to sign up and sign in using their phone number.

To enable this strategy, set `providers.phoneNumber` to `true`.

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

### Enabling Email Link Authentication

This strategy allows users to sign up and sign in using their email address. A link will be sent to their email address to verify their identity.

To enable this strategy, set `providers.emailLink` to `true`.

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

### Enabling OAuth Authentication

This strategy allows users to sign up and sign in using their social media accounts. You can enable multiple OAuth providers.

To enable this strategy, set `providers.oAuth` to an array of OAuth providers.

```tsx
providers: {
  emailPassword: false,
  phoneNumber: false,
  emailLink: false,
  oAuth: ['google', 'facebook'] as Provider[]
},
```

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

## Can I use multiple authentication strategies?

Yes, you can use multiple authentication strategies. For example, you can enable email and password authentication and phone number authentication at the same time.

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

With that said, the UI is not designed to support multiple authentication strategies. **You will need to customize the UI to support multiple authentication strategies**.


Learn how to change the authentication strategy in Makerkit. Choose between email and password, phone number, email link, and OAuth.

How to change Authentication strategy


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

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

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

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

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

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

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

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

### How to Setup an oAuth Provider

Most of the setup is done in two places:

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

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

Learn how to setup oAuth in the Remix Supabase Starter

How to setup oAuth in the Remix Supabase Starter

Authentication


There are several ways to fetch the signed in user, depending on the use-case.

## Fetching the signed in user from the backend

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

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

### Using "requireSession" in API Routes

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

```tsx
import getSupabaseServerClient from '~/core/supabase/server-client';
import requireSession from '~/lib/user/require-session.server';

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

### Using "requireSession" in Loaders

When using Remix Loaders, you can retrieve the signed in user using the `requireSession` function.

```tsx
import { LaaderFunctionArgs } from '@remix-run/node';

import getSupabaseServerClient from '~/core/supabase/server-client';
import requireSession from '~/lib/user/require-session.server';

export async function loader(args: LaaderFunctionArgs) {
  const client = getSupabaseServerClient();
  const session = await requireSession(client);

  // use session here
}
```

### Using "requireSession" Actions

You can use the `requireSession` function in Remix Actions to retrieve the signed in user.

```tsx
import { ActionFunctionArgs } from '@remix-run/node';

export async function action(args: ActionFunctionArgs) {
  const client = getSupabaseServerClient(args.request);
  const session = await requireSession(client);

  // use session here
}
```

## Fetching the signed in user from the frontend

When in the scope of the `_app` layout, the app automatically injects the user session in the context layout.

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

### Getting the user Session with "useUserSession"

To retrieve the signed in user from the frontend, you can use the `useUserSession` hook:

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

const userSession = useUserSession();
```

This is a React hook and can only be used inside a React component.

### Getting the user ID with "useUserId"

To retrieve the signed in user ID from the frontend, you can use the `useUserId` hook:

```tsx
import useUserId from '~/core/hooks/use-user-id';

const userId = useUserId();
```

This is a React hook and can only be used inside a React component.

### Getting the user role within the organization with "useUserRole"

To retrieve the signed in user role of the current organization from the frontend, you can use the `useUserRole` hook:

```tsx
import useCurrentUserRole from '~/core/hooks/use-current-user-role';

const role = useCurrentUserRole();
```

This is a React hook and can only be used inside a React component.


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

Fetching the signed in User


There are several ways to fetch the current selected organization, depending on the use-case.

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

You can use the `parseOrganizationIdCookie` function in:

- Remix Loaders
- Remix Actions

```tsx
import { LoaderFunctionArgs } from '@remix-run/node';
import getSupabaseServerClient from '~/core/supabase/server-client';
import requireSession from '~/lib/user/require-session.server';

import {
  parseOrganizationIdCookie,
} from '~/lib/server/cookies/organization.cookie';

async function getOrganizationId(request: Request) {
  const client = getSupabaseServerClient(request);
  const session = await requireSession(client);

  return parseOrganizationIdCookie(request, session.user.id);
}

export async function loader(args: LoaderFunctionArgs) {
  const organizationId = await getOrganizationId(args.request);

  return json({ organizationId });
}
```

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

## Fetching the selected Organization from the backend

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

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

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

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

```tsx
import { ActionFunctionArgs } from '@remix-run/node';

import getCurrentOrganization from '~/lib/server/organizations/get-current-organization';
import getSupabaseServerClient from '~/core/supabase/server-client';
import requireSession from '~/lib/user/require-session.server';

import {
  parseOrganizationIdCookie,
} from '~/lib/server/cookies/organization.cookie';

export async function action({ request }: ActionFunctionArgs) {
  const client = getSupabaseServerClient();
  const session = await requireSession(client);
  const userId = session.user.id;
  const organizationId = await parseOrganizationIdCookie(request, userId);

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

## Fetching the selected Organization from the frontend

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

### Getting the Organization with "useCurrentOrganization"

To retrieve the signed in user from the frontend, you can use the `useUserSession` hook:

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

const organization = useCurrentOrganization();
```

This is a React hook and can only be used inside a React component.

### Getting if the Organization subscription status is set to "active" on the frontend

You can use the `useIsSubscriptionActive` hook to get the subscription status of the current organization. You may want to use this function to gate access to certain parts of the app.

```tsx
import useCurrentOrganization from '~/lib/organizations/hooks/use-is-subscription-active';

const isActive = useIsSubscriptionActive();
```

This is a React hook and can only be used inside a React component.




Learn how to fetch the selected organization from the backend and frontend.

Fetching the selected Organization

Contextual Data


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

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

### Adding data to the seed file

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

Then, you can run the `diff` command:

```
supabase diff
```

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

The next database restarts will use the new data inserted.


Learn how to seed data in your Supabase Database

How to seed data in your Supabase application


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

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

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

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

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

Learn how to reset the seed data in your Supabase Database

How to reset your local Database


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

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

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

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

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

How to generate your Supabase Database types

Database


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

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

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

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

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

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

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

## Usage

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

1. Loader functions
2. Action Functions
3. React Client Components

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

### Backend

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

```tsx
import { LoaderFunctionArgs, json, redirect } from '@remix-run/node';

const TaskPage = () => {
  const { task } = useLoaderData<typeof laoder>();

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

export async function loader(args: LoaderFunctionArgs) {
  const client = getSupabaseServerClient(args.request);
  const taskId = args.params.taskId;
  const { data: task } = await getTask(client, Number(taskId));

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

  return json({
    task,
  });
}

export default TaskPage;
```

### Frontend

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

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

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

```tsx
import useQuery from "@tanstack/react-query";

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

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

We can then use the hook in a React component:

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

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

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

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

Learn how to read records from Supabase using your Remix Supabase application

Reading Records from Postgres

Reading Data


When taking payments from Stripe, you're required to configure your subscription's plans.

Your plans need to be configured in two places:

1. **Stripe** - first, you need to define your **products** and **plans** in Stripe itself. This requires you to have an account in Stripe.
2. **Configuration**: - then, you will copy your plans data in the Makerkit configuration, which is used to render the Pricing table and display the prices metadata

### Pricing Table Configuration

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

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

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

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

#### Update the Stripe Price IDs values!

Please replace the property `stripePriceId` with the real price ID from the
Stripe Dashboard.

<div>
  <Alert type="warn">
    <Alert.Heading>Update your real Stripe Price IDs</Alert.Heading>

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

### Additional Configuration

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

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

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

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


Learn how to configure the Stripe plans in your SaaS application with Makerkit

Configuring your SaaS Stripe Plans in your Makerkit Remix Supabase App


When testing webhooks sent by Stripe, it's useful to redirect them to our local webhook endpoint so that we can test them locally.

Makerkit has a built-in NPM script that starts the Stripe CLI and redirects webhooks to our local endpoint.

## Prerequisites

The only prerequisite is to have Docker installed and running on your machine.

## Running the Stripe Webhook locally

To run the Stripe Webhook locally, run the following command:

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

The first time you run this command, it will ask you to login to your Stripe account. Follow the instructions on the screen to do so.

Once you're logged in, run the command again:

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

This time, the Stripe CLI will start and redirect webhooks to our local endpoint.

You can now test your webhooks locally when testing your Stripe integration with Makerkit 🎉


Want to test and run the Stripe Webhook locally? This guide will show you how to do it.

Running the Stripe Webhook locally


To use Lemon Squeezy instead of Stripe, you should use the branch `main-ls` to develop your SaaS.

The Lemon Squeezy configuration is slightly different from the Stripe configuration as it accepts a variant ID instead of a price ID.

```tsx
subscriptions: {
  plans: [
    {
      name: 'Basic',
      description: 'Description of your Basic plan',
      badge: `Up to 20 users`,
      features: [
        'Basic Reporting',
        'Up to 20 users',
        '1GB for each user',
        'Chat Support',
      ],
      plans: [
        {
          name: 'Monthly',
          price: '$9',
          variantID: '<your variant ID>',
        },
        {
          name: 'Yearly',
          price: '$90',
           variantID: '<your variant ID>',
        },
      ],
    },
    {
      name: 'Pro',
      badge: `Most Popular`,
      recommended: true,
      description: 'Description of your Pro plan',
      features: [
        'Advanced Reporting',
        'Up to 50 users',
        '5GB for each user',
        'Chat and Phone Support',
      ],
      plans: [
        {
          name: 'Monthly',
          price: '$29',
           variantID: '<your variant ID>',
        },
        {
          name: 'Yearly',
          price: '$200',
          variantID: '<your variant ID>',
        },
      ],
    },
    {
      name: 'Premium',
      description: 'Description of your Premium plan',
      badge: ``,
      features: [
        'Advanced Reporting',
        'Unlimited users',
        '50GB for each user',
        'Account Manager',
      ],
      plans: [
        {
          name: '',
          price: 'Contact us',
          label: `Contact us`,
          href: `/contact`,
        },
      ],
    },
  ]
}
```

Please refer to the [complete Lemon Squeezy documentation](/docs/next-supabase/lemon-squeezy) for more details.

How to use Lemon Squeezy instead of Stripe in your Makerkit application

Using Lemon Squeezy instead of Stripe in your Makerkit application

Payments


The translations of the application are stored at `public/locales/<en>`.

We have various translations languages JSON files by default (only in English):
- `public/locales/en/common.json` - where we store the common translations
- `public/locales/en/auth.json` - where we store the auth translations
- `public/locales/en/profile.json` - where we store the profile settings translations
- `public/locales/en/organization.json` - where we store the organization settings translations
- `public/locales/en/subscription.json` - where we store the subscription settings translations

You can keep adding translations to these files if you wish, or create new bundles for your translations.

## Adding a new translation string

Let's say we want to add a new translation string to the `common.json` file.

1. Open the `public/locales/en/common.json` file and add the new translation string:

```json
{
  "new_translation_string": "This is a new translation string"
}
```

You can then reference this key in your application like this:
1. Using the `Trans` component from `~/core/ui/Trans`
2. Using the `useTranslation` hook from `react-i18next`

For example, using the `Trans` component:

```tsx
<Trans i18nKey="common:new_translation_string" />
```

or using the `useTranslation` hook:

```tsx
const { t } = useTranslation();
const newTranslationString = t('common:new_translation_string');
```


Adding new translations to your application is easy. This guide will show you how to add a new translation string to your application.

Adding a new translation string


Setting a default language in your Remix Supabase application is easy.

Simply set the environment variable `DEFAULT_LOCALE` to the language code you want to use as the default language.

By default, we use `en` as the default language. If you want to change it, simply add the following line to your `.env` file. For example, if you want to use Spanish as the default language, you would add the following line to your `.env` file:

```bash
DEFAULT_LOCALE=es
```

Make sure to set this environment variable in your hosting provider as well for your production application.

Learn how to set a default language for your Makerkit application.

Setting a Default Language


To add a new locale to your application, you need to create a new file in the `public/locales` directory.

For example, to add a new language called `fr` (French), you would create a new file called `fr.json` in the `public/locales` directory.

```json
{
  "hello": "Bonjour"
}
```

That's it! Now you can use the `hello` key in your application and it will be translated to `Bonjour` when the locale is set to `fr`.

How to add a new language to your Remix Supabase application.

Adding a new language


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

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

```typescript
import isBrowser from '~/core/generic/is-browser';

const env = isBrowser() ? window.ENV : process.env;
const DEFAULT_LOCALE = env.DEFAULT_LOCALE ?? 'en';

const i18Config = {
  fallbackLanguage: DEFAULT_LOCALE,
  supportedLanguages: [DEFAULT_LOCALE],
  defaultNS: ['common', 'auth', 'organization', 'profile', 'subscription'],
  react: { useSuspense: false },
};

export default i18Config;

```

We add the `tasks` bundle name to the `i18Config.defaultNS` array:

```typescript {4}
const i18Config = {
  fallbackLanguage: DEFAULT_LOCALE,
  supportedLanguages: [DEFAULT_LOCALE],
  defaultNS: ['common', 'auth', 'organization', 'profile', 'subscription', 'tasks'],
  react: { useSuspense: false },
};
```

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

How to add a new translation file to your application.

Adding a new translation file


By default, the language switcher is not used within the Remix Supabase starter. To use it, you will need to import it into your application and add it to your layout.

To do so, import the `LanguageSwitcher` component from the `components` directory and add it to any component you want to display it in.

```tsx
import { LanguageSwitcher } from '~/components/LanguageSwitcher';

export const YourComponent = ({ children }) => {
  return (
    <div>
      <LanguageSwitcher />
      {children}
    </div>
  );
};
```

The language switcher will automatically display the current language and a list of available languages. When a user clicks on a language, the language will be updated in the user's profile and the page will be reloaded.

Import and use the LanguageSwitcher component in your Remix Supabase application.

Using the Language Switcher

Translations


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

## Is Docker running?

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

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

## Is Supabase already running?

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

```bash
docker ps
```

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

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

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

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

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

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

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

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

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

How to fix: Supabase is not starting


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

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

```bash
docker ps
```

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

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

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

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

How to fix: Supabase is not stopping


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

This can happen for two reasons:

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

## This is happening when running Supabase locally

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

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

### This is happening in the Supabase Cloud Instance

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

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

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

We can do this by running the following command:

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

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

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

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

The output should look like this:

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

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

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

How to fix: Supabase tables not found


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

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

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

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

Contentlayer gets stuck when starting the Makerkit application

Troubleshooting

Tutorials


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

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

1. Home Page and marketing pages (blog, pricing, FAQ)
2. Authentication (sign in, sign up, password reset)
3. Payments with Stripe
4. Profile Settings
5. Organization Settings
6. Tasks management with paginated Table and CRUD operations
7. Super Admin

## Prerequisites

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

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

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

If you have all the above installed, let's get started!

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

Building a SaaStasks application with Makerkit


## Initializing the Project

You have two ways to initialize the project:

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

### 1. Forking the Repository

Fork this repository by clicking on the "Fork" button on the top-right
corner in GitHub for the repository you want to use. Please be aware that by forking the repository, the Makerkit organization has read-only access to your forked repository.

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

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

### 2. Cloning the Repository

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

```
git clone git@github.com:makerkit/remix-supabase-saas-kit.git tasks-app
```

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

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

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

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

Run the following command to run the CLI:

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

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

### Reinitialize Git

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

```
git remote rm origin
```

Now you have a clean Git repository.

### Setting the Upstream Repository

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

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

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

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

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

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

As updates are released almost daily, remember to pull updates often!

---

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

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

Initial Setup


When inspecting the project structure, you will find something similar to the below:

```
tasks-app
├── README.md
├── @types
├── src
│   ├── components
│   ├── core
│   ├── lib
│   └── routes
        ...
│       └── root.tsx
├── package-lock.json
├── package.json
├── public
│   └── favicon.ico
└── tsconfig.json
```

NB: we omitted a lot of the files for simplicity.

Let's take a deeper look at the structure we see above:

- `src/core`: this folder contains reusable building blocks of the template that **are not related to any domain**. This includes components, React hooks, functions, and so on.
- `src/components`: this folder contains the application's components, including those that belong to your application's domain. For example, we can add the `tasks` components to `src/components/tasks`.
- `src/lib`: this folder contains the business logic of your application's
domain. For example, we can add the `tasks` hooks to write and fetch data
from Supabase in `src/lib/tasks`.
- `src/routes`: this is Remix folder where we add our application
routes.

Don't worry if this isn't clear yet! We'll explain where we place our files in the sections ahead.

A quick overview of the project structure and how to navigate it.

Project Structure


## Running the project

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

### Why do we need to run the Supabase local environment?

The guide below will show you how to run the application locally. But why locally? Developing locally has many advantages over developing on a remote server:

**Speedy Development:** Local development lets you work without the hindrance of network latency or internet disruptions.

**Simplified Collaboration:** It's typically easier to collaborate with teammates when developing locally on the same project.

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

**Code-Based Configuration:** Any modifications to your tables via the Dashboard aren't reflected in code. Adopting local development workflows allows you to maintain all table schemas in code.

Once you are ready to deploy your application, you can do so by following
the [production checklist guide](/docs/remix-supabase/going-to-production-overview).

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

### Adding the environment variables file

The kit comes with a template of what your `.env` file should look like named `.env.template`.

**Before you continue**: rename `.env.template` to `.env`, or copy its contents to `.env`.

**This file won't be committed to git**. When you deploy your production app, ensure you add the environment variables using your CI/Service.

NB: Remix does not use the `.env` file when bundling the application in production mode.

### Building the Content using Contentlayer

Before running the application, we need to build the content using Contentlayer. To do so, run the following command:

```
npm run contentlayer:build
```

### Running the Remix development server

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

```
npm run dev
```

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

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

### Running the Supabase Local environment

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

```
npm run supabase:start
```

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

```
> supabase start

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

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

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

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

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

```
npm run supabase:stop
```

#### Supabase Studio UI

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

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

### Running the Stripe CLI (optional)

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

1. Have a Stripe account
2. Have Docker installed and running
3. Run the Stripe CLI (or install Stripe on your OS)

To run the CLI, run the following command:

```
npm run stripe:listen
```

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

After signing in, run the command again.

```
npm run stripe:listen
```

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

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

```
STRIPE_WEBHOOK_SECRET=<KEY>
```

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

### Signing In for the first time

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

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

### Email Confirmations for Testing with InBucket

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

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

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

Learn how to run the app locally for development and testing.

Running the App


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

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

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

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

Here is what the configuration file looks like:

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

const env = getEnv() ?? {};
const production = env.NODE_ENV === 'production';

enum Themes {
  Light = 'light',
  Dark = 'dark',
}

const configuration = {
  site: {
    name: 'Awesomely - Your SaaS Title',
    description: 'Your SaaS Description',
    themeColor: '#ffffff',
    themeColorDark: '#0a0a0a',
    siteUrl: env.SITE_URL,
    siteName: 'Awesomely',
    twitterHandle: '',
    githubHandle: '',
    language: 'en',
    convertKitFormId: '',
    locale: env.DEFAULT_LOCALE,
  },
  auth: {
    // ensure this is the same as your Supabase project
    requireEmailConfirmation: true,
    // NB: Enable the providers below in the Supabase Console
    // in your production project
    providers: {
      emailPassword: true,
      phoneNumber: false,
      emailLink: false,
      oAuth: ['google'] as Provider[],
    },
  },
  production,
  environment: env.ENVIRONMENT,
  features: {
    enableThemeSwitcher: true,
  },
  theme: Themes.Dark,
  paths: {
    signIn: '/auth/sign-in',
    signUp: '/auth/sign-up',
    signInMfa: '/auth/verify',
    signInFromLink: '/auth/link',
    callback: '/auth/callback',
    onboarding: `/onboarding`,
    appHome: '/dashboard',
    settings: {
      profile: '/settings/profile',
      authentication: '/settings/profile/authentication',
      email: '/settings/profile/email',
      password: '/settings/profile/password',
    },
    api: {
      checkout: `/resources/stripe/checkout`,
      billingPortal: `/resources/stripe/portal`,
      organizations: {
        create: `/resources/organizations/create`,
        transferOwnership: `/resources/organizations/transfer-ownership`,
        members: `/resources/organizations/members`,
      },
    },
  },
  email: {
    host: 'smtp.ethereal.email',
    port: 587,
    user: 'gracie.hand58@ethereal.email',
    password: '5hr3DDGGc2bTbu7tJR',
    senderAddress: 'MakerKit Team <info@makerkit.dev>',
  },
  sentry: {
    dsn: env.SENTRY_DSN,
  },
  stripe: {
    products: [
      {
        name: 'Basic',
        description: 'Description of your Basic plan',
        badge: `Up to 20 users`,
        features: [
          'Basic Reporting',
          'Up to 20 users',
          '1GB for each user',
          'Chat Support',
        ],
        plans: [
          {
            name: 'Monthly',
            price: '$9',
            stripePriceId: '<price_id>',
          },
          {
            name: 'Yearly',
            price: '$90',
            stripePriceId: '<price_id>',
          },
        ],
      },
      {
        name: 'Pro',
        badge: `Most Popular`,
        recommended: true,
        description: 'Description of your Pro plan',
        features: [
          'Advanced Reporting',
          'Up to 50 users',
          '5GB for each user',
          'Chat and Phone Support',
        ],
        plans: [
          {
            name: 'Monthly',
            price: '$29',
            stripePriceId: '<price_id>',
          },
          {
            name: 'Yearly',
            price: '$200',
            stripePriceId: '<price_id>',
          },
        ],
      },
      {
        name: 'Premium',
        description: 'Description of your Premium plan',
        badge: ``,
        features: [
          'Advanced Reporting',
          'Unlimited users',
          '50GB for each user',
          'Account Manager',
        ],
        plans: [
          {
            name: '',
            price: 'Contact us',
            stripePriceId: '',
            label: `Contact us`,
            href: `/contact`,
          },
        ],
      },
    ],
  },
};

export default configuration;
```

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

Learn how to set up up your project's configuration

Project Configuration


The starter project comes with two different environment variables files:
1. **.env**: the main environment file
2. **.env.test**: this environment file is loaded when running the Cypress
E2E tests. You would rarely need to use this.

NB: the `.env` file is never committed to the repository. This is because it
contains sensitive information, such as API keys. Instead, we use a `.env.
template` file to show what the `.env` file should look like.

The environment variables for the Remix Supabase kit look like the below:

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

# set the below to "production" in your production environment
ENVIRONMENT=development

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

# STRIPE
STRIPE_WEBHOOK_SECRET=
STRIPE_SECRET_KEY=
NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY=

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

<Alert>
  <Alert.Heading>
    Define your environment variables in your hosting provider
  </Alert.Heading>

  Remix does not use .env files for bundling your app in production. Therefore, you will need to define your environment
  variables in your hosting provider (such as Vercel).
</Alert>

### Define your environment variables in your hosting provider

**NB**: Remix will not bundle environment variables when building your app, but only during development mode. This needs to be repeated, as it is often confused with how Next.js works.

Instead, you will need to define them in your hosting provider (such as your Vercel project settings).

Learn how to use environment variables in your Remix project.

Environment Variables


This SaaS template uses Tailwind CSS for styling the application.

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

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

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

### Updating the Primary color of your app

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

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

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

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

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


### Dark Mode

Makerkit also ships with a dark theme.

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

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

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

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

## Installing Animations (optional)

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

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

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

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

## Caveats

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

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

Tailwind CSS and Styling



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

The kit supports the following strategies:

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

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

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

### How does Authentication work?

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

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

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

- Simplifying the business logic: for example, checking server-side if a user can access a specific page before rendering that page
- Rendering the user's data server-side by fetching some data from Supabase in
the `loader` function of your Remix routes

### Authentication Strategies

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

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

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

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

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

We will do the following:

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

And the result will be similar to the image below:

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

### Creating Accounts

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

### Requiring Email Verification

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

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

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

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

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

## Emails sent by Supabase

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

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

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

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



After sign-up, users are redirected to the onboarding flow. Here, you can ask users questions, configure their accounts or simply show them around.

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

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

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

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

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

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

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

### What is an "Organization"?

Organizations are groups of users.

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

Users can:

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

### Can I remove this step?

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

Yes, you can follow this guide for [removing the onboarding flow and organizations](/recipes/removing-organizations). It is for the Firebase version, but the same principles apply.


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

Onboarding Flow


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

This involves a couple of steps:

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

### Learning about RLS

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

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

##### How is the data structured?

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

#### Generating the types from the SQL schema

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

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

You can generate the types by running the following command:

```bash
npm run typegen
```

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

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

For example:

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

type Client = SupabaseClient<Database>;
```


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

Database Schema


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

### Routing Structure

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

<Alert type="info">
  The routing structure below has been updated to using the new Remix v2 convention
</Alert>

```txt {16-17}
├── routes
  └── $.tsx
  └── _app.dashboard.tsx
  └── _app.settings._index.tsx
  └── _app.settings.organization._index.tsx
  └── _app.settings.organization.members._index.tsx
  └── _app.settings.organization.members.invite._index.tsx
  └── _app.settings.organization.tsx
  └── _app.settings.profile._index.tsx
  └── _app.settings.profile.authentication.tsx
  └── _app.settings.profile.email.tsx
  └── _app.settings.profile.password.tsx
  └── _app.settings.profile.tsx
  └── _app.settings.subscription._index.tsx
  └── _app.settings.tsx
  └── _app.tasks.$task.tsx
  └── _app.tasks._index.tsx
  └── _app.tsx
  └── _invite.tsx
  └── _site._index.tsx
  └── _site.about.tsx
  └── _site.faq.tsx
  └── _site.pricing.tsx
  └── _site.tsx
  └── admin._index.tsx
  └── admin.organizations.$id.members.tsx
  └── admin.organizations._index.tsx
  └── admin.tsx
  └── admin.users.$id.ban.ts
  └── admin.users.$id.impersonate.tsx
  └── admin.users.$id.reactivate.ts
  └── admin.users.$id.tsx
  └── admin.users._index.tsx
  └── auth.callback.tsx
  └── auth.link.tsx
  └── auth.password-reset.tsx
  └── auth.sign-in.tsx
  └── auth.sign-up.tsx
  └── auth.tsx
  └── auth.verify.tsx
  └── healthcheck.ts
  └── invite.$code.tsx
  └── onboarding._index.tsx
  └── resources.organizations.create.ts
  └── resources.organizations.members.$member.tsx
  └── resources.organizations.transfer-ownership.ts
  └── resources.stripe.checkout.tsx
  └── resources.stripe.portal.ts
  └── resources.stripe.webhook.ts
```

The routes are split in the following way:

1. The website's pages are placed under the prefix `_site`
2. The auth pages are placed under the prefix `_auth`
3. The internal pages (behind auth) pages are placed under the prefix `_app`

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

### Setting the application's Home Page

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

You can update the above by setting the application's home page path at `configuration.paths.appHome`.

### Routing

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

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

1. **List Page**: we create a page `index.tsx`, which is accessible at the path `/tasks`
3. **Task Page**: we create a page `$task.tsx`, which is accessible at the path
`/tasks/<taskID>` where `taskID` is a dynamic variable that refers to the actual ID of the task

```txt
├── routes
  └── _app.tasks._index.tsx
  └── _app.tasks.$task.tsx
```

### Adding Functionalities to your application

To add new functionalities to your application (in our case, tasks management), usually, you'd need the following things:
1. First, we want to define our data model
2. Once we're happy with the data model, we can create our Supabase hooks to
write new tasks and then fetch the ones we created
3. Then, we import and use our hooks within the components
4. Finally, we add the components to the pages

### Adding page links to the Navigation Menu

#### Updating the Top header Navigation

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

```ts
import { Squares2X2Icon, Cog8ToothIcon } from "@heroicons/react/24/outline";

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

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

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

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

The result will be similar to the images below:

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

<Alert type={'warn'}>
  You may need to restart your development server to see the changes, and/or refresh the browser's cache for the changes to be visible.
</Alert>

Learn how to get started developing new features in your app

Routing


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

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

## Fetching a list of tasks

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

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

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

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

type Client = SupabaseClient<Database>;

const TASKS_PAGE_SIZE = 10;

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

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

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

  return query;
}

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

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

## Fetching a single task

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

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

---

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

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

Supabase: Data Fetching


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

#### Creating a Task

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

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

#### Updating a Task

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

We will write another mutation function to update a task:

```ts title="lib/tasks/mutations.ts"
export function updateTask(
  client: Client,
  task: Partial<Task> & { id: number }
) {
  return client
    .from(TASKS_TABLE)
    .update({
      name: task.name,
      done: task.done,
    })
    .match({
      id: task.id,
    })
    .throwOnError();
}
```

#### Deleting a Task

We will write another mutation function to delete a task:

```ts title="lib/tasks/mutations.ts"
export function deleteTask(
  client: Client,
  taskId: number
) {
  return client.from(TASKS_TABLE).delete().match({
    id: taskId
  }).throwOnError();
}
```



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

Supabase: Data Writing

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

Building the Tasks page


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

As you may know, we can define a dynamic path in Remix using the convention `$param` denoted by the `$1` prefix. For example, we can define a dynamic path for the Tasks page by creating a file called `_app.tasks.$task.tsx`. This will create a dynamic path for the Tasks page that will be available at `/tasks/:task`.

## Building the Loader

First - we need to define the loader function for the Task Detail page. The loader function is responsible for fetching the data that will be used by the page.

In this case - we fetch the task data by using the `getTask` query. This query is defined in the `~/lib/tasks/queries` module.

As you can see below, we're able to access the `task` param by using the `args.params.task` property. This is possible because we defined the dynamic path as `_app.tasks.$task.tsx`.

```tsx
export const meta: MetaFunction = ({ data }) => {
  return [
    {
      title: data.task.name,
    },
  ];
};

export async function loader(args: LoaderArgs) {
  const client = getSupabaseServerClient(args.request);
  const taskId = args.params.task;

  const { data: task, error } = await getTask(client, Number(taskId));

  if (!task || error) {
    return throwNotFoundException();
  }

  return json({
    task,
  });
}
```

Don't worry about copying the code above, we will show the full code for the Task Detail page later in this step.

## Building the Action

From this page - we also allow users to update the task data. To do that, we define an action function that will be responsible for updating the task data.

```tsx
export async function action(args: ActionArgs) {
  const client = getSupabaseServerClient(args.request);
  const body = await args.request.json();

  switch (args.request.method) {
    case 'PUT':
      await updateTask(client, body);

      return json({ success: true });
  }

  return throwNotFoundException();
}
```

## Building the Task Detail Container

Before we build the page, we define a client component named `TaskItemContainer` that will be used by the page.

This component will be responsible for rendering the form that will be used to update the task - and also for handling the form submission using the `useFetcher` hook.

The `useFetcher` hook is a hook that is provided by Remix. When called, it will submit the `action` function defined above.

```tsx title="app/dashboard/[organization]/tasks/components/TaskItemContainer.tsx"
function TaskItemContainer({
  task,
}: React.PropsWithChildren<{
  task: Task;
}>) {
  const fetcher = useFetcher();
  const isSubmitting = fetcher.state === 'submitting';

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

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

      fetcher.submit(
        {
          name,
          description,
        },
        {
          method: 'PUT',
          encType: 'application/json',
        },
      );
    },
    [fetcher],
  );

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

        <TextField.Label>
          Name
          <TextField.Input required name={'name'} defaultValue={task.name} />
        </TextField.Label>

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

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

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

## Building the Task Detail page

Now that we have the `TaskItemContainer` component, we can build the Task Detail page.

Below is the full code for the Task Detail page.

```tsx title="app/dashboard/[organization]/tasks/[task]/page.tsx"
import type { MetaFunction } from '@remix-run/react';
import { useFetcher, useLoaderData } from '@remix-run/react';
import type { ActionArgs } from '@remix-run/node';
import { json } from '@remix-run/node';
import type { LoaderArgs } from '@remix-run/server-runtime';
import type { FormEventHandler } from 'react';
import React, { useCallback } from 'react';

import { ChevronLeftIcon, ArrowLeftIcon } from '@heroicons/react/24/outline';

import Heading from '~/core/ui/Heading';
import Button from '~/core/ui/Button';
import { throwNotFoundException } from '~/core/http-exceptions';
import getSupabaseServerClient from '~/core/supabase/server-client';

import AppHeader from '~/components/AppHeader';
import AppContainer from '~/components/AppContainer';

import { getTask } from '~/lib/tasks/queries';
import type Task from '~/lib/tasks/types/task';
import Label from '~/core/ui/Label';
import Textarea from '~/core/ui/Textarea';
import TextField from '~/core/ui/TextField';
import { updateTask } from '~/lib/tasks/mutations';

export const meta: MetaFunction = ({ data }) => {
  return [
    {
      title: data.task.name,
    },
  ];
};

export async function loader(args: LoaderArgs) {
  const client = getSupabaseServerClient(args.request);
  const taskId = args.params.task;

  const { data: task, error } = await getTask(client, Number(taskId));

  if (!task || error) {
    return throwNotFoundException();
  }

  return json({
    task,
  });
}

const TaskPage = () => {
  const data = useLoaderData<typeof loader>();
  const task = data.task as Task;

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

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

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

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

export default TaskPage;

function TaskItemContainer({
  task,
}: React.PropsWithChildren<{
  task: Task;
}>) {
  const fetcher = useFetcher();
  const isSubmitting = fetcher.state === 'submitting';

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

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

      fetcher.submit(
        {
          name,
          description,
        },
        {
          method: 'PUT',
          encType: 'application/json',
        },
      );
    },
    [fetcher],
  );

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

        <TextField.Label>
          Name
          <TextField.Input required name={'name'} defaultValue={task.name} />
        </TextField.Label>

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

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

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

export async function action(args: ActionArgs) {
  const client = getSupabaseServerClient(args.request);
  const body = await args.request.json();

  switch (args.request.method) {
    case 'PUT':
      await updateTask(client, body);

      return json({ success: true });
  }

  return throwNotFoundException();
}

```

---

Perfect, our Tasks App is now complete! 🎉

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

Building the Task Detail page


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

There are many ways to call an API route in Remix:
1. Using the Remix `useSubmit` or `useFetcher` hooks
2. Using the `fetch` API wrapper in Makerkit `useFetcher`
3. Using the `fetch` API directly

As a rule of thumb - it's best to use the `useSubmit` or `useFetcher` hooks whenever possible. It's the Remix way ad closer to the Remix philosophy.

With that said, there are times where the `useFetch` hook can be useful - where `useFetcher` and `useSubmit` may not be as convenient - for example - when you need to await the request using a Promise.

### Calling API functions from the client

API functions in Remix are defined using the special functions `loader` and
`action`.

These functions are defined in the routes.

These functions can be called in
various ways, for example using Remix's `useFetcher`, `useSubmit`, `<Form>`,
or can be called using simple `fetch` calls.

#### Defining global API functions

When the API functions are "standalone" and not tied to a specific page, it
makes sense to prefix them with the `resources` path.

For example, the following code calls the `action` function `owner` from the
file `resources.organizations.members.transfer-ownership.ts`.

##### Using Fetch + React Query
First, we define a function using the utility `useFetch` and React Query's `useMutation` hook.

```tsx
import useFetch from '~/core/hooks/use-fetch';
import { useMutation } from '@tanstack/react-query';

function useTransferOrganizationOwnership() {
  const transferOrganizationFetch = useFetch<{ membershipId: number }>(
    `/resources/organizations/members/transfer-ownership`,
    'PUT'
  );

  return useMutation((membershipId: number) => {
    return transferOrganizationFetch({ membershipId });
  });
}

export default useTransferOrganizationOwnership;
```

Then, we can define an `action` function in the file `resources.organizations.ts`.

```tsx
export async function action(args: ActionArgs) {
  const req = args.request;

  // logic to transfer ownership
}
```

#### Using useFetcher and useSubmit

Alternatively, we can use the Remix functions `useSubmit` or `useFetcher` to call the same endpoint.

This is more conventional to Remix, so you may prefer this latter approach.

```tsx {2,5}
function useTransferOrganizationOwnership() {
  const submit = useSubmit();

  return useCallback((membershipId: number) => {
    return submit({
      data: { membershipId: membershipId.toString() },
      action: `/resources/organizations/members/transfer-ownership`,
      method: `put`
    });
  });
}

export default useTransferOrganizationOwnership;
```

### Submitting Actions using JSON

It's important to notice that in this case the payload is sent as `FormData`, not as `JSON` - but you can specify the `encType` parameter to change this behavior.

```tsx
const fetcher = useFetcher();

<button onClick={() => {
  fetcher.submit(data, {
    method: 'POST',
    encType: 'application/json'
  })
}}>Submit</button>
```

```tsx
export async function action(args: ActionArgs) {
  const req = args.request;
  const body = await req.json();

  // ...
}
```

#### Sending the CSRF Token

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

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

```tsx
const getCsrfToken = useGetCsrfToken();
const csrfToken = getCsrfToken();

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

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

### CSRF Token check

We must pass a `CSRF token` when using POST requests to prevent malicious attacks. To do so, we use the pipe `withCsrfToken`.

1. The CSRF token is generated when the page is server-rendered
2. The CSRF token is stored in a `meta` tag
3. The CSRF token is sent to an HTTP POST request automatically when using
the `useFetch` hook
4. This function will throw an error when the token is invalid

By using this function, **we ensure all the following functions will not be executed unless the token is valid**.

```tsx
export const action: ActionFunction = async ({ request }) => {
  await withCsrf(request);
}
```

### Sending CSRF Token using useFetcher and useSubmit

When using `useSubmit` and `useFetcher` - you must pass the CSRF token manually:

```tsx
const submit = useSubmit();
const csrfToken = useCsrfToken();

submit({ csrfToken }, {
  method: 'POST',
  encType: 'application/json'
})
```

We can then validate it using the `withCsrf` function:

```tsx
export const action: ActionFunction = async ({ request }) => {
  const body = await request.json();
  await withCsrf(request, () => body.csrfToken);
}
```

### API Logging

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

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

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

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

  await performAction();

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

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


The best practices to write API routes in your Remix Supabase application


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

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

#### Using the components AppHeader and AppContainer

These components are used to wrap the content of the pages. They are responsible for displaying the header and the container of the page.
```tsx
function DashboardPage() {
  return (
    <>
      <AppHeader>
        <span className={'flex space-x-2'}>
          <Squares2X2Icon className="w-6" />

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

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

## Guarding Application Pages for Authenticated Users

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

```tsx
import { redirect } from "@remix-run/node";

export async function loader() {
  const session = await requireSession();

  if (!session) {
    return redirect("/auth/sign-in");
  }

  return {
    session,
  };
}
```

## Using Dynamic Parameters

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

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

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

You can access the `organization` and `project` parameters from the page's `loader` function.

```tsx
import type { LoaderArgs } from '@remix-run/node';

export async function loader(args: LoaderArgs) {
  const organization = args.params.organization;
  const project = args.params.project;

  // ...
}
```

## Using Search Parameters

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

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

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

You can access the `page` and `limit` parameters from the page's `loader` function.

```tsx
import type { LoaderArgs } from '@remix-run/node';

export async function loader(args: LoaderArgs) {
  const params = new URL(args.request.url).searchParams;
  const page = params.get('page');
  const limit = params.get('limit');

  // ...
}
```


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


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

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

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

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

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

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

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

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

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

export const action: ActionFunction = async ({ request }) => {
  try {
     // we can safely use data with the interface Body
    const schema = getBodySchema();
    const body = await request.json();
    const { displayName, email } = schema.parse(body);

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

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

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

API Routes Validation


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

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

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

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

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

### Adding new languages

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

Adding a new language is very simple:

1. **Translation Files**: First, we need to create a new folder, such as `/public/locales/es`, and then copy over the files from the English version and start translating files.
2. **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 `supportedLanguages` array.

The configuration will look like the below:

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

#### Setting the default Locale

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

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

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


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


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

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

## Client-Side Functions

### Supabase Hooks

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

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

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

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

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

#### Server Side Supabase Clients

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

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

### Makerkit Hooks

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

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

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

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

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

  return organization?.name;
}
```

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

You can customize this hook to fit your needs.

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

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

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

  if (!status) {
    return false;
  }

  return ACTIVE_STATUSES.includes(status);
}

export default useIsSubscriptionActive;
```

## Server-Side Functions

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

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

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

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

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

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

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

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

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

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

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

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

It returns a Supabase Auth `Session` instance:

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

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

  //
}
```

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

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

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

And returns the organization data:

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

Usage:

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

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

  //
}
```

Using a user ID:

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

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

Using an organization ID:

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

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

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

Functions you need to know

Adding pages to the Marketing Site is easy.

The marketing/site pages are placed under the prefix `_site`
directory, and are part of the `site` layout.

```tsx title="app/routes/_site.about.tsx"
import type { MetaFunction } from '@remix-run/node';

import configuration from '~/configuration';
import Hero from '~/core/ui/Hero';
import Container from '~/core/ui/Container';
import SubHeading from '~/core/ui/SubHeading';

export const meta: MetaFunction = () => {
  return {
    title: `About - ${configuration.site.siteName}`,
  };
};

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

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

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

export default About;
```

### Adding pages to the navigation menu

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

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

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

The menu is defined in the render function:

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

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

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

And then we update the menu:

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

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

Adding pages to the Marketing Site


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

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

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


Learn how to deploy your Remix Supabase app to your hosting provider.

Deploying to Production


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

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

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

Unfortunately, you may need to resolve eventual conflicts.

### Any questions?

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

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

Updating to the latest version

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

Getting Started


MakerKit is **the 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 [Radix UI](https://radix-ui.
com)
- **SSR-compatible Authentication flow**, including 3rd-party providers (Google,
Facebook, Twitter, GitHub, etc.)

### Template Features

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

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

### Debugging and Testing

Never waste time chasing bugs again.

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

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

### After you buy

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

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

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

MakerKit has plenty of resources for using both 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, Radix UI, Typescript and Cypress to build wonderful SaaS applications

The technologies that make up a MakerKit application


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

### Requirements

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

- Node.js
- Git
- Docker

### Remix Versions

The current main uses Remix v2.

### Cloning the repository

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

```
git clone 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. Adding the remote to your own Git repository (if you haven't created a Git repository yet, you can do it later on)
3. Adding the original Makerkit repository as "upstream" so we can fetch updates from the main repository:

```
cd my-saas
git remote rm origin
git remote add origin <your-git-repository>
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
```

If it doesn't work, try with:

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

## About this Documentation

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

## Install and Run Docker

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

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

### Adding the environment variables file

The kit comes with a template of what your `.env` file should look like named `.env.template`.

**Before you continue**: rename `.env.template` to `.env`, or copy its contents to `.env`.

**This file won't be committed to git**. When you deploy your production app, ensure you add the environment variables using your CI/Service.

NB: Remix does not use the `.env` file when bundling the application in production mode.

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

```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=****************************************************
```

### Building the Contentlayer (Blog and Documentation) documents

The codebase expects the Contentlayer documents to be built before running the Remix server. To do so, run the following command:

```
npm run contentlayer:build
```

If you want to build the documents every time you save a file, you can run the following command:

```
npm run contentlayer:watch
```

Running the `contentlayer:watch` command is the recommended way to work with the Contentlayer during development.

### 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 title=".env.development"
STRIPE_WEBHOOKS_SECRET=<PASTE_KEY_HERE>
```


#### Signing In for the first time

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

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

#### Email Confirmations

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




Learn how to run a Remix and Supabase MakerKit application

How to run a Remix and Supabase MakerKit application


In this section - we will take an overview of the Remix Supabase codebase. We will look at the different folders and files and what they do.

## The "supabase" folder

This is the folder generated by Supabase when initiating a new project. In this folder, Supabase stores the local configuration `config.toml`, the database migrations, the seed file and the tests.

Most importantly, you will be more interested in the `migrations` folder. This folder contains the database migrations that seed your database with the necessary tables and data when starting the Supabase server.

It's here where you will be editing or adding new migrations to your database.

## The "public" folder

In this folder you can store static files that you want to serve from your application. For example, you can store images, fonts, etc. in this folder.

## The "app" folder

The `app` folder contains the various folders and files:
- `core`
- `lib`
- `components`
- `routes`
- `i18n`
- `configuration.ts`
- `database.types.ts`

### The "core" folder

The core folder contains the building blocks of your application, and the core utilities that you will use throughout your application.

It does not contain any business logic, but rather contains the building blocks that you will use to build your business logic.

#### Reusable components

The `core/ui` folder contains the reusable components that you will use throughout your application.

It's best to place here components not related to your app's business logic. For example, you can place here components like `Button`, `Input`, `Select`, etc.

### The "lib" folder

The `lib` folder contains business-logic related code - and it's here where you will be writing most of your code.

### The "components" folder

The `components` folder contains the various components that you will use throughout your application.

For example, here you can add components such as `UsersList`, `UserDetails`, `UserForm`, etc. If they relate to a feature, this is a good place to put them.

### The "routes" folder

This is the Remix routes folder. It contains the various routes that your application will have.

### The "i18n" folder

This folder contains the settings and utilities for internationalization in your application.

### The "configuration.ts" file

This file contains the configuration for your application. It's here where you will configure your auth providers, your application's name, etc.

### The "database.types.ts" file

This file is automatically generated by Supabase. It contains the types for your database tables and we use it to add type-safety to our database queries.

Learn how to navigate the Remix Supabase codebase - so you can understand and extend the codebase to your needs.

Tutorials

Environment Variables

Learn how to use environment variables in your Remix project.

Define your environment variables in your hosting provider

Define your environment variables in your hosting provider

Subscribe to our Newsletter