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.

Related implementation resources: AI Use Case for Software Agencies Using Github Copilot To Accelerate Boilerplate Code Generation for New Client Mvps and Designing secure Server Actions with mandatory input schema validations at the server boundary.

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.