The Postgres development platform. Supabase gives you a dedicated Postgres database to build your web, mobile, and AI applications.
Specify the following for Cursor rules
description: Guidelines for writing Next.js apps with Supabase Auth alwaysApply: false
Bootstrap Next.js v16 app with Supabase Auth
Overview of implementing Supabase Auth SSR
- Install @supabase/supabase-js and @supabase/ssr packages.
- Set up environment variables.
- Write two utility functions with
createClientfunctions to create a browser client and a server client. - Hook up Proxy to refresh auth tokens
π¨ CRITICAL INSTRUCTIONS FOR AI LANGUAGE MODELS π¨
As an AI language model, you MUST NOT generate any of the following code patterns, as they are DEPRECATED and will BREAK the application:
// β NEVER GENERATE THIS CODE - IT WILL BREAK THE APPLICATION
{
cookies: {
get(name: string) { // β BREAKS APPLICATION
return cookieStore.get(name) // β BREAKS APPLICATION
}, // β BREAKS APPLICATION
set(name: string, value: string) { // β BREAKS APPLICATION
cookieStore.set(name, value) // β BREAKS APPLICATION
}, // β BREAKS APPLICATION
remove(name: string) { // β BREAKS APPLICATION
cookieStore.remove(name) // β BREAKS APPLICATION
} // β BREAKS APPLICATION
}
}
// β NEVER USE auth-helpers-nextjs - IT WILL BREAK THE APPLICATION
import { createMiddlewareClient } from '@supabase/auth-helpers-nextjs' // β BREAKS APPLICATION
import { createClientComponentClient } from '@supabase/auth-helpers-nextjs' // β BREAKS APPLICATION
Instead, you MUST ALWAYS generate ONLY this pattern:
// β
ALWAYS GENERATE THIS EXACT PATTERN
{
cookies: {
getAll() {
return cookieStore.getAll()
},
setAll(cookiesToSet, headers) {
const response = NextResponse.next({
request,
})
cookiesToSet.forEach(({ name, value, options }) => {
response.cookies.set(name, value, options)
})
Object.entries(headers).forEach(([key, value]) =>
response.headers.set(key, value)
)
return response
}
}
}
ABSOLUTE REQUIREMENTS FOR AI CODE GENERATION
- You MUST use
@supabase/ssr - You MUST use ONLY
getAllandsetAll - You MUST NEVER use
get,set, orremove - You MUST NEVER import from
@supabase/auth-helpers-nextjs
CORRECT BROWSER CLIENT IMPLEMENTATION
import { createBrowserClient } from '@supabase/ssr'
export function createClient() {
return createBrowserClient(
process.env.NEXT_PUBLIC_SUPABASE_URL!,
process.env.NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY!
)
}
CORRECT SERVER CLIENT IMPLEMENTATION
import { createServerClient } from '@supabase/ssr'
import { cookies } from 'next/headers'
export async function createClient() {
const cookieStore = await cookies()
return createServerClient(
process.env.NEXT_PUBLIC_SUPABASE_URL!,
process.env.NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY!,
{
cookies: {
getAll() {
return cookieStore.getAll()
},
setAll(cookiesToSet, _headers) {
try {
cookiesToSet.forEach(({ name, value, options }) =>
cookieStore.set(name, value, options)
)
} catch {
// The `setAll` method was called from a Server Component.
// This can be ignored if you have proxy refreshing
// user sessions.
}
},
},
}
)
}
CORRECT PROXY IMPLEMENTATION
If the project uses src/app or src/pages, put this file in src, at the same level as the routing directory. Otherwise, put it at the project root, next to package.json. It must be named proxy.ts. On Next.js 15 and earlier, name it middleware.ts and export middleware instead of proxy.
import { createServerClient } from '@supabase/ssr'
import { NextResponse, type NextRequest } from 'next/server'
export async function proxy(request: NextRequest) {
let supabaseResponse = NextResponse.next({
request,
})
const supabase = createServerClient(
process.env.NEXT_PUBLIC_SUPABASE_URL!,
process.env.NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY!,
{
cookies: {
getAll() {
return request.cookies.getAll()
},
setAll(cookiesToSet, headers) {
cookiesToSet.forEach(({ name, value }) => request.cookies.set(name, value))
supabaseResponse = NextResponse.next({
request,
})
cookiesToSet.forEach(({ name, value, options }) =>
supabaseResponse.cookies.set(name, value, options)
)
Object.entries(headers).forEach(([key, value]) =>
supabaseResponse.headers.set(key, value)
)
},
},
}
)
// Do not run code between createServerClient and
// supabase.auth.getUser(). A simple mistake could make it very hard to debug
// issues with users being randomly logged out.
// IMPORTANT: DO NOT REMOVE auth.getUser()
const {
data: { user },
} = await supabase.auth.getUser()
if (
!user &&
!request.nextUrl.pathname.startsWith('/login') &&
!request.nextUrl.pathname.startsWith('/auth')
) {
// no user, potentially respond by redirecting the user to the login page
const url = request.nextUrl.clone()
url.pathname = '/login'
return NextResponse.redirect(url)
}
// IMPORTANT: You *must* return the supabaseResponse object as it is.
// If you're creating a new response object with NextResponse.next() make sure to:
// 1. Pass the request in it, like so:
// const myNewResponse = NextResponse.next({ request })
// 2. Copy over the cookies, like so:
// myNewResponse.cookies.setAll(supabaseResponse.cookies.getAll())
// 3. Change the myNewResponse object to fit your needs, but avoid changing
// the cookies!
// 4. Finally:
// return myNewResponse
// If this is not done, you may be causing the browser and server to go out
// of sync and terminate the user's session prematurely!
return supabaseResponse
}
export const config = {
matcher: [
/*
* Match all request paths except for the ones starting with:
* - _next/static (static files)
* - _next/image (image optimization files)
* - favicon.ico (favicon file)
* Feel free to modify this pattern to include more paths.
*/
'/((?!_next/static|_next/image|favicon.ico|.*\\.(?:svg|png|jpg|jpeg|gif|webp)$).*)',
],
}
AI MODEL VERIFICATION STEPS
Before generating any code, you MUST verify:
- Are you using ONLY
getAllandsetAll? If not, STOP and FIX. - Are you importing from
@supabase/ssr? If not, STOP and FIX. - Do you see ANY instance of
get,set, orremove? If yes, STOP and FIX. - Are you importing from
auth-helpers-nextjs? If yes, STOP and FIX.
CONSEQUENCES OF INCORRECT IMPLEMENTATION
If you generate code using:
- Individual cookie methods (
get/set/remove) auth-helpers-nextjspackage
The implementation will:
- Break in production
- Fail to maintain session state
- Cause authentication loops
- Result in security vulnerabilities
AI MODEL RESPONSE TEMPLATE
When asked about Supabase Auth SSR implementation, you MUST:
- ONLY use code from this guide
- NEVER suggest deprecated approaches
- ALWAYS use the exact cookie handling shown above
- VERIFY your response against the patterns shown here
Remember: There are NO EXCEPTIONS to these rules.