CLAUDE.md Template: Next.js + TypeScript + Supabase + Clerk + Stripe Digital Marketplace

Overview

CLAUDE.md Template is a copyable Claude Code blueprint designed for building a Digital Products Marketplace using Next.js with App Router, TypeScript, Supabase, Clerk, Stripe, AI SEO generation, digital downloads, licensing, and creator analytics. This page is a CLAUDE.md template page, not a boilerplate. It provides a ready-to-paste instruction block that you can drop directly into a CLAUDE.md file for this stack.

Direct answer: This template yields a production-ready blueprint with modular architecture, secure auth, payments, licensing, AI-assisted SEO, and creator analytics, all encoded for Claude Code consumption.

When to Use This CLAUDE.md Template

• You need a turnkey marketplace with Next.js App Router and TypeScript.
• You want integrated authentication via Clerk and secure Supabase database access.
• You require Stripe-based payments, licensing workflows, and digital downloads.
• You plan AI-generated SEO content and analytics for creators.
• You expect good developer ergonomics with a clear file structure and test strategy.

Copyable CLAUDE.md Template

# CLAUDE.md

Project role
- You are a seasoned Full-Stack Engineer with a focus on building a scalable Digital Products Marketplace using Next.js, TypeScript, Supabase, Clerk, Stripe, and AI SEO capabilities.
- Your job is to output Claude Code blocks that are copy-paste ready for developers to implement quickly in Claude Code.

Architecture rules
- Use Next.js App Router with a server/client separation pattern; all business logic in server components where possible.
- Store data in Supabase Postgres with RLS enabled; enforce security at the DB layer.
- Use Clerk for authentication and role-based access control; map roles to permissions in your API routes.
- Implement Stripe for payments, webhooks, and licensing validation; keep keys strictly on the server.
- Provide an AI SEO generator service that can produce metadata for product pages and creator profiles.
- Maintain a single source of truth for product definitions, pricing, and licensing terms.
- Ensure observability with structured logging and error handling; surface only necessary data to the client.

File structure rules
- apps/marketplace (Next.js app)
- apps/marketplace/pages (or app dir with app/)
- apps/marketplace/src (shared UI and hooks)
- libs/seo (AI SEO generation utilities)
- libs/payments (Stripe integration wrappers)
- db/ (Supabase migrations and seed data)
- scripts/ (devops and migrations)
- public/ (static assets)

Authentication rules
- Clerk handles all user authentication; store user roles in a dedicated table in Supabase and map them in API routes.
- Never rely on client-only user state for authorization; validate on the server side.
- Require email verification for critical actions (purchases, licensing, downloads).

Database rules
- Supabase Postgres with RLS enabled on all tables.
- Tables: users, products, licenses, purchases, downloads, analytics, api_keys (server-side only), seo_metadata.
- Use proper foreign keys and referential actions; never expose DB keys in the frontend.

Validation rules
- Use Zod for all input schemas; export TS types from schemas for consistency.
- Validate all external inputs and webhook payloads strictly; reject unknown fields.

Security rules
- Never embed secrets in client bundles; fetch secrets from server only.
- Validate and sanitize all user inputs; implement rate limiting for sensitive endpoints.
- Disable CORS on sensitive endpoints or scope it to the frontend domain.

Testing rules
- Unit tests for utilities and validators; integration tests for API routes using Vitest.
- End-to-end tests with Playwright for key user flows (auth, product creation, purchase, licensing).
- Add test data seeds for deterministic test runs.

Deployment rules
- Deploy on a serverless platform (e.g., Vercel); ensure environment variables are securely managed.
- Use separate environments for dev/staging/prod; enable automatic previews for PRs.
- Keep secrets out of version control; rotate keys regularly.

Things Claude must not do
- Do not hardcode production credentials or API keys.
- Do not bypass server-side validation for critical operations.
- Do not assume client-side state equals authenticated user state.
- Do not use deprecated APIs or risky inline secrets.
- Do not expose internal admin endpoints to the public.

Recommended Project Structure

apps/marketplace/
  app/                      # Next.js App Router entry
  src/                      # Components, hooks, utilities
  pages/                    # (if not using app/)
  components/
  lib/
  styles/
  server/
libs/seo/
libs/payments/
ldb/
  migrations/
  seeds/
public/
docker/
docs/

Core Engineering Principles

• typed, modular, and maintainable codebase; strict TS usage everywhere
• explicit contracts between server and client; minimize API surface
• security by design; enforce authorization on the server side
• clear separation of concerns; single responsibility for modules
• test-driven approach; high test coverage for critical paths
• observable and debuggable; structured logging and tracing

Code Construction Rules

• All API routes must validate input with Zod and fail fast on invalid payloads
• Server components handle data fetching; client components render via props
• Auth checks must be enforced server-side; never rely on client-side guards
• Use Supabase RLS to restrict data access per user/role
• Stripe webhooks must verify signature and update licenses/purchases accordingly
• AI SEO generator must be idempotent and produce deterministic outputs for given inputs
• Do not bypass license checks for downloads; enforce licensing terms

Security and Production Rules

• Store secrets in environment variables; never commit keys
• Enable CORS restrictively; lock to authorized frontends
• Enable rate limiting on sensitive endpoints (purchases, license validation)
• Use nonces for critical actions; validate webhook payloads on the server
• Regularly rotate API keys and monitor access logs

Testing Checklist

• Unit tests for all validators and helpers
• Integration tests for auth, product creation, licensing, and purchases
• End-to-end tests for checkout, license download, and analytics events
• Smoke tests on deployment previews

Common Mistakes to Avoid

• Relying on client-side data for authorization decisions
• Neglecting DB-level security (RLS) or overexposing data in API responses
• Hardcoding secrets in code or environment files not protected in CI
• Skipping validation for webhook and external requests
• Ignoring accessibility and performance considerations in UI

Related implementation resources: AI Use Case for Notion Knowledge Base and Internal Question Answering and Access control in routing layouts: practical AI-driven verification patterns for production systems.

FAQ

• What is a CLAUDE.md Template?

  A CLAUDE.md Template provides a copyable Claude Code blueprint for a specific stack that you can paste into CLAUDE.md to scaffold a production-ready solution.

• Which stack does this template cover?

  Next.js with TypeScript, Supabase, Clerk for auth, Stripe for payments, plus AI SEO generation, downloads, licensing, and creator analytics.

• How do I use the included CLAUDE.md block?

  Copy from the code block and paste into your CLAUDE.md file; adapt environment-specific values and seed data as needed.

• What should I customize first?

  Configure environment variables for Supabase and Stripe, set up Clerk, then implement core product, license, and download flows.

• How is security enforced?

  Server-side validation, DB-level security with RLS, and secret management via environment variables are required.