CLAUDE.md Template: SvelteKit + Supabase DB/Auth + PostgREST Engine Layout

Overview

Direct answer: Use this CLAUDE.md Template to scaffold a SvelteKit app backed by a Supabase DB and Supabase Auth, with a PostgREST Engine serving the API surface. This page is a copyable Claude Code blueprint tailored for the SvelteKit + Supabase DB/Auth + PostgREST Engine Layout.

The template enforces architecture, file structure, authentication, database access rules, validation, security, testing, and deployment guidelines for this stack.

When to Use This CLAUDE.md Template

• Starting a new SvelteKit project with a Supabase DB and authentication
• Exposing a REST API via PostgREST for database access
• Implementing row-level security and role-based access control
• Preparing for production deployment with proper environment separation

Copyable CLAUDE.md Template

# CLAUDE.md
Project role: You are Claude Code, an assistant specialized in building a SvelteKit + Supabase + PostgREST Engine Layout. You guide the developer through architecture, security, testing, and deployment with concrete rules.

Architecture rules:
- The API surface is PostgREST-backed; front-end (SvelteKit) should fetch from PostgREST endpoints only and not execute raw SQL.
- Supabase Auth provides JWTs; access to DB is controlled via RLS policies and PostgREST role mappings.
- Separate environments for dev, staging, and production; secrets come from environment variables, not code.
- Use server-side validation and DB constraints; never trust client input for critical decisions.

File structure rules:
- src/ contains all SvelteKit source code; db/ contains database schemas and migrations; supabase/ holds project-specific config like policies and functions.
- README.md and docs live at the project root; avoid mixing concerns across folders.

Authentication rules:
- Use Supabase Auth JWTs; verify tokens in the API gateway (PostgREST) and in server-side logic.
- Do not expose private keys or service credentials in client code.

Database rules:
- Enable Row Level Security on all tables and implement policies for anonymous and authenticated users.
- Use PostgREST endpoints for CRUD operations; no raw client-side SQL.

Validation rules:
- Validate input via DB constraints and server logic; sanitize inputs; reject invalid payloads early.

Security rules:
- Do not bypass RLS; do not store secrets in front-end code; rotate credentials regularly; enforce TLS in transport.

Testing rules:
- Unit tests for UI and client-side logic; integration tests for API endpoints; end-to-end tests covering frontend-to-DB flows.

Deployment rules:
- CI runs tests and migrations; deploy frontend to a hosting provider; ensure environment variables are configured in production.

Things Claude must not do:
- Do not generate raw SQL in the client; do not bypass authentication or RLS; do not rely on client-side validation for security decisions.

Recommended Project Structure

apps/
  sveltekit-supabase-postgrest/
    src/
      lib/
        db/
        api/
      routes/
      components/
    migrations/
    supabase/
      migrations/
      functions/

Core Engineering Principles

• Explicit contracts: frontend, API, and DB boundaries are clearly defined and adhered to.
• Least privilege: services operate with the minimal required access.
• Idempotent deployments: migrations and seed data are idempotent.
• Strict input validation and validation-first design.
• Defensive coding: handle failures gracefully with meaningful errors.

Code Construction Rules

• Use TypeScript in SvelteKit; type data models; avoid any.
• All API calls go through PostgREST endpoints and respect RLS policies.
• Store secrets as environment variables; never commit keys.
• Do not embed DB secrets in the client or within the CLAUDE.md code blocks.

Security and Production Rules

• Enable RLS on all tables; implement policies for anon and authenticated users.
• JWT validation is mandatory; verify Supabase tokens on the API layer.
• Strict CORS settings; TLS enforced; monitor logs for anomalies.

Testing Checklist

• Unit tests for UI components; integration tests for API endpoints; end-to-end tests for login, data fetch, and update flows.
• Automated migrations and seed data tests in CI.

Common Mistakes to Avoid

• Exposing DB admin endpoints to the client.
• Relying solely on client-side validation for security decisions.
• Omitting RLS policies or misconfiguring them.

FAQ

• Q: What is this CLAUDE.md Template for?
  A: A copyable Claude Code blueprint for a SvelteKit + Supabase + PostgREST Engine Layout.
• Q: Which stack does it cover?
  A: SvelteKit frontend, Supabase DB/Auth, and PostgREST as the API engine.
• Q: How do I use the CLAUDE.md block?
  A: Copy the CLAUDE.md block and paste into your CLAUDE.md file in the project.
• Q: What are the key security considerations?
  A: Enable RLS, validate JWTs, enforce server-side validation, and avoid exposing secrets.
• Q: Where should I deploy?
  A: Deploy the frontend to a hosting provider; configure Supabase env vars for DB/Auth and API.