How to Structure a Modern Next.js 15 & Supabase Application with Strict Type Safety

The New Full-Stack Standard: Next.js 15 + Supabase

The web development ecosystem has converged on a clear architectural standard for high-performance SaaS applications: Next.js 15 App Router paired with Supabase (managed PostgreSQL with native authentication, Row-Level Security, and real-time listeners). However, integrating these technologies without strict type safety and architectural boundaries leads to fragmented authentication states, memory leaks, and brittle deployments.

Core Architectural Architecture

A production-ready repository must maintain a clean separation between server-rendered data fetching, interactive client boundaries, and database communication:

/src
  ├── /app
  │    ├── /(auth)          # Isolated auth routes (login, register, reset)
  │    ├── /(dashboard)     # Protected application shell
  │    ├── layout.tsx       # Root layout with font optimization & theme scripts
  │    └── page.tsx         # Static landing page
  ├── /actions              # Type-safe Next.js Server Actions ('use server')
  ├── /components
  │    ├── /ui              # Pure presentational UI elements
  │    └── /layout          # Navbar, Footer, Mobile drawers
  ├── /lib
  │    ├── /supabase
  │    │    ├── client.ts   # Browser client (createBrowserClient)
  │    │    ├── server.ts   # Server client (createServerClient with cookies)
  │    │    └── middleware.ts # Token refresh middleware
  └── /types
       └── database.types.ts # Auto-generated Supabase schema types

Step 1: Setting Up the Supabase SSR Client

Next.js 15 features enhanced caching heuristics and asynchronous request headers. The official @supabase/ssr package handles token refresh and cookie synchronization across server components, client components, and route handlers.

Server Client Factory (lib/supabase/server.ts)

import { createServerClient } from '@supabase/ssr'
import { cookies } from 'next/headers'
import { Database } from '@/types/database.types'

export async function createClient() {
  const cookieStore = await cookies()

  return createServerClient<Database>(
    process.env.NEXT_PUBLIC_SUPABASE_URL!,
    process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY!,
    {
      cookies: {
        getAll() {
          return cookieStore.getAll()
        },
        setAll(cookiesToSet) {
          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 middleware refreshing user sessions.
          }
        },
      },
    }
  )
}

Step 2: Automated TypeScript Type Generation

Never manually write database interfaces. Doing so guarantees that schema migrations will desynchronize from your frontend types. Instead, configure Supabase CLI to generate types directly from your live or local PostgreSQL schema:

npx supabase gen types typescript --project-id your-project-id > src/types/database.types.ts

Add this script to your package.json as "db:generate" so your team can re-synchronize types after every migration.

Step 3: Writing Type-Safe Server Actions

Server Actions in Next.js 15 allow you to mutate backend data directly without maintaining custom API endpoints. Always validate input data with Zod before touching the database:

'use server'

import { createClient } from '@/lib/supabase/server'
import { revalidatePath } from 'next/cache'
import { z } from 'zod'

const OrderSchema = z.object({
  productId: z.string().uuid(),
  customerEmail: z.string().email(),
})

export async function createDigitalOrder(formData: FormData) {
  const parsed = OrderSchema.safeParse({
    productId: formData.get('productId'),
    customerEmail: formData.get('customerEmail'),
  })

  if (!parsed.success) {
    return { error: 'Invalid order parameters.' }
  }

  const supabase = await createClient()
  const { data, error } = await supabase
    .from('orders')
    .insert([
      {
        product_id: parsed.data.productId,
        email: parsed.data.customerEmail,
        status: 'pending',
      },
    ])
    .select()
    .single()

  if (error) {
    console.error('Database Error:', error)
    return { error: 'Failed to record order.' }
  }

  revalidatePath('/dashboard/orders')
  return { success: true, orderId: data.id }
}

Key Takeaways for Full-Stack Reliability

By enforcing automatic schema type generation, using the unified SSR cookie adapter, and validating Server Action inputs, you eliminate runtime type mismatches and build an application that scales securely from prototype to enterprise.