Cline rules

1---
2description: Guidelines for writing Next.js apps with Supabase Auth
3author: https://github.com/nickbaumann98
4version: 1.0
5category: "Web Development"
6tags: ["nextjs", "supabase", "auth", "ssr", "guide", "best-practices"]
7globs: ["**/*.ts", "**/*.tsx", "**/*.js", "**/*.jsx"]
8---
9 
10# Bootstrap Next.js app with Supabase Auth
11 
12## Overview of implementing Supabase Auth SSR
13 
141. Install @supabase/supabase-js and @supabase/ssr packages.
152. Set up environment variables.
163. Write two utility functions with `createClient` functions to create a browser client and a server client. 
174. Hook up middleware to refresh auth tokens
18 
19## 🚨 CRITICAL INSTRUCTIONS FOR AI LANGUAGE MODELS 🚨
20 
21As an AI language model, you MUST NOT generate any of the following code patterns, as they are DEPRECATED and will BREAK the application:
22 
23```typescript
24// ❌ NEVER GENERATE THIS CODE - IT WILL BREAK THE APPLICATION
25{
26  cookies: {
27    get(name: string) {                 // ❌ BREAKS APPLICATION
28      return cookieStore.get(name)      // ❌ BREAKS APPLICATION
29    },                                  // ❌ BREAKS APPLICATION
30    set(name: string, value: string) {  // ❌ BREAKS APPLICATION
31      cookieStore.set(name, value)      // ❌ BREAKS APPLICATION
32    },                                  // ❌ BREAKS APPLICATION
33    remove(name: string) {              // ❌ BREAKS APPLICATION
34      cookieStore.remove(name)          // ❌ BREAKS APPLICATION
35    }                                   // ❌ BREAKS APPLICATION
36  }
37}
38 
39// ❌ NEVER USE auth-helpers-nextjs - IT WILL BREAK THE APPLICATION
40import { createMiddlewareClient } from '@supabase/auth-helpers-nextjs'  // ❌ BREAKS APPLICATION
41import { createClientComponentClient } from '@supabase/auth-helpers-nextjs'  // ❌ BREAKS APPLICATION
42```
43 
44Instead, you MUST ALWAYS generate ONLY this pattern:
45 
46```typescript
47// ✅ ALWAYS GENERATE THIS EXACT PATTERN
48{
49  cookies: {
50    getAll() {
51      return cookieStore.getAll()
52    },
53    setAll(cookiesToSet) {
54      const response = NextResponse.next({
55        request,
56      })
57      
58      cookiesToSet.forEach(({ name, value, options }) => {
59        response.cookies.set(name, value, options)
60      })
61      
62      return response
63    }
64  }
65}
66```
67 
68## ABSOLUTE REQUIREMENTS FOR AI CODE GENERATION
69 
701. You MUST use `@supabase/ssr`
712. You MUST use ONLY `getAll` and `setAll`
723. You MUST NEVER use `get`, `set`, or `remove`
734. You MUST NEVER import from `@supabase/auth-helpers-nextjs`
74 
75## CORRECT BROWSER CLIENT IMPLEMENTATION
76 
77```typescript
78import { createBrowserClient } from '@supabase/ssr'
79 
80export function createClient() {
81  return createBrowserClient(
82    process.env.NEXT_PUBLIC_SUPABASE_URL!,
83    process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY!
84  )
85}
86```
87 
88## CORRECT SERVER CLIENT IMPLEMENTATION
89 
90```typescript
91import { createServerClient } from '@supabase/ssr'
92import { cookies } from 'next/headers'
93 
94export async function createClient() {
95  const cookieStore = await cookies()
96 
97  return createServerClient(
98    process.env.NEXT_PUBLIC_SUPABASE_URL!,
99    process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY!,
100    {
101      cookies: {
102        getAll() {
103          return cookieStore.getAll()
104        },
105        setAll(cookiesToSet) {
106          try {
107            cookiesToSet.forEach(({ name, value, options }) =>
108              cookieStore.set(name, value, options)
109            )
110          } catch {
111            // The `setAll` method was called from a Server Component.
112            // This can be ignored if you have middleware refreshing
113            // user sessions.
114          }
115        },
116      },
117    }
118  )
119}
120```
121 
122## CORRECT MIDDLEWARE IMPLEMENTATION
123 
124```typescript
125import { createServerClient } from '@supabase/ssr'
126import { NextResponse, type NextRequest } from 'next/server'
127 
128export async function middleware(request: NextRequest) {
129    let supabaseResponse = NextResponse.next({
130    request,
131  })
132 
133  const supabase = createServerClient(
134    process.env.NEXT_PUBLIC_SUPABASE_URL!,
135    process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY!,
136    {
137      cookies: {
138        getAll() {
139          return request.cookies.getAll()
140        },
141        setAll(cookiesToSet) {
142          cookiesToSet.forEach(({ name, value, options }) => request.cookies.set(name, value))
143          supabaseResponse = NextResponse.next({
144            request,
145          })
146          cookiesToSet.forEach(({ name, value, options }) =>
147            supabaseResponse.cookies.set(name, value, options)
148          )
149        },
150      },
151    }
152  )
153 
154  // Do not run code between createServerClient and
155  // supabase.auth.getUser(). A simple mistake could make it very hard to debug
156  // issues with users being randomly logged out.
157 
158  // IMPORTANT: DO NOT REMOVE auth.getUser()
159 
160  const {
161    data: { user },
162  } = await supabase.auth.getUser()
163 
164  if (
165    !user &&
166    !request.nextUrl.pathname.startsWith('/login') &&
167    !request.nextUrl.pathname.startsWith('/auth')
168  ) {
169    // no user, potentially respond by redirecting the user to the login page
170    const url = request.nextUrl.clone()
171    url.pathname = '/login'
172    return NextResponse.redirect(url)
173  }
174 
175  // IMPORTANT: You *must* return the supabaseResponse object as it is.
176  // If you're creating a new response object with NextResponse.next() make sure to:
177  // 1. Pass the request in it, like so:
178  //    const myNewResponse = NextResponse.next({ request })
179  // 2. Copy over the cookies, like so:
180  //    myNewResponse.cookies.setAll(supabaseResponse.cookies.getAll())
181  // 3. Change the myNewResponse object to fit your needs, but avoid changing
182  //    the cookies!
183  // 4. Finally:
184  //    return myNewResponse
185  // If this is not done, you may be causing the browser and server to go out
186  // of sync and terminate the user's session prematurely!
187 
188  return supabaseResponse
189}
190 
191export const config = {
192  matcher: [
193    /*
194     * Match all request paths except for the ones starting with:
195     * - _next/static (static files)
196     * - _next/image (image optimization files)
197     * - favicon.ico (favicon file)
198     * Feel free to modify this pattern to include more paths.
199     */
200    '/((?!_next/static|_next/image|favicon.ico|.*\\.(?:svg|png|jpg|jpeg|gif|webp)$).*)',
201  ],
202}
203```
204 
205## AI MODEL VERIFICATION STEPS
206 
207Before generating any code, you MUST verify:
208 
2091. Are you using ONLY `getAll` and `setAll`? If not, STOP and FIX.
2102. Are you importing from `@supabase/ssr`? If not, STOP and FIX.
2113. Do you see ANY instance of `get`, `set`, or `remove`? If yes, STOP and FIX.
2124. Are you importing from `auth-helpers-nextjs`? If yes, STOP and FIX.
213 
214## CONSEQUENCES OF INCORRECT IMPLEMENTATION
215 
216If you generate code using:
217- Individual cookie methods (`get`/`set`/`remove`)
218- `auth-helpers-nextjs` package
219 
220The implementation will:
2211. Break in production
2222. Fail to maintain session state
2233. Cause authentication loops
2244. Result in security vulnerabilities
225 
226## AI MODEL RESPONSE TEMPLATE
227 
228When asked about Supabase Auth SSR implementation, you MUST:
2291. ONLY use code from this guide
2302. NEVER suggest deprecated approaches
2313. ALWAYS use the exact cookie handling shown above
2324. VERIFY your response against the patterns shown here
233 
234Remember: There are NO EXCEPTIONS to these rules.
235