DEV Community: Sebastian Ruhleder

Protected Routes with Supabase and Next.js

Sebastian Ruhleder — Fri, 03 Dec 2021 12:44:02 +0000

Some routes of your web application are meant for authenticated users only. For example, a /settings page can only be used if the user is signed in.

You could solve this client-side: Once the page renders, you check whether a user is signed in; if they are not, you redirect the user to the sign in page.

There is a problem with this, though. The page will start to render, so you either have to prevent everything from rendering until this check is done or you will see a partially rendered page suddenly redirected to the sign in page.

Luckily with Next.js, we can do this check server-side. Here's an outline of how we're going to do it:

Write an API route /api/auth to set a cookie based on whether a user signs in or out.
Register a listener with Supabase's onAuthStateChange to detect a sign in or sign out and call this API route.
Extract a function enforceAuthenticated to protect a route with one line of code.

Setting an Auth Cookie

Supabase provides a setAuthCookie function defined in @supabase/gotrue-js. This function takes a Next.js (or Express) request and response and sets or removes an auth cookie.

To make use of it, we introduce an API route /api/auth and simply call setAuthCookie, passing it the request and response objects.

// pages/api/auth.ts
import { NextApiRequest, NextApiResponse } from 'next';
import { supabase } from './../../components/supabaseClient';

const handler = (req: NextApiRequest, res: NextApiResponse) => {
    supabase.auth.api.setAuthCookie(req, res);
};

export default handler;

setAuthCookie behaves like this:

The request req must be POST request.
The request body must contain two elements: a session and an event.
The session contains session data (as is provided by supabase.auth.session() for example).
The event is either SIGNED_IN indicating a sign in or SIGNED_OUT indicating a sign out.

Getting this data is easy.

Updating the Auth Cookie

To keep the auth cookie up to date, we have to listen to changes in the authentication state of Supabase. On every change, we have to call the /api/auth endpoint to update the cookie accordingly.

For this, Supabase provides the onAuthStateChange function, which allows us to register a listener. This listener is called whenever a user signs in or out.

The following snippet should be used within the App component (usually _app.tsx or _app.jsx).

useEffect(() => {
    const { data: authListener } = supabase.auth.onAuthStateChange((event, session) => {
        updateSupabaseCookie(event, session);
    });

    return () => {
        authListener?.unsubscribe();
    };
});

async function updateSupabaseCookie(event: AuthChangeEvent, session: Session | null) {
    await fetch('/api/auth', {
        method: 'POST',
        headers: new Headers({ 'Content-Type': 'application/json' }),
        credentials: 'same-origin',
        body: JSON.stringify({ event, session }),
    });
}

The listener is passed two arguments when the authentication state changes: an event indicating whether the user signed in or out and the current session. This is exactly what the /api/auth endpoint needs to update the auth cookie. Using fetch, we send a simple POST request to it to reflect this change.

👉 I recommend extracting this code into a custom hook (which you can call useUpdateAuthCookie for example).

Changes in the authentication state in the frontend are now reflected in the auth cookie. Why do we update such a cookie? So we can use it server-side when using functions like getServerSideProps.

Protecting Routes

We can now protect a route by checking the auth cookie in getServerSideProps. If the user is signed in, we simply return; otherwise, we redirect the user to a sign in page.

Let's assume this sign in page can be found at /signin.

export async function getServerSideProps({ req }) {
    const { user } = await supabase.auth.api.getUserByCookie(req);

    if (!user) {
        return { props: {}, redirect: { destination: '/signin' } };
    }

    return { props: {} };
}

Depending on how many routes you must protect, it's a good idea to extract this code and reuse it. For my projects, I use a function called enforceAuthenticated. This function takes an optional getServerSideProps function and delegates to it in the case that the user is signed in.

import { GetServerSideProps } from 'next';
import { supabase } from './supabaseClient';

const enforceAuthenticated: (inner?: GetServerSideProps) => GetServerSideProps = inner => {
    return async context => {
        const { req } = context;
        const { user } = await supabase.auth.api.getUserByCookie(req);

        if (!user) {
            return { props: {}, redirect: { destination: '/signin' } };
        }

        if (inner) {
            return inner(context);
        }

        return { props: {} };
    };
};

export default enforceAuthenticated;

