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.

Related implementation resources: AI Use Case for Software Agencies Using Github Copilot To Accelerate Boilerplate Code Generation for New Client Mvps and Skill files for secure file upload implementations in production AI systems.

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.