Setting up Server-Side Auth for Next.js

Next.js comes in two flavors: the App Router and the Pages Router. You can set up Server-Side Auth with either strategy. You can even use both in the same application.

Install Supabase packages

Install the @supabase/supabase-js package and the helper @supabase/ssr package.


_10npm install @supabase/supabase-js @supabase/ssr

Set up environment variables

Create a .env.local file in your project root directory.

Fill in your NEXT_PUBLIC_SUPABASE_URL and NEXT_PUBLIC_SUPABASE_ANON_KEY:

Project URL

Anon key

.env.local


_10NEXT_PUBLIC_SUPABASE_URL=<your_supabase_project_url>
_10NEXT_PUBLIC_SUPABASE_ANON_KEY=<your_supabase_anon_key>

Write utility functions to create Supabase clients

To access Supabase from your Next.js app, you need 3 types of Supabase clients:

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

Create a utils/supabase folder with a file for each type of client. Then copy the utility functions for each client type.

utils/supabase/client.ts

utils/supabase/server.ts

utils/supabase/actions.ts


_10import { createBrowserClient } from '@supabase/ssr'
_10
_10export function createClient() {
_10  return createBrowserClient(
_10    process.env.NEXT_PUBLIC_SUPABASE_URL!,
_10    process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY!
_10  )
_10}

Hook up middleware

Create a middleware.ts file at the root of your project.

Since Server Components can't write cookies, you need middleware to refresh expired Auth tokens and store them. Copy the code to refresh the Auth token whenever it's expired.

Add a matcher so the middleware doesn't run on routes that don't access Supabase.

Be careful when protecting pages. The server gets the user session from the cookies, which can be spoofed by anyone.

Always use supabase.auth.getUser() to protect pages and user data.

Never trust supabase.auth.getSession() inside server code such as middleware. It isn't guaranteed to revalidate the Auth token.

It's safe to trust getUser() because it sends a request to the Supabase Auth server every time to revalidate the Auth token.

middleware.ts


_73import { createServerClient, type CookieOptions } from '@supabase/ssr'
_73import { NextResponse, type NextRequest } from 'next/server'
_73
_73export async function middleware(request: NextRequest) {
_73  let response = NextResponse.next({
_73    request: {
_73      headers: request.headers,
_73    },
_73  })
_73
_73  const supabase = createServerClient(
_73    process.env.NEXT_PUBLIC_SUPABASE_URL!,
_73    process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY!,
_73    {
_73      cookies: {
_73        get(name: string) {
_73          return request.cookies.get(name)?.value
_73        },
_73        set(name: string, value: string, options: CookieOptions) {
_73          request.cookies.set({
_73            name,
_73            value,
_73            ...options,
_73          })
_73          response = NextResponse.next({
_73            request: {
_73              headers: request.headers,
_73            },
_73          })
_73          response.cookies.set({
_73            name,
_73            value,
_73            ...options,
_73          })
_73        },
_73        remove(name: string, options: CookieOptions) {
_73          request.cookies.set({
_73            name,
_73            value: '',
_73            ...options,
_73          })
_73          response = NextResponse.next({
_73            request: {
_73              headers: request.headers,
_73            },
_73          })
_73          response.cookies.set({
_73            name,
_73            value: '',
_73            ...options,
_73          })
_73        },
_73      },
_73    }
_73  )
_73
_73  await supabase.auth.getUser()
_73
_73  return response
_73}
_73
_73export const config = {
_73  matcher: [
_73    /*
_73     * Match all request paths except for the ones starting with:
_73     * - _next/static (static files)
_73     * - _next/image (image optimization files)
_73     * - favicon.ico (favicon file)
_73     * Feel free to modify this pattern to include more paths.
_73     */
_73    '/((?!_next/static|_next/image|favicon.ico).*)',
_73  ],
_73}

Create a login page

Create a login page for your app. Use a Server Action to call the Supabase signup function.

Since Supabase is being called from an Action, use the client defined in @/utils/supabase/actions.ts.

app/login/page.tsx

app/login/actions.ts

app/error/page.tsx


