nextjs-supabase-auth · diff
git:20260218.048cbae to git:20260311.27f086e
48 added, 38 removed. Audit A to A.
---
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)
+ description: Integrate Supabase Auth with Next.js App Router using middleware, callback handling, protected routes, and server/client client boundaries.
+ metadata:
+ owner: "skills-steward"
+ last_updated: 2026-02-18
+ status: "active"
+ upstream:
+ repo: "supabase/agent-skills"
+ related_guides:
+ - "https://supabase.com/docs/guides/auth/server-side/nextjs"
+ - "https://supabase.com/docs/guides/auth"
+ license: MIT
---
# 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
+ Use this skill for authentication work in Next.js App Router with Supabase Auth.
- ## Patterns
+ ## When to Apply
- ### Supabase Client Setup
+ Use this skill when:
- Create properly configured Supabase clients for different contexts
+ - Implementing login/signup/logout and session flows
+ - Protecting routes with middleware
+ - Handling auth callback exchanges
+ - Wiring auth checks in Server Components, Server Actions, and route handlers
+ - Debugging cookie/session desync between server and client
- ### Auth Middleware
+ Do not use this skill when:
- Protect routes and refresh sessions in middleware
+ - The task is primarily query/index/schema optimization (use `supabase-postgres-best-practices`)
+ - The task is UI-only and does not change auth behavior
- ### Auth Callback Route
+ ## Core Rules
- Handle OAuth callback and exchange code for session
+ 1. Use `@supabase/ssr` patterns for App Router integration.
+ 2. Use `@/lib/supabase/server` for server-side code and `@/lib/supabase/client` for client-side code.
+ 3. Use middleware to refresh and enforce session state on protected routes.
+ 4. Do not manually store or forward auth tokens in client code.
+ 5. Use Server Actions (or secure route handlers) for privileged auth operations.
+ 6. Maintain RLS assumptions; do not bypass policy boundaries.
- ## Anti-Patterns
+ ## Workflow
- ### ❌ getSession in Server Components
+ 1. Identify execution boundary first (server component, client component, middleware, action, or route handler).
+ 2. Ensure the correct Supabase client is used for that boundary.
+ 3. Verify middleware coverage for protected routes.
+ 4. Verify callback handling exchanges auth code/session correctly.
+ 5. Validate auth checks before sensitive reads/writes.
+ 6. Verify end-to-end login/logout/session refresh behavior.
- ### ❌ Auth State in Client Without Listener
+ ## Checklist
- ### ❌ Storing Tokens Manually
+ - [ ] Server code imports `@/lib/supabase/server`
+ - [ ] Client code imports `@/lib/supabase/client`
+ - [ ] Protected paths are covered by auth middleware
+ - [ ] Callback route/session exchange is correctly handled
+ - [ ] No service role keys in client-side code
+ - [ ] No manual token persistence logic added
- ## Related Skills
+ ## Common Anti-Patterns
- Works well with: `nextjs-app-router`, `supabase-backend`
+ - Using browser clients in server actions
+ - Using server clients in client components
+ - Calling `getSession` blindly in server render paths without user validation
+ - Storing JWTs manually in localStorage/cookies