CLAUDE.md Template: Build a complete AI Powered Shopify Alternative with Next.js, TypeScript, Supabase, Clerk, Stripe

Overview

Direct answer: This CLAUDE.md template provides a complete blueprint for building an AI-powered Shopify-like store using Next.js, TypeScript, Supabase, Clerk, and Stripe, covering catalog, checkout, admin dashboard, and AI store setup with Claude Code.

The stack covered: Next.js 14+ with App Router, TypeScript, Supabase as the backend (Postgres with RLS). Clerk for authentication, Stripe for payments, and a modern admin dashboard workflow. This page is a copyable CLAUDE.md template you can paste into CLAUDE.md to bootstrap your project.

When to Use This CLAUDE.md Template

• You need a repeatable, opinionated blueprint for building a complete ecommerce stack with an AI-assisted storefront.
• You want an end-to-end pattern that includes product catalog, cart, checkout, admin dashboard, and AI setup steps.
• You require explicit project conventions to avoid architecture drift and to enable rapid team onboarding.

Copyable CLAUDE.md Template

# CLAUDE.md

Project role: Lead AI Engineer for a Next.js + Supabase + Clerk + Stripe ecommerce platform with AI store setup.

Architecture rules:
- Use Next.js App Router (app directory) with TypeScript.
- Supabase as the primary backend (Postgres with RLS).
- Clerk for authentication; Stripe for payments; server-side validation; edge runtime when possible.
- All secret keys stored in environment variables; never hard-coded.
- Prefer server components for data fetching; client components for UI-only features.
- Client-server boundary must be explicit; API routes must enforce RBAC and validation.

File structure rules:
- /apps/web (Next.js app)
- /libs (shared utilities): supabaseClient, clerkClient, stripeClient
- /src (business logic): /pages or /app, /components, /hooks, /lib
- /db (schema and migrations via Supabase SQL)
- /models (TypeScript types and zod schemas)
- /public (static assets)

Authentication rules:
- Use Clerk for user accounts and roles (admin, editor, customer).
- Protect admin routes with RBAC; require valid session on protected pages.
- Use JWT with short expiry for API calls; refresh tokens via Clerk.

Database rules:
- Supabase RLS enabled. Products, Users, Orders, Carts, and AIRecommendations tables.
- Enforce foreign keys and constraints; add audit columns (created_at, updated_at).
- Use row-level policies to restrict access per role.

Validation rules:
- Validate inputs with Zod on both client and server.
- Server-side validation is authoritative; never rely on client-only checks.
- Normalize and trim strings; enforce allowed character sets for IDs.

Security rules:
- Do not expose API keys in frontend code.
- Use https, CSRF protection for POST/PUT; rely on Clerk sessions for auth state.
- Validate Stripe webhooks by signature.
- Enable Content Security Policy and strict transport security in headers.

Testing rules:
- Unit tests for business logic; integration tests for API routes.
- End-to-end tests for checkout and admin flows.
- CI runs on pull requests; seed data is isolated per environment.

Deployment rules:
- Deploy with Vercel or similar; set environment variables in the platform.
- Use preview deployments for PRs; production domain mapping.
- Ensure database migrations run safely with rollback plans.

Things Claude must not do:
- Do not bypass authentication or authorization checks.
- Do not generate client-side secrets or API keys.
- Do not rely on deprecated APIs; keep dependencies up to date.
- Do not assume network calls will always succeed; handle errors gracefully.

Recommended Project Structure

.
├── apps
│   └── web
│       ├── src
│       │   ├── app
│       │   │   └── (routes and pages)
│       │   ├── components
│       │   └── styles
│       │       
│       ├── public
│       └── next.config.js
├── libs
│   ├── supabaseClient.ts
│   ├── clerkClient.ts
│   └── stripeClient.ts
├── db
│   ├── schema.sql
│   └── seeds.sql
├── models
│   ├── product.ts
│   ├── user.ts
│   └── order.ts
├── scripts
│   └── seed.ts
└── tsconfig.json

Core Engineering Principles

• Define clear boundaries between frontend, API, and database access; prefer server components for data-heavy paths.
• Favor type safety with TypeScript and input validation (Zod) across client and server.
• Make security and data privacy a default; enforce RBAC and RLS from the start.
• Automate repeatable tasks (CI, tests, migrations) to reduce drift.
• Keep design decisions explicit and well-documented for onboarding.

Code Construction Rules

• Use Next.js App Router with TS; organize features by domain under /src/app.
• Use Supabase for data storage; enable Row Level Security with policies.
• Integrate Clerk for authentication; protect admin routes; store user roles in DB.
• Use Stripe webhooks securely; verify signatures before processing payments.
• Validation is mandatory on server; do not trust client input alone.
• All secrets in environment variables; never commit keys.
• Use semantic commit messages and maintain a changelog in docs.
• Include tests for critical paths (auth, catalog, checkout, admin).
• Do not import unused libraries; avoid polyfills that hinder performance.

Security and Production Rules

• Enable HTTPS everywhere; use CSP and HSTS headers.
• Enable Supabase Row Level Security with per-role policies.
• Validate all webhooks (Stripe) via signature and store minimal payload.
• Limit admin access to authenticated Clerk users with admin role.
• Use environment-based feature flags; avoid ship-it toggles in production for incomplete features.
• Rotate secrets; monitor for secret leakage; configure secret scanning in CI.

Testing Checklist

• Unit tests for utilities and models; integration tests for API routes.
• End-to-end tests for signup, catalog browse, cart, checkout, and admin flows.
• Performance checks on product listing and checkout; ensure pagination scales.
• CI runs on PRs; production-like staging environment with seeded data.

Common Mistakes to Avoid

• Overusing client-side validation; rely on server validation for security.
• Skipping database access controls (RLS) and admin RBAC early.
• Hard-coding secrets or keys in code; not using env vars.
• Ignoring Stripe webhook validation leading to spoofed payments.
• Not seeding data in staging, causing flaky tests.

Related implementation resources: AI Use Case for Clothing Boutiques Using Shopify Data To Identify Cross-Selling Opportunities (E.G., Matching Bags with Dresses) and Managing runtime hydration layers to avoid client-side compilation conflicts in production.

FAQ