Remix (SPA Edge Mode) + Supabase DB + Supabase Auth + Drizzle ORM System - CLAUDE.md Template

Overview

A CLAUDE.md template designed for Remix (SPA Edge Mode) apps that use Supabase as the database and authentication provider, with Drizzle ORM for data access. The template produces a ready-to-paste Claude Code block you can drop into CLAUDE.md to bootstrap a minimal, production-lean Remix edge app with type-safe data access and secure authentication.

Direct answer: This page provides a copyable CLAUDE.md template block and a concrete project structure for a Remix SPA Edge app backed by Supabase DB/Auth and Drizzle ORM.

When to Use This CLAUDE.md Template

• You are building a Remix SPA Edge Mode app requiring edge-first rendering with API routes that fetch from Postgres (via Supabase).
• You want to use Supabase for authentication and as a managed Postgres DB, with server-side data access through Drizzle ORM.
• You need a repeatable, paste-ready CLAUDE.md template to onboard new engineers and maintain consistency across projects.
• You deploy to edge runtimes (e.g., Cloudflare Workers / Vercel Edge) and prefer a clean, typed data layer with strong validation.

Copyable CLAUDE.md Template

# CLAUDE.md

Project role: You are Claude Code acting as the lead engineer for a Remix (SPA Edge Mode) project that uses Supabase DB, Supabase Auth, and Drizzle ORM. Your output must be a complete, copy-paste ready CLAUDE.md template that a developer can drop into CLAUDE.md for rapid project bootstrap.

Architecture rules:
- Edge-first architecture with Remix routes on the edge and client components isolated behind server boundaries.
- Use Supabase Postgres as the DB; access via Drizzle ORM on the server.
- Centralize data access in a single db/ directory; keep server components to perform all DB interactions.
- Keep authentication checks on the server side; never trust client input for authorization decisions.
- Favor deterministic builds; avoid runtime feature flags that cause drift between environments.
- Cache API responses at the edge where appropriate using standard HTTP caching headers.

File structure rules:
- app/ should contain Remix-specific files: entry.client.tsx, entry.server.tsx, root.tsx, routes/, components/.
- db/ should include drizzle.ts and schema.ts for type-safe queries.
- env variables must live in a .env file (not checked in); reference SUPABASE_URL, SUPABASE_ANON_KEY, SUPABASE_SERVICE_ROLE if needed.
- Do not colocate DB access logic under non-server modules; keep it under db/ and import from there.

Authentication rules:
- Use Supabase Auth with email/password and OAuth providers as configured in the Supabase project.
- Sessions must be stored in HttpOnly cookies with Secure flag in production.
- Validate tokens on every request; refresh tokens using refresh token flow when needed.
- Do not expose service role credentials to the client.

Database rules:
- Use Drizzle ORM to define Postgres tables in db/schema.ts.
- All queries must be parameterized via Drizzle.
- Enforce row-level security policies in Supabase as appropriate for the app.
- Never run raw string-concatenated SQL queries; always use Drizzle''s query builder.

Validation rules:
- Validate all incoming data with Zod schemas on the server side before DB access.
- Return precise, non-ambiguous error messages to the client only after validating permissions.

Security rules:
- Do not embed secrets in the client bundle.
- Use HttpOnly, Secure cookies for session management.
- Implement CSRF protection for state-changing requests.
- Do not bypass authorization checks; enforce least-privilege access for DB users.

Testing rules:
- Unit test data access functions using mock DB adapters.
- Integration test server routes that perform DB writes using a test database or a sandboxed environment.
- End-to-end tests should cover login, session management, and a protected data fetch path.

Deployment rules:
- Ensure edge-friendly deployment target (Cloudflare Workers, Vercel Edge, or similar) with proper environment variables.
- Use feature-flag-free builds; ensure all environment-dependent features are resolved at deploy time.
- Validate that routes render correctly when cookies are present and absent.

Things Claude must not do:
- Do not emit raw SQL collected from user input without parameterization.
- Do not bypass Supabase auth checks or expose private keys to the client.
- Do not propose non-edge compatible APIs for Remix Edge Mode.
- Do not generate or rely on insecure default credentials.

Recommended Project Structure

remix-supabase-drizzle/
├─ app/
│  ├─ entry.client.tsx
│  │  └─ entry.server.tsx
│  ├─ root.tsx
│  ├─ routes/
│  │  ├─ index.tsx
│  │  ├─ login.tsx
│  │  └─ dashboard.tsx
│  └─ components/
│     └─ Navbar.tsx
├─ db/
│  ├─ drizzle.ts
│  └─ schema.ts
├─ .env.example
├─ package.json
├─ remix.config.js
└─ tsconfig.json

Core Engineering Principles

• Edge-first design with predictable SSR boundaries and minimal payloads.
• Type-safe data access via Drizzle ORM and Zod validation on the server.
• Least-privilege and secure authentication using Supabase Auth.
• Secret management through environment variables and secure storage.
• Idempotent deploys with clear observability and error reporting.

Code Construction Rules

• All DB access must go through Drizzle ORM in db/; avoid raw queries outside Drizzle.
• Server routes perform validation before DB interactions.
• Use Remix loaders/actions with explicit type definitions and error boundaries.
• Do not import client-only modules into server code; separate by environment.
• Do not store secrets in the client bundle; rely on process.env and runtime config.

Security and Production Rules

• Use HttpOnly and Secure cookies for sessions; set SameSite=Lax or Strict as appropriate.
• Enable CSRF protection for state-changing requests.
• Mask and vault secrets; rotate keys regularly and audit access.
• Apply row-level security in Supabase and validate permissions server-side.

Testing Checklist

• Unit tests for DB adapters with mocked Drizzle queries.
• Integration tests for auth flow and protected routes.
• End-to-end tests for login, data fetch, and logout paths.
• Performance tests for edge route responses and caching behavior.

Common Mistakes to Avoid

• Over-fetching data on the client; rely on edge routes and server components for data access.
• Ignoring environment-specific differences between edge runtimes.
• Storing long-lived tokens insecurely on the client.
• Late validation or bypassing authorization in API routes.

FAQ

What stack does this CLAUDE.md Template cover?

Remix (SPA Edge Mode) with Supabase DB/Auth and Drizzle ORM.

What should I paste into CLAUDE.md?

The large copyable Claude Code block provided above, which includes project role, architecture rules, and implementation constraints.

Can I adapt this to other edge runtimes?

Yes, but ensure the auth, DB access, and deployment rules align with the target edge provider.

Where are secrets stored?

In environment variables; never in client code or repository.

Which testing framework is expected?

Unit tests with your preferred framework (e.g., Vitest) and end-to-end tests with Playwright or similar.