home / skills / xfstudio / skills / nextjs-supabase-auth

nextjs-supabase-auth skill

safe

This skill helps you securely integrate Supabase Auth with Next.js App Router, protecting routes and handling middleware and callbacks efficiently.

npx playbooks add skill xfstudio/skills --skill nextjs-supabase-auth

Review the files below or copy the command above to add this skill to your agents.

Files (1)

SKILL.md

1.4 KB

---
name: nextjs-supabase-auth
description: "Expert integration of Supabase Auth with Next.js App Router Use when: supabase auth next, authentication next.js, login supabase, auth middleware, protected route."
source: vibeship-spawner-skills (Apache 2.0)
---

# Next.js + Supabase Auth

You are an expert in integrating Supabase Auth with Next.js App Router.
You understand the server/client boundary, how to handle auth in middleware,
Server Components, Client Components, and Server Actions.

Your core principles:
1. Use @supabase/ssr for App Router integration
2. Handle tokens in middleware for protected routes
3. Never expose auth tokens to client unnecessarily
4. Use Server Actions for auth operations when possible
5. Understand the cookie-based session flow

## Capabilities

- nextjs-auth
- supabase-auth-nextjs
- auth-middleware
- auth-callback

## Requirements

- nextjs-app-router
- supabase-backend

## Patterns

### Supabase Client Setup

Create properly configured Supabase clients for different contexts

### Auth Middleware

Protect routes and refresh sessions in middleware

### Auth Callback Route

Handle OAuth callback and exchange code for session

## Anti-Patterns

### ❌ getSession in Server Components

### ❌ Auth State in Client Without Listener

### ❌ Storing Tokens Manually

## Related Skills

Works well with: `nextjs-app-router`, `supabase-backend`

Overview

This skill provides expert patterns and ready guidance for integrating Supabase Auth with the Next.js App Router. It focuses on secure, server-first authentication flows that use @supabase/ssr, middleware-based protection, and Server Actions to avoid leaking tokens to the client. Use it to implement reliable sign-in, session refresh, and OAuth callbacks with minimal boilerplate.

How this skill works

The skill shows how to create context-specific Supabase clients: server clients for Server Components and middleware, and limited client-side instances only when needed. It explains using @supabase/ssr to read and set cookie sessions in the App Router, handling tokens and refreshing sessions inside middleware, and delegating auth operations to Server Actions to keep secrets on the server.

When to use it

Protect App Router routes and refresh sessions at the edge or server middleware
Implement OAuth callbacks that exchange codes for sessions securely
Avoid exposing auth tokens to client code while still supporting client-side UI
Migrate an existing Next.js app to server-first Supabase auth patterns
Set up sign-in, sign-out, and session renewal using Server Actions

Best practices

Use @supabase/ssr in server contexts to read/write cookie-based sessions
Perform token handling and refresh logic inside middleware, not client code
Use Server Actions for login/logout flows to keep secrets off the client
Never store raw access or refresh tokens in client-visible storage
Avoid calling getSession from Server Components; prefer server client helpers

Example use cases

Middleware that blocks unauthenticated users and refreshes expired sessions
OAuth callback route that exchanges code for a Supabase session and sets cookies
Server Action sign-in that validates credentials and returns minimal client-safe state
Protected admin dashboard rendered as a Server Component with server-side session checks
Client Component that displays user UI but relies on server-provided session data

FAQ

Can I call getSession in a Server Component?

Avoid getSession in Server Components; use a server-configured Supabase client or @supabase/ssr helpers to read session from cookies instead.

Where should token refresh logic live?

Implement refresh logic in middleware or server actions so tokens are rotated server-side and never exposed unnecessarily to the client.