With this, quickly protecting a route becomes a one-liner:

// pages/protected.tsx
import enforceAuthenticated from '../components/enforceAuthenticated';

export default function ProtectedPage() {
    return <div>Protected Page</div>
}

export const getServerSideProps = enforceAuthenticated();

When we go to /protected now, we are either redirected to /signin when we are not signed in or the ProtectedPage is rendered.

Recap

Here's what we did:

We created an API route /api/auth which updates an auth cookie based on a session and an event indicating a sign in or sign out.
We created a listener in the App component to send every update to the authentication state to the /api/auth endpoint, thereby updating the auth cookie.
In our server-side code, we used the getUserByCookie function to determine whether a user is signed in or out. Based on this, we either render the page or redirect the user to a sign in page.
We introduced a function enforceAuthenticated to reuse this functionality on as many routes as we want.

If you enjoyed this post, you can follow me on Twitter 🙏

Credits

When I started out with Supabase, I read:

Magic Link Authentication and Route Controls with Supabase and Next.js by Nader Dabit

It's a great post and the first time I saw the setAuthCookie/getUserByCookie combination. Give it a read, it's an excellent post!

Creating User Profiles on Sign-Up in Supabase

Sebastian Ruhleder — Wed, 11 Aug 2021 18:16:38 +0000

Supabase stores authentication-related information (unique ID, email, password, etc.) in the auth.users table when users sign up. The auth schema isn't publicly accessible for security reasons, so you can't store additional information on your users in this table.

Depending on what type of application you are building, you might need a profile table containing profile information your users can interact with. In this post, we will:

Create a simple profile table in the public schema.
Enable Row-Level Security on it and restrict access for users to their own profile data.
Write a database trigger that automatically creates a row for every user on sign-up.

Creating & Securing a Profile Table

We start by creating a profile table with two columns: id referencing a user ID in the auth.users table, and display_name.

CREATE TABLE public.profile (
  id UUID REFERENCES auth.users NOT NULL,
  display_name TEXT NULL,
  PRIMARY KEY (id)
);

Supabase uses PostgREST to access the Postgres database via its API (i.e., the supabase API you use in your client application). By default, a table in the public schema can be accessed without restriction.

However, in our case, we want to restrict access on this table so that users can only select and update data that belongs to them. We are going to use Row-Level Security for this.

ALTER TABLE public.profile
  ENABLE ROW LEVEL SECURITY;

When Row-Level Security is enabled for a table, all access to this table must be allowed by a row security policy. The idea here is: "Everything is forbidden unless explicitly allowed."

The first row security policy we introduce allows a user to SELECT their own profile data:

CREATE POLICY
  "Can only view own profile data."
  ON public.profile
  FOR SELECT
  USING ( auth.uid() = id );

The second row security policy allows a user to UPDATE their own profile data:

CREATE POLICY
  "Can only update own profile data."
  ON public.profile
  FOR UPDATE
  USING ( auth.uid() = id );

The idea behind these policies is to specifically grant rights to SELECT or UPDATE rows where the id is set to the authenticated user's unique ID. Since id is the primary key of the profile table, this effectively leaves only one row: the user's own profile data.

If you want to know how to handle public and private access, I recommend reading the page Managing User Data from the Supabase documentation.

Automatically Creating Profiles on Sign-Up

When a user signs up or signs in with a Third-Party provider (e.g. Twitter, GitHub, Google, etc.), a new row is inserted into the auth.users table. Ideally, we want to create a new profile at the same time. An easy way to do so is to use triggers.

The following statement creates a trigger called create_profile_on_signup that calls the function create_profile_for_new_user() whenever a new row is inserted into the auth.users table:

CREATE TRIGGER
  create_profile_on_signup
  AFTER INSERT ON auth.users
  FOR EACH ROW
  EXECUTE PROCEDURE
    public.create_profile_for_new_user();

The function create_profile_for_new_user() simply inserts a new row into our profile table:

CREATE FUNCTION
  public.create_profile_for_new_user()
  RETURNS TRIGGER AS
  $$
  BEGIN
    INSERT INTO public.profile (id)
    VALUES (NEW.id);
    RETURN NEW;
  END;
  $$ LANGUAGE plpgsql SECURITY DEFINER;

