CLAUDE.md Template for Next.js + TypeScript + Supabase + Clerk + Stripe — AI Portfolio Builder SaaS

Overview

The CLAUDE.md template is designed for developers building a complete AI Portfolio Builder SaaS using Next.js, TypeScript, Supabase, Clerk, Stripe, with support for project pages, SEO generation, and custom domains. This template is stack-specific for Next.js + TS + Supabase + Clerk + Stripe.

When to Use This CLAUDE.md Template

• You are building a multi-tenant SaaS that manages AI portfolio pages for creators.
• You want paste-ready Claude Code that aligns with your tech stack and deployment workflow.
• You require robust authentication, payments, domain management, and SEO automation out of the box.

Copyable CLAUDE.md Template

# CLAUDE.md

Project role: You are the lead engineer configuring a production-grade Next.js + TypeScript + Supabase + Clerk + Stripe SaaS (AI Portfolio Builder). Your output must be paste-ready as CLAUDE.md for engineers to follow.

Architecture rules:
- Use Next.js App Router with server components where appropriate; SEO-friendly rendering; API routes for server-only logic.
- Deploy with a hosting provider that supports custom domains and edge functions (e.g., Vercel).
- Enforce multi-tenant isolation via per-organization spaces in Supabase; ensure tenant data is isolated.
- Clerk handles authentication; Stripe handles billing; Supabase stores data.
- Do not introduce additional DB technologies unless required by the design.

File structure rules:
- All code under apps/portfolio-builder/
- app/ contains layout.tsx and page.tsx; components/ stores React components; lib/ holds SDK clients; services/ holds business logic; pages/api/ for server endpoints; public/ for assets.
- Do not create extraneous folders or include unused tech stacks.

Authentication rules:
- Require Clerk-based authentication for protected routes; store userId in session; enforce role-based access on sensitive APIs.
- Use server-side checks for authorization in API routes.

Database rules:
- Supabase tables: users (PK id), portfolios, projects, domains, subscriptions, payments, audit_logs.
- Enable RLS with tenant_id/organization_id gating; never grant cross-tenant access.
- Do not store secrets in the client; fetch and use them on the server.

Validation rules:
- Validate all inputs with Zod schemas on the server; return precise error messages.
- Never skip validation for critical operations (billing, domain changes).

Security rules:
- Do not expose secrets in client bundles; use environment variables; rotate keys.
- Verify Stripe webhooks with signatures; restrict processing to a dedicated endpoint.
- Enforce TLS, HSTS, and secure cookies.

Testing rules:
- Unit tests for utilities and components; integration tests for API routes; end-to-end tests for onboarding and checkout flows.
- Use Vitest for unit tests and Playwright for E2E tests.

Deployment rules:
- Deploy to Vercel; configure custom domains; define environment variables: SUPABASE_URL, SUPABASE_ANON_KEY, CLERK_API_KEY, STRIPE_SECRET, STRIPE_WEBHOOK_SECRET.
- Enable preview deployments; run full CI checks before merging to main.

Things Claude must not do:
- Do not reveal secrets or deployments keys in the CLAUDE.md content.
- Do not propose client-side handling of Stripe webhooks or secret keys.
- Do not rely on Prisma or Mongoose; use Supabase as the DB.

Recommended Project Structure

apps/portfolio-builder/
  app/
    layout.tsx
    page.tsx
  components/
  lib/
    clerk.ts
    supabase.ts
    stripe.ts
  services/
  pages/
    api/
      stripe-webhooks/
  public/
  styles/

Core Engineering Principles

• Explicit, typed contracts across boundaries (TypeScript).
• Single source of truth for data models and business rules.
• Separation of concerns: UI, domain logic, and integrations.
• Security by default: least privilege, secure storage, and proper validation.
• Operability: observable, testable, and recoverable systems.

Code Construction Rules

• Prefer server components for data-fetching logic; avoid exposing secrets on the client.
• Use Next.js App Router with API routes for server-side operations (Stripe webhooks, billing, etc.).
• Data layer is Supabase; do not introduce additional ORMs unless required.
• Use Clerk for authentication and role checks; guard all protected routes.
• Environment variables must be loaded via runtime config; never hardcode secrets.
• All API surface areas should be typed with TypeScript interfaces.

Security and Production Rules

• Validate all inputs and enforce server-side authorization for every API call.
• Verify Stripe webhooks with signatures and store only non-sensitive data on the client.
• Use HTTPS, secure cookies, and proper CORS at API boundaries.
• Enable RLS in Supabase and apply tenant-scoped access controls.
• Rotate keys and monitor for suspicious activity.

Testing Checklist

• Unit tests for utilities and components.
• Integration tests for API routes (auth, payments, domain management).
• End-to-end tests for onboarding, portfolio creation, and checkout flows.
• CI must run type checks, lint, tests, and a quick integration test suite.

Common Mistakes to Avoid

• Using client secrets in the frontend or inline in components.
• Over-sharing permissions; failing to lock down API routes with Clerk sessions.
• Relying on client-side validation for sensitive operations (billing, domain changes).
• Hard-coding domain values or Stripe keys in codebases that are not environment-scoped.

Related implementation resources: AI Use Case for Software Agencies Using Github Copilot To Accelerate Boilerplate Code Generation for New Client Mvps and Why authorization checks belong in AI coding instructions for production-grade systems.

FAQ