Auth

Creating a Supabase client for SSR

Configure your Supabase client to use cookies

To use Server-Side Rendering (SSR) with Supabase, you need to configure your Supabase client to use cookies. The @supabase/ssr package helps you do this for JavaScript/TypeScript applications.

Install

Install the @supabase/supabase-js and @supabase/ssr helper packages:

1
npm install @supabase/supabase-js @supabase/ssr

Set environment variables

Create a .env.local file in the project root directory. In the file, set the project's Supabase URL and Key:

Project URL
Publishable key
Anon key

You can also get the Project URL and key from the project's Connect dialog.

Read the API keys docs for a full explanation of all key types and their uses.

1
NEXT_PUBLIC_SUPABASE_URL=supabase_project_url
2
NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY=supabase_publishable_key

Create a client

You need setup code to configure a Supabase client to use cookies. Once you have the utility code, you can use the createClient utility functions to get a properly configured Supabase client.

Use the browser client in code that runs on the browser, and the server client in code that runs on the server.

Write utility functions to create Supabase clients

To access Supabase from a Next.js app, you need 2 types of Supabase clients:

  1. Client Component client - To access Supabase from Client Components, which run in the browser.
  2. Server Component client - To access Supabase from Server Components, Server Actions, and Route Handlers, which run only on the server.

Since Next.js Server Components can't write cookies, you need a Proxy to refresh expired Auth tokens and store them.

The Proxy is responsible for:

  1. Refreshing the Auth token by calling supabase.auth.getClaims().
  2. Passing the refreshed Auth token to Server Components, so they don't attempt to refresh the same token themselves. This is accomplished with request.cookies.set.
  3. Passing the refreshed Auth token to the browser, so it replaces the old token. This is accomplished with response.cookies.set.

Create a lib/supabase folder at the root of your project, or inside the ./src folder if you are using one, with a file for each type of client. Then copy the lib utility functions for each client type.

1
import { createBrowserClient } from '@supabase/ssr'
2
3
export function createClient() {
4
  return createBrowserClient(
5
    process.env.NEXT_PUBLIC_SUPABASE_URL!,
6
    process.env.NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY!
7
  )
8
}
View source

Hook up proxy

The code adds a matcher so the Proxy doesn't run on routes that don't access Supabase.

1
import { type NextRequest } from "next/server"
2
import { updateSession } from "@/lib/supabase/proxy"
3
4
export async function proxy(request: NextRequest) {
5
  return await updateSession(request)
6
}
7
8
export const config = {
9
  matcher: [
10
    /*
11
     * Match all request paths except for the ones starting with:
12
     * - _next/static (static files)
13
     * - _next/image (image optimization files)
14
     * - favicon.ico (favicon file)
15
     * Feel free to modify this pattern to include more paths.
16
     */
17
    "/((?!_next/static|_next/image|favicon.ico|.*\\.(?:svg|png|jpg|jpeg|gif|webp)$).*)",
18
  ],
19
}
View source

Congratulations

You're done! To recap, you've successfully:

  • Called Supabase from a Server Action.
  • Called Supabase from a Server Component.
  • Set up a Supabase client utility to call Supabase from a Client Component. You can use this if you need to call Supabase from a Client Component, for example to set up a realtime subscription.
  • Set up Proxy to automatically refresh the Supabase Auth session.

You can now use any Supabase features from your client or server code!

Next steps