Next.js + Supabase Starter Guide

Productivity instructions for working with a Next.js 13 App Router + Supabase SSR starter app.

Big Picture

This is a Next.js 13 application using the App Router pattern (routes in `app/`). Authentication and database access are provided by Supabase via `@supabase/ssr` helpers. The project follows a server-first approach where most pages are Server Components, with explicit `"use client"` directives only where needed.

Repository Structure

Key Directories

- `app/layout.tsx` — Root layout with global providers (fonts, theme, audio player)

- `app/actions.ts` — Server actions for authentication (signUpAction, signInAction, signOutAction)

- `app/(auth-pages)/` — Auth-related routes (grouped)

- `app/(main)/` — Main application routes (grouped)

- `app/protected/` — Protected routes requiring authentication

- `components/providers.tsx` — Global providers orchestration

- `components/audio-player.tsx` — Audio player component with CSS

- `utils/supabase/client.ts` — Browser client for client components

- `utils/supabase/server.ts` — Server client for Server Components, Server Actions, and middleware

- `utils/supabase/middleware.ts` — Session update logic for middleware

- `utils/utils.ts` — Contains `encodedRedirect` for server action redirects

Authentication & Session Management

Critical Pattern

The app uses **cookie-backed Supabase sessions** via `@supabase/ssr`. Always use the correct client for your context:

**Server-side code** (Server Components, Server Actions, Route Handlers):

```typescript

import { createClient } from '@/utils/supabase/server'

const supabase = await createClient()

```

**Client-side code** (Client Components):

```typescript

import { createClient } from '@/utils/supabase/client'

const supabase = createClient()

```

Middleware

Server Actions Pattern

Follow the pattern in `app/actions.ts`:

```typescript

export async function myServerAction() {

const supabase = await createClient() // server helper

const { data, error } = await supabase.auth.someMethod()

if (error) {

return encodedRedirect('error', '/path', error.message)

}

return encodedRedirect('success', '/path', 'Success message')

}

```

Use `encodedRedirect` from `utils/utils.ts` for all redirects with flash messages.

Data Flow Patterns

Server-First Rendering (Preferred)

1. Fetch data in Server Components using `utils/supabase/server.ts`

2. Pass data as props to Client Components when needed

3. Use Server Actions for mutations

Client Components with Auth

When a Client Component needs Supabase:

```typescript

'use client'

import { createClient } from '@/utils/supabase/client'

export function MyComponent() {

const supabase = createClient() // browser client

// Use supabase here

}

```

Environment Variables

Required variables in `.env.local`:

The app reads `VERCEL_URL` in `app/layout.tsx` for `metadataBase` — document any additional env vars in the README.

Development Commands

No test runner is configured in this starter.

Styling & UI

Critical Gotchas

1. **Never** use the browser client (`utils/supabase/client.ts`) in server-side code

2. **Never** use the server client (`utils/supabase/server.ts`) in client components

3. **Preserve** middleware matcher exceptions for static assets and images

4. **Maintain** route group naming conventions (parentheses folders)

5. **Use** `encodedRedirect` for server action redirects, not raw Response objects

Example Reference Files

When implementing patterns, refer to these files:

Adding New Features

New Server Action

1. Add to `app/actions.ts` or create new actions file

2. Use `await createClient()` from `utils/supabase/server`

3. Return `encodedRedirect()` for redirects with messages

New Client Component

1. Add `"use client"` directive at top

2. Import client helper: `import { createClient } from '@/utils/supabase/client'`

3. Call `const supabase = createClient()` inside component

New Protected Route

1. Create in `app/protected/` or add auth check to existing route

2. Use server client to check session in Server Component

3. Redirect unauthorized users via `redirect()` from `next/navigation`

TypeScript Types

```typescript

const { data } = await supabase

.from('table_name')

.select('*')

.returns<Database['public']['Tables']['table_name']['Row'][]>()

```

If You Need Clarification

Request expansion on:

Follow these patterns consistently to maintain codebase conventions and avoid common pitfalls.