CLAUDE.md Template: Ecommerce SaaS Stack (Next.js, TypeScript, Supabase, Clerk, Stripe, OpenAI, Shadcn UI, Tailwind)

Overview

This CLAUDE.md template is designed for building a complete Ecommerce SaaS using the full Next.js stack with TypeScript, Supabase, Clerk, Stripe, OpenAI, Shadcn UI, and Tailwind CSS. It is a copyable CLAUDE.md template page you can paste directly into CLAUDE.md to bootstrap architecture, rules, and project structure for Claude Code-driven development. Direct answer: paste the block below into your CLAUDE.md to initialize a production-ready scaffold for a modern ecommerce storefront powered by OpenAI-assisted features and a serverless backend.

When to Use This CLAUDE.md Template

• Starting a complete Ecommerce SaaS project with a full frontend and backend stack.
• Defining authoritative rules for architecture, authentication, data access, and deployment.
• Ensuring Claude Code adheres to stack-specific constraints and security practices.
• Generating a ready-to-paste project blueprint that speeds up onboarding and consistency.

Copyable CLAUDE.md Template

# CLAUDE.md

Project role: You are the system architect and Claude Code guide for building a complete Ecommerce SaaS using Next.js, TS, Supabase, Clerk, Stripe, OpenAI, Shadcn UI, and Tailwind. Your goal is to produce production-ready, paste-ready instructions and constraints.

Architecture rules:
- Use a modular monorepo with a single Next.js app for the web UI and API routes.
- Prefer server components when possible; isolate IO-bound calls to client components.
- Use Supabase for Postgres and authentication; configure Row-Level Security (RLS) on all sensitive tables.
- Clerk handles user authentication; store user metadata in Supabase and sync minimal data via webhooks.
- Integrate Stripe for payments with webhooks; keep payment intents and customer data in dedicated tables with proper access controls.
- OpenAI calls must be rate-limited, logged, and gated behind server-side functions; never call OpenAI from the browser without a server proxy.
- UI must be built with Shadcn UI and Tailwind CSS; use a shared design system and component library.
- All code and configurations must be paste-ready for CLAUDE.md; avoid proprietary or vendor-specific config not needed at runtime.
- Do not implement custom ORM logic beyond basic helper wrappers for Supabase; rely on PostgreSQL and RLS.

File structure rules:
- Use apps/web as the Next.js application root.
- Place all API routes under app/api and server components in app/(ui) with shared components in apps/web/src/components.
- Keep infra scripts under infra/ and config under config/
- Use a single package.json at the repo root with workspaces if needed; pin exact versions for reproducibility.

Authentication rules:
- Clerk must be used for authentication; enable email, passwordless, and social connectors as needed.
- When a user is authenticated, attach a minimal auth object to server context for server-side validation.
- Never expose API keys or secrets to the client; store secrets in environment variables and access them only on the server.

Database rules:
- Supabase Postgres is the primary database. Tables: users, products, carts, orders, payments, sessions, audit_logs.
- Implement Row-Level Security policies to restrict access by auth role and ownership.
- Use foreign keys with ON DELETE CASCADE where appropriate; avoid hard-coding IDs in client code.
- Back up critical tables and track schema migrations via a simple migration tool; keep migrations auditable.

Validation rules:
- Use TypeScript types for all API surfaces; validate inputs with Zod on the server.
- Client-side forms should perform basic validation; server validation must be the source of truth.
- Normalize inputs (trim, lowercase where needed) before persistence.

Security rules:
- Enforce CSRF protection on mutating endpoints; use signed cookies for session state.
- Enable HTTPS in all environments; never expose sensitive endpoints publicly.
- Rotate API keys; limit scope to required permissions.
- Audit log critical actions (create, update, delete) with user context and timestamp.

Testing rules:
- Unit-test UI components with a React testing library; test hooks and utilities in isolation.
- End-to-end tests should cover product creation, cart flow, checkout, and Stripe webhooks locally.
- Use mocked OpenAI calls in unit tests; verify prompts, tokens, and responses handling.

