Tutorials

Building an AI Writer SaaS with Next.js and Supabase


I am super excited to announce the **Data Loader SDK for Supabase**, a new [open source project](https://github.com/makerkit/makerkit) that I have been working on for the past few weeks.

The Data Loader SDK is a declarative, type-safe set of utilities to load data from your Supabase database.

It's an external package that you can use in any Next.js or Remix project, and it's built on top of the Supabase JS Client. It's not limited to Makerkit's SaaS Kits.

## Why?

Generally speaking - to remove boilerplate and make it easier to load data from your Supabase database. The SDK is built on top of the Supabase JS Client and uses the Supabase JS Client under the hood.

## Installation

You can use the Data Loader SDK in any Next.js or Remix project. Yes - it's not limited to Makerkit's SaaS Kits.

To install it for Next.js, run the following command:

```bash
npm install @makerkit/data-loader-supabase-next.js
```

or if you use Remix:

```bash
npm install @makerkit/data-loader-supabase-remix
```

## Usage

To use the Data Loader SDK, you have a variety of options.

1. **JSX**: you can use it as a component, importing the components `ServerDataLoader` and `ClientDataLoader` from the SDK. The `ServerDataLoader` component can be used for Server Components (RSC), while the `ClientDataLoader` component will load data in Client Components. The Remix version only provides the `ClientDataLoader` component, as Remix doesn't support Server Components.
2. **Hooks**: you can use the `useSupabaseQuery` to load data in your components. The Next.js uses `SWR` under the hood, while the Remix version uses TanStack's `useQuery` hook.
3. **Directly**: you can use the `fetchDataFromSupabase` function from the core library to load data directly where you need it: for example, in API Routes, Server Actions, Remix Loaders/Actions, a Middleware, and so on.

## Examples

### Loading Supabase Data from a Server Component

In the example below, we want to pull data from a Supabase Database from within a Next.js Server Component. The data will be entirely fetched and rendered on the server.

Here's what we want to do:
1. Import the `ServerDataLoader` component from the Data Loader SDK.
2. Import the `getSupabaseServerComponentClient` function to load the Supabase Client to be used in the Server Component. Ideally, you have provided the Database interface - so that the Loader can infer the types of the data that you are loading.
3. Pass the `client` prop to the `ServerDataLoader` component.
4. Pass the `table` prop to the `ServerDataLoader` component. In our case, we want to load data from the `organizations` table.
5. Define the fields that you want to load from the table using the `select` prop. In our case, we want to load the `id` and `name` fields.
6. Pass the fetched data to the `data` prop of the `DataTable` component - which displays the data in a table.

```tsx
import { ServerDataLoader } from '@makerkit/data-loader-supabase-nextjs';

import getSupabaseServerComponentClient from '~/core/supabase/server-component-client';
import DataTable from '~/core/ui/DataTable';

const OrganizationsTable = () => {
  const client = getSupabaseServerComponentClient();

  return (
    <ServerDataLoader
      client={client}
      table="organizations"
      select={['id', 'name']}
    >
      {({ data, count, pageSize, pageCount }) => {
        return (
          <DataTable
            data={data}
            count={count}
            pageSize={pageSize}
            pageCount={pageCount}
            columns={[
              {
                header: 'ID',
                accessorKey: 'id',
              },
              {
                header: 'Name',
                accessorKey: 'name',
              },
            ]}
          />
        );
      }}
    </ServerDataLoader>
  );
};
```

DX Goodies:

1. **Type Safety**: the `select` prop is type-safe. If you try to select a field that doesn't exist in the table, you will get a TypeScript error.
2. **Intellisense**: the `select` prop provides intellisense for the fields that you can select from the table. This depends on the `client` property: you must pass the Database types to the Supabase Client to get intellisense.
3. **Server-Side Rendering**: the data is fetched and rendered on the server.
4. **Pagination**: the `ServerDataLoader` component provides pagination out of the box. You can use the `count`, `pageSize`, and `pageCount` properties to display pagination controls. In Makerkit's `DataTable` component, the pagination will automatically handled for you.

As you can see in the below image, the IDE will provide intellisense for the fields that you can select from the table.

<Image src="/assets/images/posts/data-loader-sdk-tasks-example.webp" alt="Intellisense for the select prop" width={1048}
       height={1080} />

### Loading Supabase Data from a Client Component

In the example below, we want to pull data from a Supabase Database from within a Next.js Client Component. The data will be fetched on the client.

Generally speaking, the two components are very similar. The main difference is that we use the `ClientDataLoader` component we need to handle the `loading` state of the component - since the data is fetched on the client and is asynchronously loaded.

Below is an example of how you can use the `ClientDataLoader` component to load data from a Supabase Database from within a Next.js Server Component.
The Server component passes the `page` query parameter to the `ClientDataLoader`, which is used to load the page of data that we want to display.

```tsx
import useSupabase from '~/core/supabase/use-supabase';
import { ClientDataLoader } from '@makerkit/data-loader-supabase-nextjs';

interface SearchParams {
  page: string;
}

const OrganizationsTable = ({
  searchParams,
}: {
  searchParams: SearchParams;
}) => {
  const client = useSupabase();
  const page = Number(searchParams.page) || 1;

  return (
    <ClientDataLoader
      client={client}
      table="organizations"
      page={page} // the page to fetch
      select="*" // all the columns - can be omitted
      limit={10} // retrieve 10 organizations per page
    >
      {({ result, isLoading }) => {
        const { data, count, pageSize, pageCount } = result;

        if (isLoading) {
          return <span>Loading...</span>;
        }

        return (
          <DataTable
            data={data}
            count={count}
            pageSize={pageSize}
            pageCount={pageCount}
            columns={[
              {
                header: 'ID',
                accessorKey: 'id',
              },
              {
                header: 'Name',
                accessorKey: 'name',
              },
            ]}
          />
        );
      }}
    </ClientDataLoader>
  );
};
```

### Loading Supabase Data from a Hook

In the example below, we want to pull data from a Supabase Database from within a Next.js Client Component using a React Hook `useSupabaseQ

Let's define a React Hook that we can use to load data from the `organizations` table.

```tsx
import useSupabase from '~/core/supabase/use-supabase';
import { useSupabaseQuery } from '@makerkit/data-loader-supabase-nextjs';

export function useFetchOrganization() {
  const client = useSupabase();

  return useSupabaseQuery({
    client,
    table: 'organizations',
    select: ['id', 'name'],
  });
}
```

We can then use the `useFetchOrganization` hook in our components to load the data.

```tsx
import { useFetchOrganization } from '~/hooks/use-fetch-organization';

const OrganizationsTable = () => {
  const { result, isLoading } = useFetchOrganization();
  const { data, count, pageSize, pageCount } = result;

  if (isLoading) {
    return <span>Loading...</span>;
  }

  return (
    <DataTable
      data={data}
      count={count}
      pageSize={pageSize}
      pageCount={pageCount}
      columns={[
        {
          header: 'ID',
          accessorKey: 'id',
        },
        {
          header: 'Name',
          accessorKey: 'name',
        },
      ]}
    />
  );
};
```

### Loading Supabase Data Directly

Finally, you can also fetch data from anywhere by using the `fetchDataFromSupabase` function from the core library `@makerkit/data-loader-supabase-core`.

In the example below, we fetch the data from a Next.js API Route. We also pass the `textSearch` operator to the `name` field, which will perform a full-text search on the `name` field.

```tsx
import { NextResponse } from 'next/server';
import { fetchDataFromSupabase } from '@makerkit/data-loader-supabase-core';
import getSupabaseRouteHandlerClient from '~/core/supabase/route-handler-client';

export async function GET() {
  const client = getSupabaseRouteHandlerClient();

  const { data, count, pageSize, pageCount } = await fetchDataFromSupabase({
    client,
    table: 'organizations',
    where: {
      name: {
        textSearch: `'makerkit'`,
      },
    },
  });

  return NextResponse.json({
    data,
    count,
    pageSize,
    pageCount,
  });
}
```

### Fetching a single Object from Supabase

To fetch a single item, instead of a list of items, you can use the `single` prop. This will return a single object instead of an array of objects.

```tsx
import { ServerDataLoader } from '@makerkit/data-loader-supabase-nextjs';

import getSupabaseServerComponentClient from '~/core/supabase/server-component-client';

const Organization = () => {
  const client = getSupabaseServerComponentClient();

  return (
    <ServerDataLoader
      client={client}
      table="organizations"
      select={['id', 'name']}
      single
    >
      {({ data }) => {
        return (
          <div>
            <h1>{data.name}</h1>
          </div>
        );
      }}
    </ServerDataLoader>
  );
};
```

The `data` prop will be a single object instead of an array of objects.

### Converting the data to camelCase

As it's commonly done in Postgres, the column names are in snake_case. If you want to convert the column names to camelCase (as it is more commonly done in Javascript), you can use the `camelCase` prop.

```tsx
import { ServerDataLoader } from '@makerkit/data-loader-supabase-nextjs';

import getSupabaseServerComponentClient from '~/core/supabase/server-component-client';

const Task = () => {
  const client = getSupabaseServerComponentClient();

  return (
    <ServerDataLoader
      client={client}
      table="tasks"
      select={['name', 'created_at', 'updated_at']}
      single
      camelCase
    >
      {({ data }) => {
        // data will be in camelCase
        // {
        //   id: '...',
        //   createdAt: '...',
        //   updatedAt: '...',
        // }
        return (
          <div>
            <h1>{data.name} - {data.createdAt}</h1>
          </div>
        );
      }}
    </ServerDataLoader>
  );
};
```

### Passing the SWR or React Query options

When fetching data using the `ClientDataLoader` or the `useSupabaseQuery` hook, you can pass the `config` prop to the component. These props will be passed to the `SWR` or `React Query` hooks under the hood.

```tsx
import { ClientDataLoader } from '@makerkit/data-loader-supabase-nextjs';
import useSupabase from '~/core/supabase/use-supabase';

const OrganizationsTable = () => {
  const client = useSupabase();

  return (
    <ClientDataLoader
      client={client}
      table="organizations"
      select={['id', 'name']}
      config={{
        refreshWhenOffline: false,
        revalidateOnMount: false,
      }}
    >
      {({ data }) => {
        return (
          <div>
            <h1>{data.name}</h1>
          </div>
        );
      }}
    </ClientDataLoader>
  );
};
```

You can do the same using the `useSupabaseQuery` hook.

```tsx
import { useSupabaseQuery } from '@makerkit/data-loader-supabase-nextjs';
import useSupabase from '~/core/supabase/use-supabase';

function useFetchOrganization() {
  const client = useSupabase();

  return useSupabaseQuery({
    client,
    table: 'organizations',
    select: ['id', 'name'],
    config: {
      refreshWhenOffline: false,
      revalidateOnMount: false,
    },
  });
}
```

This allows you to customize the behavior of the `SWR` or `React Query` hooks - for example, you can disable the `revalidateOnMount` option to prevent the data from being fetched again when the component is mounted.

## Conclusion

I hope you enjoyed this announcement. I am super excited about this new project, and I hope you will find it useful.

You can use it **today** in your Next.js or Remix projects. It's not limited to Makerkit's SaaS Kits - so feel free to use it in any project.

If you have any questions, feel free to reach out to me on our Discord server.

Happy coding!

Announcing the Data Loader SDK for Supabase

Adding AI capabilities to your Next.js SaaS with Supabase and HuggingFace


It's very common for any SaaS application to need to store API keys, tokens, and other sensitive information. There are various alternatives to do so practically and securely, but you're likely making some tradeoffs with each approach.

1. **Manually encrypting secrets in your DB**: One of the approaches can be to encrypt the secrets and store them in your database. This is a good approach, but you'll need to manage the encryption and decryption of the secrets. You'll also need to manage the encryption keys and make sure they're secure.
2. **Using external services**: Another approach is to use an external Secrets Manager like AWS Secrets Manager or Hashicorp Vault. This is a great approach, with the added complexity of managing another service, and the cost of the service itself.

In this tutorial I introduce Supabase Vault, **an alternative approach to storing secrets in your Postgres database, which is both secure and cost-effective**. Supabase Vault is a Postgres extension that allows you to store secrets in your database. This is a great way to store API keys, tokens, and other sensitive information.

To make working with Supabase Vault, **we will be defining functions to store and retrieve secrets from the Vault that we can easily execute using the Supabase SDK**. We will create simple SQL functions to store and retrieve secrets from Supabase Vault, and we will use these functions to store and retrieve our API keys.

While in this post we focus on DX, if you want to know more about the nitty and gritty of Supabase Vault, you can read the [official documentation](https://supabase.com/docs/guides/database/vault).

## Prerequisites

Before we get started, you'll need to have a Supabase project. If you don't have one, you can create one for free at [supabase.io](https://supabase.io).

### Enable the Vault extension

Once you have your Supabase project, you'll need to enable the Vault extension. You can do this by going to the SQL editor and running the following query:

```sql
create extension vault with schema vault;
```

This is pretty much all you need to do to enable the Vault extension.

Now that we have the Vault extension enabled, we can create the functions to store, retrieve and delete secrets from the Vault.

## Create the function to insert secrets into Supabase Vault

The first function we'll create is the function to insert secrets into the Vault. This function will take two parameters, the key and the value of the secret. The key will be the name of the secret, and the value will be the actual secret.

```sql
create or replace function insert_secret(name text, secret text)
returns uuid
language plpgsql
security definer
set search_path = public
as $$
begin
  if current_setting('role') != 'service_role' then
    raise exception 'authentication required';
  end if;

  return vault.create_secret(secret, name);
end;
$$;
```

Run the following command to update your database types, so that you can use the function in your queries:

```
supabase gen types typescript --local > app/database.types.t
```

NB: Tweak the path to the generated types file to match your project structure.

### Inserting a secret using the Supabase SDK

Now that we have the function to insert secrets into the Vault, we can use it in our Supabase project. We'll use the Supabase SDK to insert the secret into the Vault using an RPC call. We assume you can create a Supabase client instance using the function `createSupabaseClient`.

The RPC call to insert a secret into the Vault will look like this:

```ts
function insertSecret(name: string, secret: string) {
  const client = createSupabaseClient();

  client.rpc('insert_secret', {
    name,
    secre,
  });
}
```

As you can see, we're passing the name and the secret to the RPC call. The `name` parameter will be the name of the secret, and the `secret` parameter will be the actual secret.

You can now use the `insertSecret` function to insert secrets into the Vault.

Assuming you're storing a password or an API Key, you can use the `insertSecret` function like this:

```ts
export async function storeOpenAiApiKey(
  userId: string,
  apiKey: string
) {
  return insertSecret(
    buildApiKeyName(userId), apiKey
  );
}

function buildApiKeyName(userId: string) {
  return `openai_api_key_${userId}`;
}
```

Remember to always build a unique name for your secrets - for example, by adding the user ID (or some other unique identifier) to the name of the secret.

## Reading a secret using the Supabase SDK

First, we want to define the SQL function in our Supabase project. The function takes a `secret_name` parameter that allows us to query the Vault for the secret.

```sql
create function read_secret(secret_name text)
returns text
language plpgsql
security definer set search_path = public
as $$
declare
  secret text;
begin
  if current_setting('role') != 'service_role' then
    raise exception 'authentication required';
  end if;

  select decrypted_secret from vault.decrypted_secrets where name =
  secret_name into secret;
  return secret;
end;
$$;
```

Now that we have the function to insert secrets into the Vault, we can use it in our Supabase project. We'll use the Supabase SDK to insert the secret into the Vault using an RPC call.

### Reading secrets using the Supabase Client

To read a secret from the Vault, we'll use the `read_secret` function. This function takes one parameter, the name of the secret.

```tsx
function getSecret(
  secretName: string
) {
  const client = createSupabaseClient();

  return client.rpc('read_secret', {
    secret_name: secretName,
  });
}
```

Now we can use this function to read secrets from the Vault. For example, if we want to read the OpenAI API key, we can do it like this:

```tsx
export async function getOpenAiApiKey(
  userId: string
) {
  return getSecret(
    buildApiKeyName(userId)
  );
}
```

You can now use the `getOpenAiApiKey` function to read secrets from the Vault.

```tsx
import { Configuration, OpenAIApi } from 'openai-edge';

function getOpenAIClient(apiKey: string) {
  const configuration = new Configuration({ apiKey });

  return new OpenAIApi(configuration);
}

async function getCompletions(
  userId: string,
  prompt: string
) {
  const apiKey = await getOpenAiApiKey(userId);
  const client = getOpenAIClient(apiKey);

  return client.createChatCompletion({
    model: 'gpt-3.5-turbo',
    messages: [
      {
      role: 'user',
      content: prompt,
    },
    ],
    max_tokens: 180,
    temperature: 1,
  });
}
```

## Deleting a secret using the Supabase SDK

Finally, we want to make sure we can delete secrets from the Vault. This is useful if we want to revoke access to a secret, or if we want to delete a secret for any other reason.

First, we want to define the SQL function in our Supabase project. The function takes a `secret_name` parameter that allows us to query the Vault for the secret.

```sql
create function delete_secret(secret_name text)
returns text
language plpgsql
security definer set search_path = public
as $$
begin
  if current_setting('role') != 'service_role' then
    raise exception 'authentication required';
  end if;

  return delete from vault.decrypted_secrets where name = secret_name;
end;
$$;
```

Now that we have the function to insert secrets into the Vault, we can use it in our Supabase project. We'll use the Supabase SDK to insert the secret into the Vault using an RPC call.

After adding this function, remember to update your database types, so that you can use the function in your queries.

### Deleting secrets using the Supabase Client

To delete a secret from the Vault, we'll use the `delete_secret` function. This function takes one parameter, the name of the secret.

```tsx
export function deleteSecret(
  secretName: string
) {
  const client = createSupabaseClient();

  return client.rpc('delete_secret', {
    secret_name: secretName,
  });
}
```

Now we can use this function to delete secrets from the Vault. For example, if we want to delete the OpenAI API key, we can do it like this:

```tsx
export async function deleteOpenAiApiKey(
  userId: string
) {
  return deleteSecret(
    buildApiKeyName(userId)
  );
}
```

## Conclusion

In this tutorial we've learned how to use Supabase Vault to store secrets in our Postgres database. We've created functions to insert, read and delete secrets from the Vault, and we've used these functions to store and retrieve our API keys.

To learn more about Supabase Vault, check out the [Supabase official documentation](https://supabase.com/docs/guides/database/vault).

Using Supabase Vault to store secrets

Changelog


I'm excited to announce that Makerkit is adding support for Multi-Factor Authentication (MFA) the Supabase kits. This is a sneak peek to our coming feature.

## What is MFA?

Multi-Factor Authentication (MFA) is a method of authentication that requires more than one piece of evidence to verify the user's identity. It is a way to add an extra layer of security for your users' accounts.

## Should you add MFA to your app?

If you're building an app that requires a high level of security, then you should definitely consider adding MFA to your app. For example, if you're building an app that requires users to manage their finances, then you should definitely add MFA to your app.

Your users will feel more secure knowing that their accounts are protected by MFA, and it can be a potential differentiator for your app. I don't see a reason not to offer this functionality to your users.

## How does MFA work?

Supabase allows us to use TOPT (Time-based One-time Password) to generate a one-time password (OTP) that the user can use to login to their account using their second authentication factor.

## Supabase MFA in Practice

### Step 1. Users will enroll an authentication factor (e.g. Google Authenticator)

The first step for your users is to enroll a new authentication factor using an Authenticator app (such as Google Authenticator or Authy).

1. The first thing they are required to do is to specify a name for their new authentication factor: Supabase supports up to 10 factors (more than enough for sure!). This name will be used to identify the authentication factor in the Authenticator app, and will help users remember which factor they are using.
2. Then, they're required to scan the QR code with the authenticator app. This will generate a secret key that will be used to generate the OTP.
3. After confirming the one-time code generated by the authenticator app, the user will be able to use their new authentication factor to login to their account.

<Video src="/assets/images/posts/mfa-setup.mp4" />

### Step 2. Users will login to their account using their email and password

After logging in, we will check if users have enrolled any MFA factor. According to Supabase, this rarely uses the network and it's a very fast check. After logging in using the first authentication factor, the users' assurance level is `aal1`.

If users are required to use MFA, then we will redirect them to the MFA page. This page will prompt them to select a factor: for example, a factor enrolled using a work smartphone. If only one factor is enrolled, then it will be automatically selected.

Then, they will be required to enter the OTP generated by the authenticator app for that factor. If the OTP is correct, then the user will be logged in to their account. Their assurance level is upgraded to `aal2`.

<Video src="/assets/images/posts/mfa-verify.mp4" />

## Conclusion

I'm excited to add this feature to our kits. I think it's a great way to add an extra layer of security to your app. I hope you enjoyed this sneak peek to our coming feature. If you have any questions, feel free to reach out on our Discord server.

Announcing support for Multi-Factor Authentication (MFA) with Supabase


As you may have seen, we are working on a new SaaS kit based on Supabase and Next.js 13 using React Server Components and the new app directory. We are excited to share a behind-the-scenes look at how we built the kit.

## A quick recap: what is a SaaS kit?

Makerkit's kits are a collection of templates that you can use to build your own SaaS products. 

The goal of the kits is to provide the building blocks that you need to build your own SaaS product and to help you get started quickly, such as a landing page, authentication, Stripe payments, emails, multi-tenancy architecture based on organizations, user invites, and more.

The kits are built using the latest technologies and are designed to be easy to customize and extend to fit your needs.

## The Supabase and Next.js RSC SaaS kit

The Supabase and Next.js RSC SaaS kit is a new kit that we are working on. It is based on Supabase, Next.js 13 React Server Components and the new app directory.

### A rewrite of the Supabase and Remix SaaS kit

It's mostly a rewrite of the Supabase and Remix SaaS kit so the two kits are very similar. While competing, the two frameworks are extremely similar, and the migration was mostly a matter of changing the framework-specific code.

In short, both frameworks are great and you can't go wrong with either one. It's important to remember that while Remix is production-ready, (at the time of writing) the Next.js app directory is still in beta.

### The Next.js app directory is in beta

Therefore, this kit is going to be a beta kit as well until the Next.js app directory is out of beta.

## Enter React Server Components

The most striking difference that you will find in the new kit is the use of React Server Components. 

The new Next.js app directory leverages React Server Components by default: Server components are rendered on the server and then sent to the client as a serialized stream. 

What the above means is that the client can render the component **without having to download the JavaScript bundle**: as you can imagine, this allows Next.js to deliver a much faster initial page load.

### Did you notice performance gains?

Generally speaking, yes. 

But the performance gains don't come for free: your components need to be written in a way that allows them to be rendered on the server, which means they will mostly be data-fetching and rendering components, and no interactivity. 

Interactive components (client components) will be rendered using SSR and hydrate on the client just like you're used to the traditional Next.js `/pages` directory.

When you're able to write your components in a way that allows them to be rendered on the server, combined with carefully written `laoding.tsx` loading handlers, you can **take advantage of the performance gains** that server components unlock and provide a **much smoother user experience** than possible today.

## The new Next.js app directory

The new Makerkit app directory will look like the following tree:

```
- app
  - (app)
    - components
    - dashboard
      - page.tsx
    - settings
      - organization
        - page.tsx
      - profile
        - page.tsx
      - subscription
        - page.tsx
    - layout.tsx
    - loading.tsx
  - (site)
    - about
      - page.tsx
    - faq
      - page.tsx
    - pricing
      - page.tsx
    - layout.tsx
    - loading.tsx
    - page.tsx
  - api
    - organizations
      - route.ts
    - stripe
      - checkout
        - route.ts
  - auth
    - components
    - password-reset
      - page.tsx
    - sign-in
      - page.tsx
    - sign-up
      - page.tsx
    - layout.tsx
    - loading.tsx
  - invite
    - [code]
    - components
    - layout.tsx
  - onboarding
    - page.tsx
  - components.css
  - globals.css
  - layout.tsx
  - loading.tsx
```

If you're not familiar with the Next.js app directory, here is a quick overview:

- pages are defined using the special filename `page.tsx`
- layouts are defined using the special filename `layout.tsx`
- loading handlers are defined using the special filename `loading.tsx`
- directories will create a new route, for example, `app/dashboard` will create the route `/app/dashboard`
- directories using parenthesis are "pathless", .e.g. `(app)` will not create the route `/app`, but will start from the root of the app directory, for example, `(app)/dashboard` will create the route `/dashboard`. The same goes for `(site)`

### Pathless directories

Pathless directories are useful for defining routes that are not part of your app: for example, the `(site)` directory is used to define the routes for your landing page, pricing page, and more. Instead, the `app` directory is used to define the routes for your app, i.e. the ones behind authentication.

### Data-Fetching Layouts

What makes these particularly useful is the fact we can define data-fetching layouts that can fetch the data that is common to the pages in the directory: for example, it may not be useful to fetch the current organization in the `site` pages, but it is useful to fetch the current organization in the `app` pages.

Or, for example, we want to ensure that logged-in users can't access the `auth` pages, but we don't want to do the same for the `app` pages. By using layouts in such a way that we can control both data-fetching and authentication, we can write our pages in a way that is more declarative and easier to reason about.

## Co-locating components

Another interesting feature of the Next.js app directory is the ability to co-locate components with your pages. As you can see, we define the directory `components` close to where they're used, such as near the `auth` pages. 

In this way, we can easily see which components are used by which pages, and we can easily move them around if we need to.

Given we have `shared` components, we can also define a `components` directory at the root of the app directory, which will be shared across all pages.

## The good parts of the Next.js app directory

The Next.js app directory is a great way to organize your Next.js app. In fact, I quite enjoyed the experience of using it. 

### Layouts

Layouts allow us to define components that wrap your pages and provide a consistent look and feel across your app.

Additionally, layouts also help you to fetch data that is common to all pages in your app, such as the current user, the current organization, and more.

#### Data loading

We can use Layouts for fetching data that is common to all pages in its directory. For example, we can fetch the current user in the `auth` directory, and we can fetch the current organization in the `app` directory, and so on.

In Makerkit, we define "data loaders" such as `loadAppData` and `loadAuthData` that are used to fetch the data that is common to all pages in the `app` and `auth` directories, respectively.

These also perform some validation such as ensuring that the user is authenticated and that the user is part of the organization, and so on. In such cases, we define a `redirect` property that tells the layouts not to proceed and redirect somewhere instead.

Let's see the loader for the authentication pages:

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

const loadAuthPageData = async () => {
  try {
    const client = getSupabaseServerClient();

    const {
      data: { session },
    } = await client.auth.getSession();

    if (session) {
      return {
        redirect: true,
        destination: configuration.paths.appHome,
      };
    }

    return {};
  } catch (e) {
    return {};
  }
};

export default loadAuthPageData;
```

Now, let's use the loader above in the `auth` layout:

```tsx
import { use } from 'react';
import { redirect } from 'next/navigation';

import loadAuthPageData from '~/lib/server/loaders/load-auth-page-data';
import Logo from '~/core/ui/Logo';
import I18nProvider from '~/i18n/I18nProvider';

function AuthLayout({ children }: React.PropsWithChildren) {
  const data = use(loadAuthPageData());

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

  return (
    <I18nProvider>
      <div
        className={
          'flex h-screen flex-col items-center justify-center space-y-4 md:space-y-8 lg:bg-gray-50 dark:lg:bg-black-700'
        }
      >
        <div>
          <Logo />

          {children}
        </div>
      </div>
    </I18nProvider>
  );
}

export default AuthLayout;
```

As you can see, we:
1. fetch the data
2. if the data contains a `redirect` property, we redirect to the destination (for example, when the user is already logged in)
3. otherwise, we render the children (such as the sign-in page, etc.)

The other layouts will work in a very similar way.

### The new Next.js Route handlers

Next.js has also released an alternative way to define API routes, using the new Route handlers. This new API is still experimental and will replace the "old" `pages/api` API handlers.

Let's take a quick look at the new API handlers. We have added a new directory called `api` that contains the API handlers. To define a route, we create a directory within `api` and create a file called `route.ts`.

For example, we create a route handler for the `/api/stripe/checkout` route:

```tsx title="app/api/stripe/checkout/route.ts"
export async function POST(
  req: Request
) {
  const payload = await req.text();

  /// handle webhook here

  return NextResponse.json({
    success: true,
  });
}
```

As you can see we can define the method handlers by simply exporting the method name using its uppercase form. For example, we can define a `GET` handler by exporting a `GET` function.

```tsx
export async function GET(
  req: Request
) {
  const data = await getData();

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

While I have created a folder named `api` which looks a lot like the `pages/api` directory, it is important to notice that you can co-locate API handlers with your pages, for example, you can create a `checkout` directory in the `app` directory and create a `route.ts` file there and execute a request against the `/app/checkout` route.

In my opinion, it can still be useful to define API handlers in a separate directory, such as the `api` directory, as it allows you to define API handlers that are not part of your app, such as the `stripe` API handlers. This is just my preference at this time, and it can likely change in the future.

## Difficulties with the Next.js app directory

While everything has been generally smooth, there have been a few difficulties with the Next.js app directory.

### i18n

At this time, the biggest difficulty with the Next.js app directory has been i18n using `i18next`. I have been able to get it working, but it has been a bit of a struggle. 

The examples online are either lacking or simply don't work, and I have had to spend a lot of time trying to figure out how to get them working.

### Mutations

Next.js is still working on mutations, which will likely allow us to define mutations in the same way we define API handlers, and automatically refresh the loaders when the mutations are executed, similar to how Remix works.

To work it around for the time being, mutations are executed using fetch requests wrapped with `useMutation` from `swr`, and manually calling `router.refresh` when the mutation succeeds. Ideally, we will be able to remove the `router.refresh` call once mutations are supported.

## Conclusion

The Next.js Supabase SaaS kit is slated to be released in March, and I am very excited about it. Do you have any questions about the kit? Let me know! 

If you want, sign up for the newsletter to be notified when the kit is released.

Ciao!

A sneak peek at the Supabase and Next.js RSC SaaS kit


Paginating data is a common task in web development. In this article, we learn how to paginate data with [Supabase](https://supabase.com) and React.js, and then render the data in a table using [React Table](https://tanstack.com/table/v8), likely the best table library for React.js.

## Prerequisites

We assume you have a basic understanding of React.js and Supabase, and a bare-bones codebase to work with. We also assume you have a Supabase project set up and a table with some data in it.

In our example, we will be fetching data from a PostgreSQL table called `organizations`, then proceed to paginate the data and render it in a table. 

The pagination is driven a `page` query parameter, set using the utilities provided by React Table. Fetching the data can be done in various ways depending on which framework you will be using, such as Remix or Next.js. For simplicity, we will fetch the data simply using the `supabase-js` library.

## Fetching the data

We will be using the `supabase-js` library to fetch the data from the `organizations` table.

Our `getOrganizations` function will take two parameters, the `client` and the `params` object. The `client` is the Supabase client, and the `params` object contains the `from` and `to` index of the data to fetch:

```tsx
export async function getOrganizations(
  client: Client,
  params: {
    from: number;
    to: number;
  }
) {
  return await client
    .from('organizations')
    .select('*')
    .range(params.from, params.to);
}
```

Assuming we're fetching this data in a React component, we can then call the `getOrganizations` function:

```tsx
const ITEMS_PER_PAGE = 10;

function OrganizationsDataProvider(
  props: React.PropsWithChildren<{
    page: number;
  }>
) {
  const [state, setState] = useState({
    loading: true,
    error: undefined,
    data: undefined,
  });

  // Get the Supabase client
  const client = useSupabase();

  useEffect(() => {
    async function fetchOrganizations() {
      try {
        setState({
          loading: true,
          error: undefined,
          data: undefined,
        });

        const from = props.page * ITEMS_PER_PAGE;
        const to = from + ITEMS_PER_PAGE;

        const { data, error } = await getOrganizations(client, {
          from,
          to,
        });

        if (error) {
          throw error;
        }

        setState({
          loading: false,
          error: undefined,
          data,
        });
      } catch (error) {
        setState({
          loading: false,
          error,
          data: undefined,
        });
      }
    }

    fetchOrganizations();
  }, [client, page]);

  return (
    <OrganizationsTable organizations={organizations} />
  );
```

As you can see in the code above, we receive the `page` parameter from the parent component, and then use it to calculate the `from` and `to` index of the data to fetch. We then call the `getOrganizations` function, and pass the `client` and the `from` and `to` index as parameters.

The `page` parameter will ideally be passed from the URL, so we can simply update the page by changing the URL.

For example, if we're using Next.js, we can use the `useRouter` hook to get the `page` parameter from the URL:

```tsx
import { useRouter } from 'next/router';  

function OrganizationsPage() {
  const router = useRouter();
  const page = router.query.page || 0;

  return (
    <OrganizationsDataProvider page={page} />
  );
}
```

## Paginating the data

Now that we have the data, we define the component `OrganizationsTable` to render the table to paginate the data.

```tsx
function OrganizationsTable(
  props: React.PropsWithChildren<{
    organizations: Organization[];
  }>
) {
  const columns = useMemo(() => {
    return [
      {
        id: 'id',
        header: 'Id',
        accessorKey: 'id',
        cell: (ctx) => ctx.getValue(),
      },
      {
        id: 'name',
        header: 'Name',
        accessorKey: 'name',
        cell: (ctx) => ctx.getValue(),
      },
    ];
  }, []);

  return (
    <Table 
      data={organizations} 
      columns={columns} 
      onPaginationChange={({ pageIndex }) => {
        // update the search params with page=pageIndex
        // this will trigger a re-render of the component
        // and fetch the data for the new page
      }}
   />
  );
}
```

As you can see, the `onPaginationChange` callback is called when the user changes the page. We can then update the `page` query parameter in the URL, which will trigger a re-render of the component and fetch the data for the new page. 

Depending on the router you're using, you can use the `useRouter` hook from `next/router` or `useLocation` hook from `react-router-dom`, or `setSearchParams` from `remix`.

## Building the Table component

We've built the Table component using React Table, which is a great library for building tables in React.js. 

If you're looking for the full source code, here is where you can read it: [Reusable Table component with React Table](/snippets/reusable-table-component-reactjs).

## Alternative approaches with SSR

The alternative approach, which is likely the best one, is to load the data from the server, and then pass it to the client. This also makes it easier to restrict the maximum amount of items to fetch.

## Example: fetching data with Next.js

For example, if we're using Next.js, we can use the `getServerSideProps` 
function to fetch the data from the server, and then pass it to the client:

```tsx
const ITEMS_PER_PAGE = 20;

export async function getServerSideProps(ctx) {
  const page = ctx.query.page || 0;
  const client = getSupabaseServerClient(); // you will have to implement this

  const from = page * ITEMS_PER_PAGE;
  const to = from + ITEMS_PER_PAGE;

  const { data: organizations, error } = await getOrganizations(client, {
    from,
    to,
  });

  if (error) {
    return ctx.res.status(500).end();
  }

  return {
    props: {
      organizations
    },
  };
}
```

Then, you could fully skip the `OrganizationsDataProvider` component, and simply pass the `organizations` prop to the `OrganizationsTable` component:

```tsx
function OrganizationsPage(props) {
  return (
    <OrganizationsTable organizations={props.organizations} />
  );
}
```

## Example: fetching data with Remix

If you're using Remix, you can use the `useLoaderData` hook to fetch the data from the `loader` function, and then pass it to the client:

```tsx
const ITEMS_PER_PAGE = 20;  

export async function loader({ request }: LoaderArgs) {
  const page = new URL(request.url).searchParams.get('page') || 0;
  const client = getSupabaseServerClient(); // you will have to implement this

  const from = page * ITEMS_PER_PAGE;
  const to = from + ITEMS_PER_PAGE;

  const { data: organizations, error } = await getOrganizations(client, {
    from,
    to,
  });

  if (error) {
    return new Response(`Could not load data`, { status: 500 });
  }

  return json({ organizations });
}

export default function OrganizationsPage() {
  const data = useLoaderData<typeof loader>();

  return (
    <OrganizationsTable organizations={data.organizations} />
  );
}
```

## Example: fetching data with Next.js 13 Server Components

If you're using Next.js 13 with Server Components, you can use the `use` hook to fetch the data from the Server Component and pass it down to the client components:

```tsx
function OrganizationsPage() {
  const { data, error } = use(
    getOrganizations(client, {
      from,
      to,
    })
  );

  if (error) {
    return <div>Could not load data</div>;
  }

  return (
    <OrganizationsTable organizations={data} />
  );
}
```

## Conclusion

In this article, we've seen how to fetch paginated data from a Supabase database, and then paginate the data using React Table. 

We've also seen how to fetch the data from the server, and then pass it to the client using Next.js, Remix, and Next.js 13 Server Components.

If you have any questions, feel free to contact me in our Discord Server!

Pagination with React.js and Supabase

SaaS


## Why use Supabase with React Query?

[Supabase](https://supabase.com) offers a Javascript SDK for interacting with the Supabase services, such as its hosted Postgres database. As such, it doesn't seem like you would need to use a library like [React Query](https://react-query.tanstack.com/) to fetch data from the server. 

However, there are a few reasons why you might want to use React Query with Supabase:
1. Data re-fetching with React Query. By using React Query, you can easily refetch data after a mutation, or update the cache and add optimistic updates to your application.
2. Caching data. React Query can cache data in various ways, such as in-memory, local storage, or using HTTP caching. This can be useful if you want to reduce the number of requests to your database, and it's arguably necessary if you want to reduce your database costs and scale your application.

While there can be more valid reasons to use React Query with Supabase, these are the two main reasons why I use it, and why I think you should too. 

In this post, I want to show you how to use React Query with Supabase. I'll be using the [Remix](https://remix.run) framework, but the concepts should apply to any React application.

NB: This post has been updated to work with React Query v5 and the new Supabase SSR package.

### Why is React Query ideal for Supabase?

Since the realtime database does not support the streaming of snapshots, React Query is my preferred way to fetch data from the database without having to write a lot of code to manage the client-side state. 

By re-fetching data after a mutation, you can easily keep your client-side state in sync with the database without having to merge the data yourself.

## How to use Supabase with React Query

### Installing the dependencies with NPM

First, we want to install the following dependencies in your project:

```bash
npm install @supabase/supabase-js @tanstack/react-query @supabase/ssr
```

### Creating a React Query client

In the root o your component tree, you want to create a React Query client. This is where you can configure the cache and other options. 

For simplicity, we will just create a default client but do check out the API to see what other options you can configure.

In Remix, we would wrap the root outlet with the `QueryClientProvider` component:

```tsx
const queryClient = new QueryClient();

<QueryClientProvider client={queryClient}>
  <Outlet />
</QueryClientProvider>
```

If you're using Next.js, the above will be placed either in your `_app.tsx` file or in your `pages/root.tsx` layout component.

### Creating a hook to create a Supabase client

Next, we want to create a hook to create a Supabase client. This is so that we can easily create a Supabase client in any component using the `useSupabase` hook.

First, we create a function to create a Supabase client:

```tsx
import { createBrowserClient } from '@supabase/ssr';
import invariant from 'tiny-invariant';

import getEnv from './get-env';
import type { Database } from '../../database.types';

let client: ReturnType<typeof createBrowserClient<Database>> | undefined;

export function getSupabaseBrowserClient() {
  if (client) {
    return client;
  }

  const env = getEnv();

  invariant(env.SUPABASE_URL, `Supabase URL was not provided`);
  invariant(env.SUPABASE_ANON_KEY, `Supabase Anon key was not provided`);

  client = createBrowserClient<Database>(
    env.SUPABASE_URL,
    env.SUPABASE_ANON_KEY,
  );

  return client;
}
```

While your code will certainly be different, **it's only important to notice that you need to pass the correct environment variables to the browser client**. In our implementation, we use an abstract `getEnv` function to get the environment variables.

Next, we can wrap the above in a `useMemo` hook to prevent the client from being recreated on every render:

```tsx title="hooks/use-supabase.ts"
import { useMemo } from 'react';
import { getSupabaseBrowserClient } from '~/core/supabase/browser-client';

function useSupabase() {
  return useMemo(getSupabaseBrowserClient, []);
}

export default useSupabase;
```

### Creating a hook to fetch data

Now that we have a Supabase client, we can create a hook to fetch data from the database. 

My favorite pattern for fetching data is to create a hook that returns a `useQuery` hook from `react-query`. Additionally, I like to pass the client as a parameter to a function that builds the query. This allows us to reuse the same query in both client and server code when creating different Supabase clients.

For example, we assume that we have a `organizations` table in our database, and we want to fetch an organization by its ID. 

We can create a hook like this:

```tsx title="hooks/use-organization-query.ts"
function useOrganizationQuery(organizationId: number) {
  const client = useSupabase();
  const queryKey = ['organization', organizationId];

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

  return useQuery({ queryKey, queryFn });
}

export default useOrganizationQuery;
```

1. first, we imported the Supabase client using the `useSupabase` hook.
2. we then created a key for the query. This is used to identify the query in the cache and to refetch the query after a mutation.
3. we return the `useQuery` hook from `react-query`. This hook takes a key and a function that returns a promise with the data.

Instead, the function `getOrganizationById` is a function that builds the query. This function is used in both client and server code, and it looks like this:

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

#### Fetching data in a component

Now that we have a hook to fetch data, we can use it in a component. In this example, we will fetch an organization by its ID:

```tsx title="pages/organizations/[organizationId].tsx"
function OrganizationPage({
  organizationId
}: {
  organizationId: number;
}) {
  const { 
    data: organization, 
    isLoading, 
    isError 
  } = useOrganizationQuery(organizationId);

  if (isLoading) {
    return <div>Loading...</div>;
  }

  if (isError) {
    return <div>Error</div>;
  }

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

The hook from `react-query` returns an object that we can use to determine the state of the query. In the example above we are checking if the query is loading or if there was an error.

### Creating a hook to mutate data

Now that we have a hook to fetch data, we can create a hook to mutate data. Mutating data typically happens upon a user action, such as submitting a form. 

The concept is similar to the above, but instead of using `useQuery` we will use `useMutation` from `react-query`.

For example, we assume that we have a `organizations` table in our database, and we want to update an organization by its ID.

We can create a hook like this:

```tsx title="hooks/use-update-organization-mutation.ts"
function useUpdateOrganizationMutation() {
  const client = useSupabase();

  const mutationFn = async (organization: Organization) => {
    return updateOrganizationById(client, organization).then(
      (result) => result.data
    );
  };

  return useMutation({ mutationFn });
}
```

1. first, we imported the Supabase client using the `useSupabase` hook.
2. we return the `useMutation` hook from `react-query`. This hook takes a function that returns a promise with the data.

```tsx
export async function updateOrganization(
  client: Client,
  params: {
    id: number;
    data: Partial<Organization>;
  }
) {
  return client
    .from('organizations')
    .update({
      name: params.data.name,
    })
    .match({ id: params.id })
    .throwOnError()
    .select<string, Organization>('*')
    .throwOnError()
    .single();
}
```

#### Mutating data in a component

Now that we have a hook to mutate data, we can use it in a component. In this example, we will update an organization by its ID:

```tsx title="OrganizationForm.tsx"
export function OrganizationForm({
  organizationId
}: {
  organizationId: number;
}) {
  const updateOrganizationMutation = useUpdateOrganizationMutation();

 const onsSubmit = (event: React.FormEvent<HTMLFormElement>) => {
    event.preventDefault();

    const formData = new FormData(event.currentTarget);
    const name = formData.get('name') as string;

    updateOrganizationMutation.mutate({
      id: organizationId,
      data: {
        name,
      },
    });
  };

  return <form onSubmit={onSubmit}></form>;
}
```

We have abstracted the form's UI, but the concept is the same. We call the `mutate` function from the hook to update the data.

If you want to turn the request into a promise, you can use the `mutateAsync` function:

```tsx
updateOrganizationMutation.mutate({
  id: organizationId,
  data: {
    name,
  },
});
```

This is incredibly useful if you want to do something after the mutation has completed or if you use a library that accepts a promise. In the case of Makerkit, we use `react-hot-toast` to show a toast during the mutation.

### Re-fetching data after a mutation

When we mutate data, we want to re-fetch the data to display the newly updated data within the UI. To coordinate data reefetching across queries, we can use the query client from `react-query` to reresh queries by referring to them using their IDs. 

Let's rewrite the `useUpdateOrganizationMutation` hook to re-fetch the query after the mutation has completed:

```tsx title="hooks/use-update-organization-mutation.ts"
function useUpdateOrganizationMutation() {
  const client = useSupabase();
  const queryClient = useQueryClient();

  const mutationFn = async (organization: Organization) => {
    return updateOrganizationById(client, organization).then(
      (result) => result.data
    );
  }, {
    onSuccess: (data, variables) => {
      queryClient.refetchQueries(['organization', variables.id]);
    }
  };

  return useMutation({ mutationFn });
}
```

### Updating the cache after a mutation

When we mutate data, we want to update the cache to display the newly updated data within the UI. 

To coordinate data refetching across queries, we can use the query client from `react-query` to update the cache by referring to them using their IDs.

```tsx
const queryClient = useQueryClient()

const promise = updateOrganizationMutation.mutateAsync(organizationData, {
  onSuccess: () => {
    const newOrganizationData = {
      ...organization,
      ...organizationData,
    };

    setOrganization(newOrganizationData);

    const userId = session?.data?.id;
    const query = ['organizations', { userId }];

    queryClient.setQueryData<UserOrganizationData[]>(query, (data) => {
      if (data) {
        return data.map((item) => {
          if (organization.id === item.organization.id) {
            const mergedOrganization = {
              ...item.organization,
              ...newOrganizationData,
            };

            return { ...item, organization: mergedOrganization };
          }

          return item;
        });
      }
    });
  },
});
```

### Invalidating a query after a mutation

Similarly, we can invalidate a query after a mutation to force a re-fetch of the data. This is useful if we want to update the cache with the latest data.

```tsx
const queryClient = useQueryClient()

const promise = updateOrganizationMutation.mutateAsync(organizationData, {
  onSuccess: () => {
    queryClient.invalidateQueries(['organization', organization.id]);
  }
});
```

### Optimistic updates with React Query

It can be useful in terms of UX to update the UI before the mutation has completed. This is called an optimistic update.

React Query makes it a breeze to do this. We can use the `onMutate` function to update the cache before the mutation has completed. If the mutation fails, we can use the `onError` function to roll back the cache to its previous state.

```tsx
const queryClient = useQueryClient()

useMutation(updateOrganization, {
  onMutate: async organization => {
    // Cancel any outgoing refetches
    await queryClient.cancelQueries('organizations');

    // Snapshot the previous value
    const snanpshot = queryClient.getQueryData('organizations');

    // Optimistically update to the new value
    queryClient.setQueryData('organizations', old => [...old, organization]);

    // Return a context object with the snapshotted value
    return { snanpshot };
  },
  onError: (err, newTodo, context) => {
    // If the mutation fails, use the context returned from onMutate to roll back
    queryClient.setQueryData('todos', context.snanpshot)
  },
  onSettled: () => {
    // Always refetch after error or success
    queryClient.invalidateQueries('organizations')
  },
});
```

## Conclusion

In this article, we have learned how to use Supabase with React Query.

I hope the above has given you some ideas on how to use Supabase with React Query. If you have any questions, please feel free to reach out!

How to use Supabase with React Query


While Cypress has greatly simplified E2E testing for developers, it can still be tricky at times. For example, a best practice while running E2E testing is bypassing the UI when testing pages behind user authentication. 

The Cypress team, in particular, has long advocated for programmatically authenticating users when testing code not related to the authentication flow.

For example, if you are testing your Dashboard code, there is no need to use the UI to authenticate your users: this will only result in slower, heavier and more flaky E2E tests.

In this post, we show you how to sign in programmatically with Supabase Authentication to improve the speed of your Cypress tests and increase their reliability.

## Adding a Cypress command to sign-in programmatically

Cypress allows us to write global commands that we can access using the `cy` variable, which is globally available in all our Cypress tests.

To do so, we will extend Cypress commands with a new command we will name `signIn`, and will be available to us using `cy.signIn()`. Neat, isn't it?

First of all, we want to play nice with Typescript. That means we extend the Typescript's interface in a filename we name `global.d.ts`:

```tsx title="global.d.ts"
namespace Cypress {
    interface Chainable {
      signIn(
        redirectPath?: string,
        credentials?: { email: string; password: string }
      ): void;
    }
  }
}
```

Now, we can extend Cypress with a custom command named `signIn`. To do so, we add a command using the method `Cypress.Commands.add`:

```tsx
Cypress.Commands.add(
  'signIn',
  (
    redirectPath = '/',
    credentials = {
      email: Cypress.env(`EMAIL`) as string,
      password: Cypress.env(`PASSWORD`) as string,
    }
  ) => {
    // body
  }
);
```

The above function takes two parameters:

1. A path where to redirect users after signing in
2. The user credentials, but by providing some default values using environment variables

Let's now write the body of the function:

```tsx
// the function we will define to sign users in
signInProgrammatically(credentials); // <--- implementation is below

// after sign-in, we redirect the users to the provided path
cy.visit(redirectPath);
```

### Signing in using Cypress sessions

If you are using Cypress 12, you will need to use `cy.session`. The `cy.session` command will preserve the session cookie between tests, otherwise, the user will get logged out.

```tsx
Cypress.Commands.add(
  'signIn',
  (
    redirectPath = '/',
    credentials = {
      email: Cypress.env(`EMAIL`) as string,
      password: Cypress.env(`PASSWORD`) as string,
    }
  ) => {
    cy.session([credentials.email, credentials.password],
      () => {
        cy.log(`Signing in with ${credentials.email}`);
        signInProgrammatically(credentials);
      }
    );

    cy.visit(redirectPath);
  }
);
```

## Using the Supabase SDK to authenticate users in Cypress E2E tests

To sign our testing users in without having to interact with the application's UI, we will use the Supabase client SDK.

First, we initialize the Supabase client using the `SUPABASE_URL` and `SUPABASE_ANON_KEY` environment variables:

```tsx
function getClient() {
  const url = Cypress.env(`SUPABASE_URL`);
  const key = Cypress.env(`SUPABASE_ANON_KEY`);

  invariant(url, `Missing SUPABASE_URL env variable`);
  invariant(key, `Missing SUPABASE_ANON_KEY env variable`);

  return createBrowserClient(url, key);
}
```

### Signing users in

Now that we can create an instance of the Supabase SDK, we can use it to sign users in programmatically:

```tsx
function signInProgrammatically(credentials: {
  email: string;
  password: string;
}) {
  const { email, password } = credentials;

  return getClient()
    .auth.signInWithPassword({
      email,
      password,
    })
    .then((response) => {
      if (response.error) {
        return Promise.reject(response.error.message);
      }
    })
    .catch((e) => {
      console.error(e);

      return Promise.reject(e);
    });
}
```

Finally, the `signInProgrammatically` function completes the `cy.signIn()` command defined in the beginning.

## Writing a Test that signs users in programmatically

Whenever you write tests that require users to be signed in, you can write the below:

```tsx
describe(`Create Invite`, () => {
  const email = `invited-member@makerkit.dev`;

  before(() => {
    cy.signIn(`/settings/organization/members`);
  });

  // your tests go here
});
```

As you can see, we can pass any path to the `signIn` function: after signing in, we redirect the users directly to that page, rather than having to use the UI. 

By programmatically signing users in, we will dramatically improve your E2E tests' speed and make them more reliable. Regardless, no need to test the authentication page over and over!

Programmatic Authentication with Supabase and Cypress


Resetting your database state when executing your E2E tests is a common practice to ensure that your tests are isolated from each other. This is important because you don't want to have to write your tests in a specific order or rely on the state from a previous test. 

This is a common cause of flakiness, and it's best to avoid it. In this tutorial, we'll show you how to reset the Supabase database in Cypress E2E tests, so that you can write your tests in any order and not worry about the state of the database.

While this tutorial is written for Cypress, the same principles apply to other E2E testing frameworks.

## When should you reset the database?

There are two ways to reset the database in Supabase:

1. by writing a plugin that resets the database before each spec (or test)
2. by manually resetting the database in your tests where you need it

While the first option is the easiest, it may not always be the best. If you have a lot of tests, resetting the database before each test can slow down your tests significantly. 

Generally speaking, if your tests are well-written, you may not need to reset the database before each test. If you find that your tests are flaky, then you should consider resetting the database before each test.

## Writing an NPM script to reset the database

First, we want to add a new npm script to our `package.json` file

```json
"supabase:db:reset": "supabase db reset"
```

If you want to debug the database reset, you can add the `--debug` flag to the command.

```json
"supabase:db:reset": "supabase db reset --debug"
```

## Writing a Cypress plugin to reset the database before each test

Let's take a look at how we can write a Cypress plugin to reset the database before each test. 

If you are using a newer version of Cypress, we will write plugins using the configuration file `cypress.config.ts`. 

Let's write a function that calls the `npm` script we wrote earlier.

```ts title="cypress.config.ts"
import { execSync } from 'child_process';

function resetDb() {
  console.log(`Resetting database...`);

  try {
    execSync('npm run supabase:db:reset');

    console.log(`DB reset successful`);

    return true;
  } catch (error) {
    console.error(`DB reset failed`, error);
  }

  return false;
}
```

Now, we can use this function in a Cypress plugin. To do so, we will use the `setupNodeEvents` function:

```ts title="cypress.config.ts"
setupNodeEvents(on, config) {
  on('before:spec', () => {
    resetDb();
  });
}
```

If you want to use this plugin in the windowed/interactive version of Cypress, we need to activate an experimental flag. To do so, add the following property to your Cypress configuration:

```ts title="cypress.config.ts"
{
  experimentalInteractiveRunEvents: true,
}
```

I suggest doing it, since running the tests in the interactive mode that updates the DB will most likely fail if you don't reset the database on each test.

Now, go on and run your tests. You should see the database being reset before each test! 🎉 Yay!

## Manually resetting the database in your tests

If you don't want to reset the database before each test, you can also reset the database manually in your tests. 

Let's add a custom Cypress command to do so.

### Writing the Cypress task that will execute the npm script

First, we need to write a Cypress task that will execute the npm script we wrote earlier. 

We will add this next to the `on` event we wrote earlier in `setupNodeEvents`:

```ts title="cypress.config.ts"
setupNodeEvents(on, config) {
  on('task', {
    resetDatabase() {
      return resetDb();
    },
  });
}
```

### Adding a custom Cypress command to reset the database

If you use Typescript, we need to augment the Cypress namespace to add our custom command. Add the snippet below to your global typings file and ensure it's picked up by your `tsconfig.json` file:

```ts
declare global {
  namespace Cypress {
    interface Chainable {
      resetDatabase(): void;
    }
  }
}
```

Now, we can add the command to the `commands.ts` file

```ts title="cypress/support/commands.ts"
Cypress.Commands.add(`resetDatabase`, () => {
  cy.task(`resetDatabase`);
});
```

We can now call `cy.resetDatabase()` in our tests to reset the database. For example, we can add it to the `before` hook of a specific test:

```ts title="cypress/integration/my-test.spec.ts"
describe('My test', () => {
  before(() => {
    cy.resetDatabase();

    // wait for the database to reset
    cy.wait(1000)
  });

  it('should do something', () => {
    // ...
  });
});
```

## Conclusion

In this tutorial, we learned how to reset the Supabase database in Cypress E2E tests. We saw how to write an npm script to reset the database, and how to write a Cypress plugin to reset the database before each test. We also saw how to write a custom Cypress command to reset the database manually in our tests.

If you have any questions, feel free to reach out to us on Discord or Twitter. We're happy to help!

Reset the Supabase Database in Cypress


Firebase and Supabase are two of the most popular backend-as-a-service (BaaS) platforms. While at Makerkit we started by using Firebase for our original SaaS kit, we are now also working to support SaaS kits based on Supabase.

In this article, we will compare Firebase vs Supabase to help you decide which one is better for your next project, so you can choose the right kit for your needs.

---

Makerkit is a SaaS boilerplate to build a SaaS using Firebase or Supabase. It's a complete solution that includes a landing page, a dashboard, and a billing system. It's built with React, Next.js or Remix, Tailwind CSS, and TypeScript.

## What is Firebase?

Firebase is a BaaS platform that provides a set of tools and services to help you build and run your app. It is developed by Google and is one of the most popular BaaS platforms.

Firebase offers a wide range of services, including:
- Authentication
- Realtime Database / Firestore
- Storage
- Hosting
- Cloud Functions
- Cloud Messaging
- Performance Monitoring
- Remote Config
- Analytics

## What is Supabase?

Supabase is an open-source alternative to Firebase. It is a BaaS platform that provides a set of tools and services to help you build and run your app. It's backed by YC and Mozilla and is one of the fastest-growing BaaS platforms.

Supabase also offers a wide range of services, including:
- Authentication
- Realtime Database / Postgres
- Storage
- Functions

## Features

When it comes to features, it's clear that Firebase has the upper hand, as it offers more services than Supabase.

However, Supabase is catching up fast and is adding new features regularly. It's also worth noting that many Firebase services only work for mobile apps, such as Crashlytics, ML, Dynamic Links, and others.

If you're building a web app, **Firebase and Supabase will offer you a similar set of features**.

## Authentication

Firebase and Supabase both offer complete authentication services that offer a variety of authentication methods, including email/password, phone, magic link, Google, Facebook, Twitter, and GitHub.

Firebase also offers anonymous authentication, which is not available in Supabase. This can be useful if you want to allow users to use your app without signing up.

There isn't a large difference Firebase and Supabase when it comes to authentication. Both platforms offer an exceptional set of features and are easy to use.

## Database

Firebase offers two database options: Realtime Database and Firestore. Realtime Database is a NoSQL database that stores data in JSON format. Firestore is a document-based database that stores data in JSON format.

### Firestore DB
Firestore allows us to write and read data directly from the clients without having to write any server code by writing security rules.

### Supabase Postgres

Supabase offers a managed Postgres database.

Postgres is one of the most popular and battle-tested relational databases that stores data in tables.

Supabase also supports client-side reads and writes by allowing developers to protect their database using Postgres Row Level Security (RLS): these rules allow us to control who can read and write data using SQL.

## Firestore vs Postgres

Firestore and Postgres are two different types of databases. Firestore is a document-based database that stores data in JSON format. Postgres is a relational database that stores data in tables.

I would recommend using Firestore if you're not experienced with SQL and relational databases. Firestore is simpler to use, and most importantly easier to secure: Firestore security rules are arguably much simpler than Postgres RLS.

However, if you're experienced with SQL and relational databases, then Postgres is the better option. Postgres is a battle-tested database that is used by many large companies, allows us to write complex queries, can allow us to use full-text search, and is better when it comes to data integrity.

Simply speaking, Firestore is **better for beginners**, and Postgres is **better for experienced developers** who have already worked with Postgres and SQL.

This does not mean Firestore is not a good option for experienced developers: if your data structure is valid for NoSQL and you don't need to write complex queries, then Firestore is a great option.

### Realtime

Firebase and Supabase both offer realtime database services, but there are differences worth noting.

#### Firebase Firestore Realtime Database

Firebase's realtime queries allow us to listen to changes in the database and receive updates in real-time: the updates include the full snapshot of our query.

The ability to receive real-time snapshots of a query is incredibly useful since we don't need to write any client-side code to manage state and reconcile changes.

The UI will automatically reflect the changes in the database using the snapshot from the realtime query.

#### Supabase Postgres Realtime Database

Supabase's realtime works differently, and it's not as straightforward as Firebase's realtime queries.

It uses a pub/sub system that allows us to listen to changes in the database and receive updates in real-time. Updates do not return the current snapshot of the original query, but rather they indicate what changed in the database. This means that we need to write client-side code to manage the state and reconcile changes.

The UI will not automatically reflect the changes in the database, but we need to write code to update the UI.

When it comes to real-time changes, Firebase is the clear winner.

## Self Hosting

Many developers may want to self-host their app, be it for security reasons or scalability.

When it comes to self-hosting, the answer is simple: **Firebase does not allow us to self-host** our app, while **Supabase does**.

If self-hosting is important to you, then Supabase is the better option.

## Local Development

Firebase and Supabase both offer a local development environment that allows us to run our app locally. This is incredibly useful since we can test our app locally before deploying it to production.

Firebase offers a local emulator that allows us to run the Firebase services locally: it's a bit of a black box, and we cannot see what's happening under the hood. It works fairly well though, and it's feature-complete these days.

Supabase allows us to run a self-hosted instance locally using Docker. It still lacks some features but is getting better every day.

Both services offer a local development Admin UI.

## SDK

Firebase and Supabase both offer a complete set of SDKs. Generally speaking, they're both very valid options.

Firebase's SDK is more mature and has more features. It's split into multiple packages for each feature. This was necessary so that we could tree-shake the library and reduce the bundle size.

Supabase's SDK, instead, has a much smaller API surface, it's more lightweight and simpler to use.

### Isomorphic SDK

Firebase's SDK is split between Client SDK and Admin SDK. When we use the SDK in our API functions, or when server-side rendering, we cannot use the client SDK, but we're constrained to use the Admin SDK.

This has a lot of disadvantages, especially when it comes to server-side rendering (SSR): in fact, we are forced to write separate queries for the client and the server, and we cannot use the same query for both. This leads to more code and more complexity.

Instead, the Supabase client SDK is isomorphic, which means that we can use the same SDK both on the client and on the server. This allows us to write less code and have a simpler architecture.

### Edge Environments

Supabase has a clear advantage over the Firebase SDK: in fact, it can be used in edge environments, such as Cloudflare Workers and Deno. Instead, Firebase's SDK is only available for Node.js and the browser.

What does it mean? It means that by allowing us to use Supabase in edge environments, we can use Supabase to build serverless applications that run on the edge. This can unlock incredibly fast performance and reduce costs.

### SDK: which one is the winner?

While the Firebase SDK is more mature and has more features, the Supabase SDK is more lightweight and simpler to use. Additionally, it allows us to use the same SDK both on the client and on the server and in edge environments which is a huge advantage.

Personally speaking, I prefer the Supabase SDK.

## Conclusion

Firebase and Supabase are both great BaaS platforms. They both offer a complete set of features and are easy to use. Ultimately, since they offer a similar set of features, the choice between Firebase and Supabase will depend on your use case, your preferences, and your experience.

### When to use Firebase

Here are some examples of use cases where Firebase is a better option:

- If you're building a mobile app, Firebase offers more features than Supabase
- If you're a beginner and you're not familiar with SQL and relational databases, Firestore is a better option than Postgres
- If you prefer not to manage client-side state and rely on real-time features to automatically update the UI, Firebase is a better option than Supabase
- If you prefer to use a more hands-off service, Firebase is a better option than Supabase

### When to use Supabase

Here are some examples of use cases where Supabase is a better option:

- If you want to use Postgres and leverage better data integrity, more complex queries, and full-text search, Supabase is a better option than Firestore
- If you want to use the same SDK both on the client and on the server, Supabase is a better option than Firebase
- If you want to use Supabase in edge environments, Supabase is a better option than Firebase
- If you want to self-host your BaaS, Supabase is a better option than Firebase
- If you want to use a BaaS that is open-source and transparent, Supabase is a better option than Firebase


Supabase

Tutorials and Guides about Supabase