The NEW keyword refers to a variable holding the new database row (i.e., the one that was just inserted into the auth.users table).

There's one thing missing, though: The display_name isn't set. Technically, this isn't a problem, as the column is nullable. For Third-Party logins, however, we can access certain metadata that allows us to prefill this column with a sensible value.

The auth.users table has a JSONB column called raw_user_meta_data containing information on the user depending on the Third-Party provider used for signing in. For example, it usually contains a user_name field.

Making use of this, we can prefill the display_name with this username like this:

CREATE FUNCTION
  public.create_profile_for_new_user()
  RETURNS TRIGGER AS
  $$
  BEGIN
    INSERT INTO public.profile (id, display_name)
    VALUES (
      NEW.id,
      NEW.raw_user_meta_data ->> 'user_name'
    );
    RETURN NEW;
  END;
  $$ LANGUAGE plpgsql SECURITY DEFINER;

Now, whenever a user signs up, a new profile is created with its display_name set to the username used with the Third-Party provider or to NULL when you use Supabase's sign in (here you can fill it from within the client application).

Recap

The auth.users table stores authentication-related information.
You can't access or modify this table from within your application for (obvious) security reasons.
We created a profile table with two columns id and display_name.
We enabled Row-Level Security for this table and restricted access for users to their own data.
We created a trigger and function to automatically insert a new row into profile when a new row is inserted into auth.users table.
When a user signs up or signs in with a Third-Party provider, a new row is inserted into auth.users.

References

I can highly recommend the Next.js Subscription Payments Starter, which uses this idea here.

Using React Query with Supabase

Sebastian Ruhleder — Tue, 10 Aug 2021 18:54:35 +0000

If you are using Supabase in React, it's a good idea to combine it with React Query. Let's first have a look at how you fetch data in Supabase.

const { data, error } = await supabase
  .from('todo')
  .select('id, name')
  .eq('done', false);

This call queries the todo table, selecting the id and name columns and filters for those to-dos that are not done. If error is not null, something went wrong, and data is null. Otherwise, data is an array of objects representing the rows that matched the query.

Since a potential error is returned, the promise we await here never rejects. But the query function we use in useQuery is supposed to either resolve data or throw an error. If we simply wrap the query from above in a useQuery call, React Query cannot detect if the call failed:

// ⛔️ silently swallows a potential 'error'
useQuery(
  ['open-todos'],
  () => supabase
          .from('todo')
          .select('id, name')
          .eq('done', false)
);

To write a useQuery-conform query function, we can explicitly throw an error if one occurs:

useQuery(
  ['open-todos'],
  async () => {
    const { data, error } = await supabase
      .from('todo')
      .select('id, name')
      .eq('done', false);

    if (error) {
      throw new Error(`${error.message}: ${error.details}`);
    }

    return data;
  }
);

Since all calls to Supabase follow the same pattern, we can introduce a small function to reuse this explicit handling of errors:

function useOpenTodos() {
  return useQuery(
    ['open-todos'],
    () => supabase
            .from('todo')
            .select('id, name')
            .eq('done', false)
            .then(handleSupabaseError)
            .then(({ data }) => data)
  );
}

function handleSupabaseError({ error, ...rest }) {
  if (error) {
    throw error;
  }
  return rest;
}

This way, you don't have to write the same boilerplate for every supabase call and can effectively make use of the benefits of React Query's data management.

How to Migrate Supabase Databases with Flyway & GitHub Actions

Sebastian Ruhleder — Mon, 09 Aug 2021 21:24:56 +0000

Completely built on open-source technology, Supabase is an upcoming alternative to Google's Firebase. One distinct difference between Supabase and Firebase is the way they persist and manage data. While Firebase uses Firestore, a NoSQL document database you can only configure via a web interface, Supabase uses a Postgres database under the hood.

When you set up a project, Supabase provides an in-built SQL console you can use to execute SQL statements on the project's database quickly. With a new project, it's tempting to whip up some CREATE TABLE statements and have at it.

And if you are experimenting with Supabase, feel free to use Supabase's SQL console. After all, it works quite well and is, hands down, the fastest way to get cooking. But if you are working on a project that will see the light of production, consider using a tool like Flyway to migrate your database schema more reliably.