Deployment rules:
- Deploy with a serverless capable platform (e.g., Vercel); ensure environment variables for Supabase, Clerk, Stripe, and OpenAI are defined.
- Use CI to run unit, integration, and e2e tests on PRs.
- Enable error monitoring and logging; surface actionable alerts for failed payments, auth errors, and OpenAI quota events.

Things Claude must not do:
- Do not inject API keys or secrets in code blocks or client bundles.
- Do not bypass server-side validation; never trust client input for database mutations.
- Do not hard-code production URLs or credentials in CLAUDE.md; reference environment variables.
- Do not generate non-reproducible infrastructure changes.

Recommended Project Structure

ecommerce-saas/
├── apps/
│   └── web/
│       ├── src/
│       │   ├── app/
│       │   │   ├── layout.tsx
│       │   │   └── page.tsx
│       │   ├── components/
│       │   ├── hooks/
│       │   ├── lib/
│       │   │   ├── supabase.ts
│       │   │   └── clerk.ts
│       │   ├── styles/
│       │   └── ui/
│       ├── public/
│       ├── next.config.js
│       ├── tailwind.config.js
│       ├── postcss.config.js
│       └── tsconfig.json
├── infra/
│   └── migrations/
├── config/
│   └── env.example
├── package.json
└── README.md

Core Engineering Principles

• Single source of truth: one canonical data model across UI, API, and admin tooling.
• Performance first: prefer server components, edge caching, and batched writes.
• Security by default: enforce RLS, server-side validation, and least privilege access.
• Typed contracts: TypeScript everywhere; validate inputs with Zod; share types across client and server.
• Observability: structured logging, tracing for external calls, and robust error handling.

Code Construction Rules

• Use Next.js app router with a clearly defined public API under app/api.
• Component-driven UI with Shadcn UI and Tailwind; centralize themes and tokens.
• Supabase client usage should be through a single wrapper exposing safe helpers.
• OpenAI calls must go through server functions with rate limiting and caching where possible.
• Payment flows must use Stripe webhooks and store sensitive data only on the server.
• Validation must be performed on both client and server; never trust client input.
• Do not create custom ORM logic; rely on database constraints and standard queries.

Security and Production Rules

• All secrets live in environment variables; never commit them.
• Enable CORS only for trusted domains; restrict API routes to authenticated users where needed.
• Audit trails for critical actions; ensure user attribution on data mutations.
• Implement feature flags for experimental OpenAI features to control rollout.
• Regular dependency audits and vulnerability scanning in CI.

Testing Checklist

• Unit tests for UI components using React Testing Library; mock external services.
• API tests for all server routes with input validation and error paths.
• Integration tests for Stripe webhooks and order flow with a test environment.
• E2E tests for product browsing, cart, checkout, and payment completion.
• CI should run lint, type checks, and tests on every PR.

Common Mistakes to Avoid

• Skipping server-side validation and trusting client input.
• Over-fetching or under-fetching data; ignore under-optimized queries.
• Hard-coding production URLs or credentials in CLAUDE.md blocks.
• Ignoring accessibility and responsive design in UI components.

Related implementation resources: AI Use Case for Software Agencies Using Github Copilot To Accelerate Boilerplate Code Generation for New Client Mvps and Managing runtime hydration layers to avoid client-side compilation conflicts in production.

FAQ

• Q: What is this CLAUDE.md Template for?
  A: It provides a ready-to-paste CLAUDE.md block that defines architecture, rules, and project structure for a complete Ecommerce SaaS stack using Next.js, TS, Supabase, Clerk, Stripe, OpenAI, Shadcn UI, and Tailwind.
• Q: Which stack does this template cover?
  A: Next.js with TypeScript, Supabase for data and auth, Clerk for auth UI, Stripe for payments, OpenAI for AI features, Shadcn UI components, and Tailwind CSS styling.
• Q: How do I use the CLAUDE.md block?
  A: Copy the code block under Copyable CLAUDE.md Template and paste it into your CLAUDE.md file to bootstrap your project guidelines.
• Q: Can I customize for different Stripe workflows?
  A: Yes, adjust the Stripe-related sections and webhooks in the template, and keep sensitive keys in environment variables.
• Q: How do I run locally?
  A: Install dependencies, set up a Supabase project, configure Clerk and Stripe env vars, then run the Next.js app with npm/yarn.