CLAUDE.md Template: SvelteKit + Neon Serverless Postgres + Clerk Auth + Drizzle ORM Profile (CLAUDE.md template)

Overview


The CLAUDE.md template is a copyable Claude Code blueprint for a modern full‑stack SvelteKit application backed by Neon Serverless Postgres, with Clerk authentication and Drizzle ORM for profile data. It codifies stack‑specific conventions, directory layout, and guardrails so developers can paste it into a project and start iterating with predictable, type‑safe patterns.


This page delivers a complete CLAUDE.md template page for the SvelteKit + Neon Serverless Postgres + Clerk Auth + Drizzle ORM Profile stack. It provides the copyable CLAUDE.md block, a recommended project structure, and concrete engineering rules you can rely on in production.



When to Use This CLAUDE.md Template



  - You are starting a new SvelteKit project that targets Neon Serverless Postgres as the data store.

  - You require robust authentication via Clerk with session aware routes.

  - You want a type safe data layer using Drizzle ORM for profiles and related entities.

  - You need a ready‑to‑paste CLAUDE.md template that enforces architecture and security rules for deployment.



Copyable CLAUDE.md Template


Paste this CLAUDE.md block into your project root to bootstrap the stack with Claude Code guidance.


# CLAUDE.md

Project role
- You are Claude Code, providing implementation guidance for a SvelteKit app using Neon Serverless Postgres, Clerk authentication, and Drizzle ORM for a profile module.

Architecture rules
- Prefer serverless friendly API routes in SvelteKit
- Use Neon serverless Postgres as the primary database
- Use Clerk for authentication and authorization across protected routes
- Use Drizzle ORM as the data access layer and keep migrations deterministic
- Treat the database as the source of truth for models; never duplicate state on the server

File structure rules
- Keep src at the project root with the following minimal layout
- src/lib for shared utilities and DB helpers
- src/db for drizzle config and migrations
- src/routes for pages and API routes
- src/hooks.server.ts to integrate Clerk and session management
- drizzle migrations and schemas under src/db
- .env.local for secrets; never commit to VCS

Authentication rules
- All protected API routes and pages require a Clerk session
- Use getAuth in server hooks to obtain the user and enforce role constraints where applicable
- Do not bypass client side checks on server routes

Database rules
- Neon Serverless Postgres connection string in env var NEON_DATABASE_URL
- Define models using Drizzle ORM in src/db/schema.ts
- Create and run migrations for each schema change; do not alter production data directly via scripts
- Implement proper foreign keys and constraints for profile related tables

Validation rules
- Validate inputs with Zod schemas in API handlers before wiring to Drizzle
- Normalize and trim inputs; reject invalid field values early

Security rules
- Do not log secrets or connection strings
- Do not expose internal DB errors to clients
- Use environment variables for all credentials
- Enforce CSRF protection on stateful routes in non-GET requests where applicable

Testing rules
- Unit test validators and input transformers
- Integration test DB interactions through Drizzle and Neon emulator or test database
- End‑to‑end tests for Clerk auth flows and profile CRUD via API routes

Deployment rules
- Deploy to a serverless host compatible with SvelteKit (Vercel, Netlify, etc.)
- Configure Neon and Clerk environment variables in the host platform
- Run drizzle migrate in deployment pipelines and verify migrations

Things Claude must not do
- Do not output real secrets or credentials
- Do not recommend non stack parts like Prisma or Mongoose for this template
- Do not bypass authentication on protected routes



Recommended Project Structure


/
├── src
│   ├── lib
│   │   ├── db.ts        # Drizzle database client and helpers
│   │   └── auth.ts      # Clerk helper wrappers
│   ├── routes
│   │   ├── +layout.svelte
│   │   ├── +page.svelte
│   │   └── api
│   │       └── users.ts
│   ├── hooks.server.ts  # Clerk session integration
│   ├── db
│   │   ├── drizzle.config.ts
│   │   └── schema.ts
│   └── components
├── drizzle
│   └── migrations


Core Engineering Principles



  - Type safety by design across API routes and data models

  - Single source of truth for data via Neon Postgres

  - Clear separation of concerns between auth, data access, and UI

  - Deterministic migrations and reproducible environments

  - Security-by-default with env vars and proper access controls

  - Observability through structured error handling and logging best practices



Code Construction Rules



  - Use TypeScript everywhere; avoid any unsafe casting

  - Models defined in src/db/schema.ts and consumed via Drizzle ORM

  - API routes guarded by Clerk getAuth checks

  - Inputs validated with Zod before persisting

  - Environment variables read via Vite / SvelteKit env loading

  - Client and server boundaries honor least privilege

  - Do not embed secrets in code or commit them



Security and Production Rules



  - Store secrets exclusively in environment variables

  - Mask or avoid logging sensitive information

  - Protect API routes from CSRF and ensure authenticated access

  - Validate all inputs; reject unexpected schema shapes

  - Use Neon migrations and backups for production data safety



Testing Checklist



  - Unit tests for validators and transformers

  - Integration tests for Drizzle queries against a test database

  - Auth flow tests via Clerk mocks or test tenants

  - End-to-end tests for profile create, update, fetch flows

  - Deployment smoke tests to confirm environment variables and migrations



Common Mistakes to Avoid



  - Using Prisma/ORMs not part of this stack for DB access

  - Hardcoding secrets or credentials in code

  - Oversharing DB errors to clients

  - Unprotected API routes or missing Clerk guards

  - Skipping migrations and relying on ad hoc DB changes



FAQ



  
    What stack is this CLAUDE.md Template designed for?
    It targets SvelteKit with Neon Serverless Postgres, Clerk authentication, and Drizzle ORM for profile data.
    How do I start using the CLAUDE.md template?
    Copy the CLAUDE.md block into your project root, install dependencies, configure Neon and Clerk, then adapt the generated code.
    Can I customize the Drizzle models?
    Yes, edit src/db/schema.ts and run migrations to reflect changes in the database.
    Where should I store secrets?
    In environment variables and a local .env file excluded from version control.
    What are the recommended deployment targets?
    Serverless hosts like Vercel or Netlify with Neon and Clerk integration.