Integrate Supabase Auth with Next.js App Router

This skill covers expert integration of Supabase Auth with the Next.js App Router. Its capabilities are named as nextjs-auth, supabase-auth-nextjs, auth-middleware, and auth-callback, and it lists nextjs-app-router and supabase-backend as required companion skills.

It documents five patterns with code. Supabase client setup creates a browser client with createBrowserClient in lib/supabase/client.ts and a server client with createServerClient in lib/supabase/server.ts, the latter wiring cookie getAll/setAll functions to Next.js's cookies(). Auth middleware protects routes and refreshes sessions:

// middleware.ts
export async function middleware(request: NextRequest) {
  let response = NextResponse.next({ request })

  const supabase = createServerClient(
    process.env.NEXT_PUBLIC_SUPABASE_URL!,
    process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY!,
    {
      cookies: {
        getAll() {
          return request.cookies.getAll()
        },
        setAll(cookiesToSet) {
          cookiesToSet.forEach(({ name, value, options }) => {
            response.cookies.set(name, value, options)
          })
        },
      },
    }
  )

  // Refresh session if expired
  const { data: { user } } = await supabase.auth.getUser()

  // Protect dashboard routes
  if (request.nextUrl.pathname.startsWith('/dashboard') && !user) {
    return NextResponse.redirect(new URL('/login', request.url))
  }

  return response
}

An auth callback route at app/auth/callback/route.ts exchanges an OAuth code for a session with exchangeCodeForSession, redirecting to the next param on success or to an error page otherwise. Server Action auth handles signIn (via signInWithPassword) and signOut in app/actions/auth.ts, calling revalidatePath('/', 'layout') and redirect after each. Getting the user in a Server Component calls supabase.auth.getUser() and redirects to /login when there is none.

Its validation checks flag concrete mistakes with a severity and fix: using getSession() for auth checks is an ERROR because it doesn't verify the JWT, and getUser() should be used for security-critical checks instead; OAuth configured without a callback route at app/auth/callback/route.ts is an ERROR; using a browser client in a server context is an ERROR, fixed by importing createServerClient from @supabase/ssr instead. WARNING-level checks cover missing middleware.ts for route protection, a hardcoded localhost redirect URL (use window.location.origin or NEXT_PUBLIC_SITE_URL instead), an auth call without error handling (destructure { data, error } and handle the error), an auth action without revalidatePath (stale cached auth state), and client-only route protection, which causes a flash of protected content and should move to middleware instead.

For collaboration, it delegates database/RLS/query/table work to supabase-backend, route/page/component/layout work to nextjs-app-router, deploy/production/Vercel work to vercel-deployment, and UI/form/button/design work to a frontend skill. It documents two multi-skill workflows: a full auth stack (database setup via supabase-backend, then auth implementation, then route protection via nextjs-app-router, then deployment config via vercel-deployment) and a protected SaaS (user authentication, then customer sync via stripe-integration, then subscription gating via supabase-backend).

Use it when the task involves Supabase Auth with Next.js, authentication in Next.js generally, login with Supabase, auth middleware, protected routes, an auth callback, or session management.

Inputs are the Next.js App Router project structure and Supabase project credentials (NEXT_PUBLIC_SUPABASE_URL, NEXT_PUBLIC_SUPABASE_ANON_KEY). Outputs are the browser and server Supabase client files, a middleware.ts for route protection and session refresh, an OAuth callback route, Server Actions for sign-in and sign-out, and Server Components that read the authenticated user, plus a validation pass flagging insecure or stale-cache-prone auth patterns.

It is for Next.js developers integrating Supabase Auth who need App Router-correct patterns for client setup, middleware-based route protection, OAuth callbacks, and Server Action-based sign-in and sign-out, along with concrete fixes for the common mistakes in each.