Next.js 16 Server Actions + Supabase DB/Auth + PostgREST Client Architecture - CLAUDE.md Template

Overview

This CLAUDE.md template demonstrates a copyable CLAUDE.md template for implementing Next.js 16 Server Actions with a Supabase DB and Supabase Auth, using a PostgREST client architecture. It targets Claude Code workflows and provides concrete, stack-specific instructions in a ready-to-paste format. The direct answer is that this template captures the architecture, security, and deployment rules for this stack in a single, Claude Code-friendly file.

Direct answer: This CLAUDE.md template yields a complete, paste-ready Claude Code block and folder structure for a Next.js 16 Server Actions + Supabase + PostgREST stack.

When to Use This CLAUDE.md Template

• Starting a new Next.js 16 project that leverages Server Actions for data fetching and mutations.
• Integrating Supabase DB and Supabase Auth for auth and database operations.
• Adopting a PostgREST client approach to expose a REST-like API surface on top of Postgres.
• Creating a repeatable blueprint that teams can vendorize into CI/CD pipelines.

Copyable CLAUDE.md Template

# CLAUDE.md
ProjectRole: Full-stack Architect
Stack: Next.js 16 Server Actions, Supabase DB, Supabase Auth, PostgREST Client
Goals: Build a secure, scalable server-driven architecture with typed endpoints and minimal client surface.
Constraints:
  - Do not perform direct DB calls from client components.
  - Do not bypass Supabase Auth during server actions.
  - Do not expose secrets in client bundles.
  - Do not rely on ORM layers that are not compatible with Server Actions.
ArchitectureRules:
  - Server Actions are the single entry point for data mutations.
  - Use PostgREST client to access Postgres as REST-like API.
  - Client components call only typed endpoints provided by PostgREST.
FileStructureRules:
  - Keep server code under src/app and server-actions folders.
  - Place database access code under src/db and src/lib.
AuthenticationRules:
  - All DB operations must be mediated by authenticated server actions.
  - Use Supabase Auth session on the server to authorize requests.
DatabaseRules:
  - Use a dedicated Postgres schema for app data.
  - Validate inputs on the server via constraints and RLS policies.
ValidationRules:
  - Validate all inputs on server side before calling the DB.
  - Use schema constraints and explicit types to prevent type coercion.
SecurityRules:
  - Never embed private keys in client code.
  - Enable Row-Level Security (RLS) with proper policies.
  - Enable CSRF protection where applicable.
TestingRules:
  - Unit-test utility functions for data transformation.
  - Integration tests for PostgREST endpoints and Supabase auth flows.
  - End-to-end tests for a typical user journey using server actions.
DeploymentRules:
  - Use environment-scoped secrets in CI/CD (e.g., Vercel/Netlify).
  - Ensure database migrations run in CI and prod.
ThingsClaudeMustNotDo:
  - Do not bypass auth to access database from client.
  - Do not lock into a single vendor library that blocks Server Actions.
  - Do not assume ORM features map directly to PostgREST.

Recommended Project Structure

src/
  app/
    page.tsx
    server-actions/
      index.ts
  lib/
    supabaseClient.ts
    postgrestClient.ts
  db/
    schema.sql
  components/
  hooks/

Core Engineering Principles

• Type-safe boundaries between client and server using Next.js Server Actions.
• Single source of truth for data access via PostgREST clients.
• Idempotent server-side operations with clear rollback semantics.
• Explicit contracts between layers (UI, server actions, DB access).
• Environment-agnostic setups with reproducible builds.

Code Construction Rules

• Prefer server-side data access through server actions and the PostgREST client.
• Avoid client-side database credentials and direct SQL.
• Use environment variables securely for all secrets.
• Document API surface in the CLAUDE.md template with typed inputs/outputs.
• Keep code modular; expose only minimal surfaces to the client.

Security and Production Rules

• Enable Strict Real-time session checks for actions.
• Enable RLS and policies on all tables used by the app.
• Rotate and protect PostgREST tokens; never persist them on client.
• Rotate and monitor credentials for all external services; follow a rotation schedule.

Testing Checklist

• Unit tests for data validators and helpers.
• Integration tests for server actions against a test database.
• End-to-end tests for user flows with Supabase Auth.
• Automation for migrations and seed data.

Common Mistakes to Avoid

• Forgetting to apply RLS policies on shared tables.
• Accessing DB from client code.
• Not validating inputs at the server boundary.
• Reusing ORM layers that conflict with PostgREST semantics.

FAQ

What is this CLAUDE.md Template designed for?

A copyable CLAUDE.md template for Next.js 16 Server Actions with Supabase and PostgREST client architecture.

Which stack does it cover?

Next.js 16 Server Actions, Supabase DB/Auth, and a PostgREST client pattern.

How do I customize environment secrets?

Store secrets in CI/CD and hosting platform env vars; never commit secrets. Use server-only config files.

Can I extend the PostgREST client?

Yes, provide type-safe wrappers around REST endpoints and parameter validation.

What are the security expectations?

Enable RLS, CSRF protections, and server-only access; do not expose credentials to the client.