In this post, we will set up a GitHub Action to execute Flyway migrations against a Supabase database whenever changes are pushed to a repository. This allows you to store your migrations alongside your code and always keep your database in sync with your business logic.

Finding the Database Connection Info

You need a database host, port, username, password, and database name to run Flyway. In Supabase, you can find this information by clicking on "Settings" and then "Database."

On the Database Settings page, you will find a box titled "Connection info" with all the information you need. For security reasons, the database password is not listed here. When you created the project, Supabase prompted you to enter it.

Creating a Simple Flyway Migration

A Flyway migration is nothing more than an SQL file. Since migrations are used to version control your database schema, these files must adhere to certain naming conventions. Flyway has a great introduction to naming SQL-based migrations.

For our purposes, we will create a profile table with three columns: user_id referencing the ID of a registered user, username, and email.

Let's create a file called V1__create_table_profile.sql in a directory migrations. The migrations directory should be placed in the root directory of our repository:

-- migrations/V1__create_table_profile.sql
CREATE TABLE public.profile (
  user_id uuid REFERENCES auth.users NOT NULL PRIMARY KEY,
  username TEXT NULL,
  email TEXT NULL
);

If you want to change the location of these migrations, make sure to change the GitHub workflow configuration below accordingly.

Writing a GitHub Action to Run Flyway

Whenever we push changes to the migrations in the migrations directory, we want a GitHub Action to run them against our Supabase database.

In our repository, create a file called .github/workflows/migrate.yml with the following content:

name: 'Migrate database schema'

on:
  push:
    branches:
      - main

jobs:
  migrate-database:
    name: Run Flyway migrations
    runs-on: ubuntu-20.04
    env:
      SUPABASE_HOST: db.YOUR_SUPABASE_DATABASE_HOST.supabase.co
      SUPABASE_PORT: 5432
      SUPABASE_USER: postgres
      SUPABASE_DB: postgres
    steps:
      - uses: actions/checkout@v2
      - run: >-
          docker run --rm
          --volume ${{ github.workspace }}/migrations:/flyway/sql:ro
          flyway/flyway:7.12.1-alpine
          -url="jdbc:postgresql://${{ env.SUPABASE_HOST }}:${{ env.SUPABASE_PORT }}/${{ env.SUPABASE_DB }}?sslmode=require"
          -user="${{ env.SUPABASE_USER }}"
          -password="${{ secrets.SUPABASE_PASS }}"
          migrate

The first line defines the workflow's name:

name: 'Migrate database schema'

Then, we define the event that will trigger this workflow. Here, the workflow will only run when someone pushes changes to main:

on:
  push:
    branches:
      - main

The job migrate-database defines four environment variables: SUPABASE_HOST, SUPABASE_PORT, SUPABASE_USER, SUPABASE_DB. Make sure to change them according to the connection info you found on the Database Settings page in Supabase.

This job first checks the repository out and then executes a docker command. This command uses the flyway:flyway image to first mount the migrations directory to the container and then run the migrations against the database configured via the environment variables.

Since the database password is a secret, we are using an encrypted secret to access it:

-password="${{ secrets.SUPABASE_PASS }}"

Make sure to create a secret SUPABASE_PASS containing the database password in your repository settings.

Commit everything and push your changes to your repository. Once the workflow has been executed, your database schema has been updated and you should see a new profile table in your database.

Recap

Why should I use Flyway?

Changes to your database schema become repeatable. This is useful when setting up new environments (either on supabase.io or locally).
Your database schema evolves alongside your application.
How your database looks like is co-located with the code interacting with it.

What we did:

Retrieved the database connection info from the Database Settings page in the Supabase UI.
Created a simple Flyway SQL migration called migrations/V1__create_table_profile.sql, which creates a profile table.
Added a GitHub workflow with one job called migrate-database that uses Flyway to run all migrations in the migrations directory against a Supabase database.

Hide useQuery

Sebastian Ruhleder — Mon, 12 Apr 2021 16:57:19 +0000

I always wrap React Query's useQuery hook in a custom hook and never use it directly within a component. To see why, let's have a look at an example:

function TodoList() {
  const { data: todos = [] } = useQuery(
    ['todos'],
    () => fetchTodos()
  );

  return (
    <ul>
      {todos.map(todo => (
        <li>{todo}</li>
      )}
    </ul>
  );
}

The TodoList component is quite simple: It fetches a list of to-dos from our backend and renders them within an unordered list. By using useQuery directly, this component has to:

specify a unique query key,
be aware of the fetchTodos() function,
and provide a sensible initial value [] while the request hasn't completed yet.

The component is intended to render a to-do list, yet it is responsible for very technical decisions like these. In contrast, let's encapsulate the use of useQuery in a custom hook:

function TodoList() {
  const todos = useTodos();

  return (
    <ul>
      {todos.map(todo => (
        <li>{todo}</li>
      )}
    </ul>
  );
}

function useTodos() {
  const { data: todos = [] } = useQuery(
    ['todos'],
    () => fetchTodos()
  );
  return todos;
}

By introducing a custom useTodos() hook, we:

provide a layer abstraction by separating what we want to do (get a list of to-dos) from how we do it (by using React Query),
make the list of to-dos reusable throughout our application,
make it possible to easily switch React Query for a different library later on,
and improve the readability of our TodoList component.

The choice of a sensible query key, how a resource is fetched, and the configuration of useQuery's options are implementation details that should always be hidden from components that only want to consume the resource managed by it.

I've used this pattern for quite a while, both in personal projects and at work. It has served me tremendously well. The pattern ties in with and is a concrete instance of Kyle Shevlin's great post useEncapsulation, which I can highly recommend for a more general view on this topic.

Effective Query Keys in React Query

Sebastian Ruhleder — Mon, 12 Apr 2021 12:33:26 +0000

In React Query, every query uses a query key to identify the data it manages. For example, the following query uses the query key ['todos'] to identify a list of to-dos:

const { data: todos } = useQuery(['todos'], () => fetchTodos());

In this post, we will have a look at:

The basic requirements a query key must fulfill.
How to invalidate the cache based on a (partial) query key.
My personal flavor of writing query keys; a few rules of thumb I have used in the past.
How query keys work under the hood.

The Basics

There are some requirements a query key must fulfill:

It must uniquely identify the data managed by the query

React Query uses query keys for caching. Make sure to use query keys that uniquely identify the data you fetch from a server:

useQuery(['todos'], () => fetchTodos());
useQuery(['users'], () => fetchUsers());

It should contain all variables the query function depends on

There are two reasons why:

The variable is necessary to identify the data since it is used to fetch it. The to-dos for two users, who are identified by a userId, can't both use ['todos']. A sensible query key would be ['todos', userId].
useQuery calls the query function and thereby refetches the data whenever the query key changes. Including a variable in a query key is an easy way to automatically trigger a refetch and keep your data up-to-date.

It must be serializable

A query key can be a string or an array of strings, numbers, or even nested objects. However, it must be serializable: It cannot contain cyclic objects or functions.

// ok
useQuery('todos', /* ... */);
useQuery(['todos', todoId], /* ... */);
useQuery(['todos', todoId, { date }], /* ... */);

// not ok!
useQuery([function () {}], /* ... */);

Query keys are hashed deterministically, which means the order of the keys in an object does not matter (whereas the order of elements in an array does!). The following two query keys are identical:

useQuery(['todos', { format, dueToday }], /* ... */);
useQuery(['todos', { dueToday, format }], /* ... */);

The following two query keys are not:

useQuery(['todos', todoId], /* ... */);
useQuery([todoId, 'todos'], /* ... */);

Cache Invalidation

You can invalidate queries matching a partial or an exact query key by using the invalidateQueries method of the QueryClient. This method will mark the matched queries as stale and refetch them automatically if they are in use. Let's consider a simple example:

useQuery(['todos', todoId], () => fetchTodo(todoId));

Imagine this hook is used twice on your page: once for todoId = 1 and once for todoId = 2. Your query cache will contain two query keys (and the data identified by them): ['todos', 1] and ['todos', 2].

You can invalidate a specific to-do by using invalidateQueries with an exact query key:

// only invalidate ['todos', 1]
queryClient.invalidateQueries(['todos', 1]);

Or, you can invalidate both by using the prefix 'todos':

// invalidate both ['todos', 1] and ['todos', 2]
queryClient.invalidateQueries(['todos']);

// you can even omit the array around the 'todos' label
// to achieve the same result
queryClient.invalidateQueries('todos');

Since cache invalidation allows you to use partial query keys to invalidate multiple queries at once, the way you structure your query keys has significant implications on how effectively you can manage data throughout your application.

The Flavor

I've established a set of best practices for myself when defining query keys. This list is by no means comprehensive, and you will find your own rhythm for dealing with query keys. But they might give you a solid foundation.

Go from most descriptive to least descriptive

You should start every query key with a label that identifies the type of data the query manages. For example, if the data describes a to-do (or a list of to-dos), you should start with a label like 'todos'. Since partial query matching is prefix-based, this allows you to invalidate cohesive data easily.

Then, you should sort the variables within the query key from most descriptive (e.g., a todoId, which directly describes a concrete to-do) to least descriptive (e.g., a format). Again, this allows us to make full use of the prefix-based cache invalidation.

Violating this best practice might lead to this:

useQuery(['todos', { format }, todoId], /* ... */);

// how do we invalidate a specific todoId irrespective of
// its format?
queryClient.invalidateQueries(['todos', /* ??? */, todoId]);

Bundle query parameters within an object

Often, I use path and query parameters of the data's URI to guide the query key's layout. Everything on the path gets its own value within the query key, and every attribute-value pair of the query component of a resource is bundled within an object at the end. For example:

// path and query parameters
'/resources/{resourceId}/items/{itemId}?format=XML&available'

// query key
['resources', resourceId, itemId, { format, available }]

Use functions to create query keys

If you reuse a query key, you should define a function that encapsulates its layout and labels. Typos are notoriously hard to debug when invalidating or removing queries, and it's easy to accidentally write ['todo'] instead of ['todos']. For this reason, introduce a central place where you generate your query keys:

const QueryKeys = {
  todos: (todoId) => ['todos', todoId]
};

// ...

useQuery(QueryKeys.todos(todoId), /* ... */);
queryClient.invalidateQueries(QueryKeys.todos(1));

(Shoutout to Tanner Linsley for also recommending this. As @TkDodo has pointed out to me, having a single file for this might lead to some unfortunate copy-paste bugs. The emphasis here is on using functions to generate query keys, not on having only one file.)

Under the Hood

Reading about rules and best practices is one thing. Understanding why they apply (or should be applied) is another. Let's have a look at how query keys are hashed in React Query:

/**
 * Default query keys hash function.
 */
export function hashQueryKey(queryKey: QueryKey): string {
  const asArray = Array.isArray(queryKey) ? queryKey : [queryKey]
  return stableValueHash(asArray)
}

/**
 * Hashes the value into a stable hash.
 */
export function stableValueHash(value: any): string {
  return JSON.stringify(value, (_, val) =>
    isPlainObject(val)
      ? Object.keys(val)
          .sort()
          .reduce((result, key) => {
            result[key] = val[key]
            return result
          }, {} as any)
      : val
  )
}

First, if the query key is a string, it will be wrapped within an array. That means, 'todos' and ['todos'] are essentially the same query key. Second, the hash of a query key is generated by using JSON.stringify.

To achieve a stable hash, the stableValueHash function makes use of the replacer parameter of JSON.stringify. This function is called for every value or key-value pair within the value parameter that needs to be "stringified." In case the value is an object, its keys are sorted. This is the reason why the order of the keys within an object does not matter!

In most cases, you won't need to consult this code when writing query keys. In fact, if you do, your query keys might be too complex. However, looking under the hood of libraries we use every day is an excellent way to engage with them on a deeper level and provides the occasional Aha! moment.

Summary

Query keys:

must uniquely identify the data they describe,
should contain all variables the query function depends on, and
must be serializable.

Cache invalidation:

You can invalidate the query cache with the invalidateQueries function of the QueryClient.
You can use a partial query key or an exact query key to invalidate the cache. Partial query matching is prefix-based.

Best practices:

Go from most descriptive (e.g., a fixed label like 'todos' and a todoId) to least descriptive (e.g., a format or available flag).
Bundle query parameters within an object and use the path of your resource to guide the query key's layout.
Write functions to generate query keys consistently.

Under the hood:

String query keys are wrapped in an array. 'todos' and ['todos'] are identical query keys.
Query keys are hashed (and compared) via their JSON.stringify serialization. Keys in objects are sorted.