Remix (Vite Router) + PostgreSQL + Kinde Auth + Prisma ORM - CLAUDE.md Template

Overview

CLAUDE.md template for Remix (Vite Router) + PostgreSQL + Kinde Auth + Prisma ORM is a copyable instruction block designed to be pasted into a CLAUDE.md file. It defines architecture, constraints, and best practices to generate a production-ready full-stack Remix app with Prisma as the ORM and Kinde for authentication.

Direct answer: This CLAUDE.md template provides Claude Code with explicit rules and a ready-to-run structure for Remix, Postgres, Kinde, and Prisma, including environment setup and deployment guidance.

When to Use This CLAUDE.md Template

• You want a fast, production-ready Remix (Vite Router) scaffold with PostgreSQL via Prisma.
• You need to integrate Kinde authentication across server and client routes.
• You require a clear file structure, validation, and security rules for a full-stack app.
• You plan to deploy to a cloud provider and want ready-to-run migrations and seed data guidance.

Copyable CLAUDE.md Template

# CLAUDE.md

Project Role
- You are Claude Code, tasked with generating a production-ready Remix (Vite Router) application using PostgreSQL, Prisma ORM, and Kinde Auth.
- The goal is to deliver a complete starter that includes auth flows, migrations, environment configuration, and a ready-to-run sample route.

Architecture Rules
- Use a layered, modular architecture: routes, services, and data access layers.
- Centralize configuration via environment variables and a single .env file (never commit secrets).
- Prefer TypeScript with strict type checking and runtime validation (Zod).
- Use Prisma for database access, migrations, and schema generation.
- Integrate Kinde as the OAuth2/OIDC provider for authentication.
- Ensure all API routes enforce authentication where required and use HttpOnly cookies for sessions.

File Structure Rules
- Keep a single source of truth for config in .env.example and config/*.ts modules.
- Place Prisma schema at prisma/schema.prisma and migrations under prisma/migrations.
- Place Remix app code under app/ with routes/ for pages and api/ for handlers.
- Include a services/ or lib/ folder for DB and auth helpers (db.ts, auth.server.ts).

Authentication Rules
- Implement Kinde authentication flow using official Kinde SDKs; store session in HttpOnly cookies.
- Protect sensitive routes with middleware to verify user sessions and roles.
- Support refresh tokens if provided by Kinde and rotate JWTs safely.

Database Rules
- Define Prisma models aligned to app needs; use Postgres as the database.
- Use environment-sourced connection string (DATABASE_URL) in .env.
- Create migrations for schema changes and provide seed script for initial data.

Validation Rules
- Validate inputs at the edge using Zod; treat all requests as unauthenticated by default.
- Normalize and trim string inputs; enforce required fields on user-facing forms.

Security Rules
- Do not log sensitive information; avoid exposing tokens in client JSON.
- Use HttpOnly, Secure cookies with SameSite=Lax or Strict in production; rotate sessions.
- Enable CSRF protection on state-changing endpoints.
- Enforce TLS in production; never use plaintext credentials in code.

Testing Rules
- Unit-test utilities and validators with Vitest; component tests with React Testing Library.
- Integration tests cover auth flow and Prisma queries against a test database.
- Include end-to-end tests with Playwright or Cypress that simulate login, protected routes, and logout.

Deployment Rules
- Prepare environment variables: DATABASE_URL, KINDE_CLIENT_ID, KINDE_CLIENT_SECRET, KINDE_DOMAIN.
- Run prisma migrate deploy and prisma generate before starting the app.
- Configure hosting to support Remix with Vite Router; ensure server starts in production with SSR.
- Monitor logs and set up health checks in your hosting provider.

Things Claude Must Not Do
- Do not implement custom OAuth flows outside Kinde without security review.
- Do not bypass Prisma migrations or operate on production data in tests.
- Do not expose secrets or private keys in code or logs.
- Do not use non-production branches for deployment in guidance.

Recommended Project Structure

remix-app/
├── app/
│   ├── entry.client.tsx
│   │   ├── root.tsx
│   │   ├── routes/
│   │   │   ├── index.tsx
│   │   │   ├── dashboard.tsx
│   │   │   └── api/
│   │   │       └── users.ts
│   │   ├── components/
│   │   ├── models/
│   │   │   └── user.ts
│   │   └── utils/
│   │       └── auth.server.ts
├── prisma/
│   ├── schema.prisma
│   └── migrations/
├── lib/
│   ├── db.ts
│   └── kinDeAuth.ts
├── .env
├── prisma-client.ts
├── package.json
└── README.md

Core Engineering Principles

• Type-safety and explicit contracts across client, server, and database layers.
• Security by default: authenticated routes, HttpOnly cookies, and CSRF protection.
• Reproducible builds and migrations; avoid environment-specific code paths.
• Clear separation of concerns; single-responsibility for data access and business logic.
• Observability: meaningful logs, metrics, and tracing for auth and DB operations.

Code Construction Rules

• Use TypeScript strictly; enable strict mode in tsconfig.json.
• Prisma models must reflect real-world constraints and migrations must be versioned.
• All inputs must be validated via Zod schemas; fail closed on invalid input.
• Auth flows must rely on Kinde; do not roll custom tokens without security review.
• API routes should return consistent shapes and proper HTTP status codes.

Security and Production Rules

• Store secrets in environment variables; do not commit .env files.
• Use Secure and HttpOnly cookies; enable CSRF protection on state-changing endpoints.
• Configure database connection pooling; implement connection timeout handling.
• Regularly rotate keys and secrets; log access patterns for anomaly detection.

Testing Checklist

• Unit tests for validators and small utilities.
• Integration tests for Prisma queries and Kinde auth flow using mocks.
• End-to-end tests for login/logout and protected routes.
• Deployment smoke tests for environment config and migrations.

Common Mistakes to Avoid

• Omitting environment variable validation; rely solely on runtime checks.
• Skipping Prisma migrations in new environments; seed data must be reproducible.
• Exposing API secrets in client-side code or logs.
• Using non-HTTPS in production or insecure cookies.

FAQ

What stack does this CLAUDE.md Template cover?

Remix (Vite Router) with PostgreSQL via Prisma ORM and Kinde authentication.

What should Claude generate first?

Config files, Prisma schema, Kinde auth integration, and a sample protected route.

How do I configure Kinde in this template?

Set KINDE_DOMAIN, KINDE_CLIENT_ID, KINDE_CLIENT_SECRET in .env and initialize auth using the provided kinDeAuth helper.

How do I run migrations?

Run prisma migrate deploy in your deployment environment after installing dependencies.

Where can I extend tests?

Extend Vitest tests for validators and utilities; add Playwright or Cypress for E2E tests.