CLAUDE.md Template: Next.js + Supabase + Clerk + Stripe SaaS Widget

Overview

The CLAUDE.md template is a copyable Claude Code blueprint for building a complete AI Chatbot Widget SaaS using Next.js, TypeScript, Supabase, Clerk, Stripe, embeddable scripts, knowledge base, analytics, and billing. This page provides a copyable CLAUDE.md template you can paste into Claude Code to scaffold the stack.

When to Use This CLAUDE.md Template

• You are building a SaaS chatbot widget with a web UI and embeddable script
• You need authentication, billing, and customer management
• You want a typed Next.js App Router app with a Postgres backend via Supabase
• You plan to use Clerk for auth and Stripe for subscriptions
• You require a knowledge base, analytics events, and widget embedding

Copyable CLAUDE.md Template

# CLAUDE.md

Project role
  - Build a complete AI Chatbot Widget SaaS using Next.js, TypeScript, Supabase, Clerk, Stripe
  - Provide a copyable CLAUDE.md template block for Claude Code to implement architecture

Architecture rules
  - Use Next.js App Router (app directory)
  - Use TypeScript everywhere
  - Use Supabase as the primary database and auth provider
  - Use Clerk for authentication and user management
  - Use Stripe for billing and subscriptions
  - Provide an embeddable script for the widget that loads via a script tag
  - Expose a knowledge base endpoint and analytics events
  - Use server components for data fetching and client components for UI

File structure rules
  - Place code in apps/saas-widget with a single source of truth
  - Maintain clear separation between frontend (UI) and backend (API)
  - Include a lib and features folder for domain logic
  - Do not include irrelevant technology scaffolds

Authentication rules
  - All sensitive routes protected by Clerk guards
  - Use Clerk session handling
  - Validate JWT on server actions and API routes

Database rules
  - Supabase Postgres with RLS enabled
  - Tables: users, subscriptions, widget_config, analytics_events, knowledge_base
  - Enforce foreign keys and constraints
  - Use upsert for idempotent writes

Validation rules
  - Strong input validation on server actions
  - Validate user input against TypeScript interfaces

Security rules
  - Do not expose secret keys on frontend
  - Use environment variables for credentials
  - Implement CSP and secure cookies
  - Verify Stripe webhooks with signature validation

Testing rules
  - Unit tests for utilities and hooks
  - Integration tests for API routes and server actions
  - End-to-end tests for sign-up, widget embed, and billing flow
  - Use mocks for external services

Deployment rules
  - Deploy on Vercel or similar hosting with serverless functions
  - Configure Stripe webhooks
  - CI runs tests on PRs

Things Claude must not do
  - Do not implement direct database migrations in client code
  - Do not bypass authentication checks
  - Do not hardcode secrets
  - Do not bypass validation on server actions
  - Do not rely on deprecated Clerk APIs

Recommended Project Structure

/apps/saas-widget
  app/
    layout.tsx
    page.tsx
    components/
  libs/
  features/
  hooks/
  styles/
  public/
  scripts/
  knowledge-base/

Core Engineering Principles

• Strong typing and explicit interfaces across the stack
• Clear separation of concerns between UI, API, and data layer
• Secure by default with proper access controls
• Idempotent operations and deterministic deployments
• Observability through logs, metrics, and tracing

Code Construction Rules

• Follow Next.js App Router patterns; use server actions for data mutations
• Use TypeScript types for API payloads and database rows
• Use Supabase client on server and client with proper role-based access
• Guard all protected routes with Clerk middleware and server checks
• Implement Stripe billing with webhooks and customer portal integration
• Use embeddable script that loads a widget React component from a CDN or host
• Validate and sanitize all inputs on the server side

Security and Production Rules

• Never expose secret keys; store in environment variables
• Enable Row Level Security on Supabase tables
• Verify Stripe webhooks and sign payloads
• Use Content Security Policy, HTTPS, and secure cookies
• Regularly rotate API keys and monitor suspicious activity

Testing Checklist

• Unit tests for utilities, hooks, and components
• Integration tests for API routes and server actions
• End-to-end tests for sign-up, widget embed, and billing
• Linting, type checking, and pre-commit checks
• End-to-end deployment smoke test on staging

Common Mistakes to Avoid

• Hardcoding secrets in source code
• Skipping Supabase RLS and policies
• Using client-side API keys for privileged actions
• Overengineering the widget with unused features
• Ignoring accessibility and performance considerations

Related implementation resources: AI Agent Use Case for Custom Manufacturers Using Active Factory Floor Milestones To Send Real-Time Order Status Updates To Clients and Designing secure Server Actions with mandatory input schema validations at the server boundary.

FAQ

• Q: What stack does this CLAUDE.md Template target?
  A: Next.js App Router with TypeScript, Supabase, Clerk, Stripe, embeddable scripts, knowledge base, analytics, and billing.
• Q: How do I insert this template into Claude Code?
  A: Copy the code block under Copyable CLAUDE.md Template and paste into Claude Code for your project.
• Q: Can I customize the project structure?
  A: Yes, adapt folders under apps/saas-widget to suit your app architecture, while keeping the CLAUDE.md rules intact.
• Q: How are security rules enforced?
  A: Use Clerk-based guards, Supabase RLS, and verify Stripe webhooks; do not expose secrets on the client.
• Q: What should I test?
  A: Unit, integration, and end-to-end tests for auth, widget embed, billing flows, and analytics events.