CLAUDE.md Template: Next.js + TypeScript + Supabase + Clerk + Stripe – Test Case Generation SaaS

Overview

CLAUDE.md template for Next.js + TypeScript + Supabase + Clerk + Stripe — a complete Test Case Generation SaaS. It covers AI test planning, automation scripts, and coverage reports, with a copyable CLAUDE.md block designed for Claude Code integration in Claude-based workflows.

When to Use This CLAUDE.md Template

• To generate a production-grade scaffold for a Next.js + TS SaaS with auth, payments, and a Postgres-backed data layer via Supabase
• When you need integrated AI planning, test generation, and coverage reporting baked into the template
• To establish a repeatable, reviewable CLAUDE.md workflow for this stack

Copyable CLAUDE.md Template

# CLAUDE.md
# CLAUDE.md for Next.js + TypeScript + Supabase + Clerk + Stripe - Test Case Generation SaaS

Project role: You are Claude Code, a production-grade assistant that generates a complete Next.js (App Router) SaaS skeleton with TypeScript, Supabase as the database, Clerk for authentication, Stripe for payments, AI-driven test planning, automation scripts, and coverage reports. Your output must be a ready-to-paste CLAUDE.md block that a developer can drop into a repository.

Architecture rules:
- Use Next.js App Router under /src/app with server and client components as appropriate.
- TypeScript everywhere; strictNullChecks enabled.
- Centralize config in /env or /src/config, not in code.
- Data flows: UI (Next.js) & API routes (Server Components) using a single source of truth in Supabase.
- Authentication with Clerk; protect pages using middleware with requireAuth.
- Payments via Stripe; implement Stripe Checkout or client-side Elements with Webhooks secured by secret endpoints.
- AI planning and test generation modules must be isolated under /ai.

File structure rules:
- Do not scaffold non-essential folders; keep only what this stack needs.
- Place source under /src, with a clear separation:
  /src/app  -> Next.js routes
  /src/components
  /src/lib
  /src/services
  /src/ai
  /src/tests
  /src/reports
- Do not include monorepo or unrelated tooling unless it serves the stack.

Authentication rules:
- Clerk must be configured; use ClerkProvider at root and withMiddleware for protected routes.
- Use environment-based config for Clerk keys.

Database rules:
- Supabase as Postgres; connect via /src/lib/supabaseClient.ts
- Use RLS with policies to enforce per-user access
- All user data stored in public or auth schemas as appropriate
- Do not hardcode database credentials; rely on env vars

Validation rules:
- Use runtime validation with Zod for all inputs
- Validate request payloads in API routes and middleware

Security rules:
- Never expose secret keys in frontend; use server actions and API routes for sensitive operations
- Use HTTPS endpoints; verify webhook signatures for Stripe
- Secrets management via environment variables; never commit secrets

Testing rules:
- Unit tests with Vitest; integration tests with Playwright or Cypress
- Mock external services; test Stripe webhooks with a test secret
- CI should run tests and lint on PRs

Deployment rules:
- Prefer Vercel or other hosting with Edge Runtime support
- Use environment variables in production; set per-environment configs
- Ensure build caches are reproducible; pin dependency versions

Things Claude must not do:
- Do not generate large monoliths that ignore separation of concerns
- Do not hardcode API keys or secrets
- Do not bypass Clerk authentication or Stripe webhooks validation
- Do not propose insecure patterns (eval, new Function, unsafe dynamic imports)

Recommended Project Structure

project-root/
├─ apps/
│  └─ web/
│     ├─ app/
│     │  ├─ layout.tsx
│     │  ├─ page.tsx
│     │  └─ loading.tsx
│     ├─ components/
│     ├─ lib/
│     └─ styles/
├─ db/
│  └─ migrations/
├─ integrations/
│  ├─ clerk/
│  │  └─ config.ts
│  ├─ stripe/
│  │  └─ webhook.ts
│  └─ supabase/
│     └─ supabaseClient.ts
├─ ai/
│  ├─ planning/
│  │  └─ plan.yaml
│  └─ generation/
│     └─ generateTests.ts
├─ tests/
│  ├─ unit/
│  ├─ integration/
│  └─ e2e/
└─ reports/
   └─ coverage/

Core Engineering Principles

• Modular, composable design with clear boundaries between UI, API, and AI planning
• Deterministic Claude outputs that are easy to review and reproduce
• Type-safe scaffolding using TypeScript
• Idempotent code generation to avoid drift
• Security-first by default; proper secret handling and RBAC
• Observability: structured logging and test coverage reports

Code Construction Rules

• Follow the recommended project structure exactly; do not create unrelated folders
• Use Next.js App Router with /src/app; TypeScript everywhere
• Integrate Supabase as the central database, Clerk for auth, Stripe for payments
• Ensure strict runtime validation with Zod for all inputs
• All API routes must be typed and tested
• Do not embed secret keys in frontend code
• Provide reusable UI components under /src/components
• File naming should be predictable and aligned with stack conventions
• Provide a minimal, reproducible CLAUDE.md block for the template

Security and Production Rules

• Use environment variables for sensitive data; never commit secrets
• Validate Stripe webhooks with signature; verify receipts and subscriptions
• Use Clerk middleware for protected routes
• Enable HTTPS in all environments; configure Vercel Edge Runtime where possible
• Audit dependencies; pin versions; run dependency checks

Testing Checklist

• Unit tests for utility functions and services
• Integration tests for API routes and DB interactions
• End-to-end tests for user flows including auth and billing
• Test Stripe webhooks with test mode
• CI linting and type-check on PRs

Common Mistakes to Avoid

• Assuming client-side secrets are safe
• Overly heavy monoliths that couple UI, API, and AI planning
• Weak input validation or no RBAC for sensitive data
• Using mock data in production pipelines without validation

Related implementation resources: AI Use Case for Software Agencies Using Github Copilot To Accelerate Boilerplate Code Generation for New Client Mvps and Using Skill Files to Stop SQL Injection in Generated Backend Code.

FAQ

Q: What is this CLAUDE.md Template designed for? A: It provides a copyable Claude Code instruction block to scaffold a Next.js + TS SaaS with AI planning, tests, and coverage.

Q: Which stack does this template cover? A: Next.js App Router, TypeScript, Supabase, Clerk, Stripe, along with AI planning and automation scripts.

Q: How do I customize it for my project? A: Modify the CLAUDE.md block, adapt project structure, and adjust service integrations as needed.

Q: What about security? A: It emphasizes env vars, webhook validation, and Clerk authentication out of the box.

Q: Where can I learn more? A: Explore the CLAUDE.md Templates collection and related AI Skills on this site.