nextjs-supabase-auth

Next.js + Supabase Auth Authentication Integration

Skill Overview

nextjs-supabase-auth is an expert-level AI skill focused on integrating Supabase authentication into the Next.js App Router. It helps you handle the server/client boundary, authentication in middleware, login logic in Server Components, and login logic in Server Actions.

Use Cases

Next.js App Router projects that need user login — When you are using the Next.js 13+ App Router architecture and want to integrate Supabase as the authentication provider

Protected routes that require server-side rendering — When your app needs to render different content based on the user’s login state, and the verification must be done on the server

Handling OAuth login and session management — When you need to implement third-party login (e.g., Google, GitHub) and ensure the session is correctly refreshed and maintained on the server

Core Features

Supabase SSR client configuration — Create the correct Supabase client instance for different runtime contexts (server components, client components, route handlers, Server Actions) to ensure the proper use of the @supabase/ssr package.

Authentication middleware and route protection — Implement automatic session refresh and route protection in Next.js middleware. This ensures that unauthenticated users cannot access protected pages while preventing tokens from being exposed to the client.

OAuth callbacks and login via Server Actions — Handle the full flow of exchanging an OAuth authorization code for a session, and support server-side login/logout operations through Server Actions.

Common Questions

How to integrate Supabase Auth with the Next.js App Router?

Use the @supabase/ssr package to create different client instances based on context. In Server Components, use createServerClient; in Route Handlers, pass cookies; in the client, use createBrowserClient. This skill guides you on how to correctly distinguish and create clients for each scenario.

How is session refreshing in Supabase automatically handled in Next.js?

In Next.js middleware (middleware.ts), calling supabase.auth.getSession() automatically refreshes expired sessions. This skill emphasizes placing the refresh logic in middleware rather than in components, ensuring that requests to all protected routes automatically update the session in cookies.

Why can’t you use getSession directly in Server Components?

Server Components execute during rendering, while getSession needs to read session information from cookies. The correct approach is to handle session refreshing in middleware ahead of time, or use a helper function to read the session from cookies and pass it to components. This skill helps you avoid common server-side authentication anti-patterns.