_14import { login, signup } from './actions'
_14
_14export default function LoginPage() {
_14  return (
_14    <form>
_14      <label htmlFor="email">Email:</label>
_14      <input id="email" name="email" type="email" required />
_14      <label htmlFor="password">Password:</label>
_14      <input id="password" name="password" type="password" required />
_14      <button formAction={login}>Log in</button>
_14      <button formAction={signup}>Sign up</button>
_14    </form>
_14  )
_14}

Change the Auth confirmation path

If you have email confirmation turned on (the default), a new user will receive an email confirmation after signing up.

Change the email template to support a server-side authentication flow.

Go to the Auth templates page in your dashboard. In each email template, change {{ .ConfirmationURL }} to {{ .SiteURL }}/auth/callback?token_hash={{ .TokenHash }}&type=signup.

Create a route handler for Auth confirmation

Create a Route Handler for auth/callback. When a user clicks their confirmation email link, exchange their secure code for an Auth token.

Since this is a Router Handler, use the Supabase client from @/utils/supabase/actions.ts.

app/auth/callback/route.ts


_36import { type EmailOtpType } from '@supabase/supabase-js'
_36import { cookies } from 'next/headers'
_36import { type NextRequest, NextResponse } from 'next/server'
_36
_36import { createClient } from '@/utils/supabase/actions'
_36
_36export async function GET(request: NextRequest) {
_36  const cookieStore = cookies()
_36
_36  const { searchParams } = new URL(request.url)
_36  const token_hash = searchParams.get('token_hash')
_36  const type = searchParams.get('type') as EmailOtpType | null
_36  const next = searchParams.get('next') ?? '/'
_36
_36  const redirectTo = request.nextUrl.clone()
_36  redirectTo.pathname = next
_36  redirectTo.searchParams.delete('token_hash')
_36  redirectTo.searchParams.delete('type')
_36
_36  if (token_hash && type) {
_36    const supabase = createClient(cookieStore)
_36
_36    const { error } = await supabase.auth.verifyOtp({
_36      type,
_36      token_hash,
_36    })
_36    if (!error) {
_36      redirectTo.searchParams.delete('next')
_36      return NextResponse.redirect(redirectTo)
_36    }
_36  }
_36
_36  // return the user to an error page with some instructions
_36  redirectTo.pathname = '/error'
_36  return NextResponse.redirect(redirectTo)
_36}

Access user info from Server Component

Server Components can read cookies, so you can get the Auth status and user info.

Since you're calling Supabase from a Server Component, use the client created in @/utils/supabase/server.ts.

Create a private page that users can only access if they're logged in. The page displays their email.

Be careful when protecting pages. The server gets the user session from the cookies, which can be spoofed by anyone.

Always use supabase.auth.getUser() to protect pages and user data.

Never trust supabase.auth.getSession() inside Server Components. It isn't guaranteed to revalidate the Auth token.

It's safe to trust getUser() because it sends a request to the Supabase Auth server every time to revalidate the Auth token.

app/private/page.tsx


_16import { cookies } from 'next/headers'
_16import { redirect } from 'next/navigation'
_16
_16import { createClient } from '@/utils/supabase/server'
_16
_16export default async function PrivatePage() {
_16  const cookieStore = cookies()
_16  const supabase = createClient(cookieStore)
_16
_16  const { data, error } = await supabase.auth.getUser()
_16  if (error || !data?.user) {
_16    redirect('/')
_16  }
_16
_16  return <p>Hello {data.user.email}</p>
_16}

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
Set up middleware to automatically refresh the Supabase Auth session

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

FAQ

Edit this page on GitHub

Product

Data API

Development Cycle

Client Library Reference

Resources

Setting up Server-Side Auth for Next.js

Install Supabase packages

Set up environment variables

Project URL

Anon key

Write utility functions to create Supabase clients

Hook up middleware

Create a login page

Change the Auth confirmation path

Create a route handler for Auth confirmation

Access user info from Server Component

Congratulations

FAQ

Setting up Server-Side Auth for Next.js

Install Supabase packages

Set up environment variables

Project URL

Anon key

Write utility functions to create Supabase clients

Hook up middleware

Create a login page

Change the Auth confirmation path

Create a route handler for Auth confirmation

Access user info from Server Component

Congratulations#

FAQ#

Congratulations

FAQ