CLAUDE.md Template: Next.js + TypeScript + Supabase + Clerk + Stripe — Website Analytics SaaS

Overview

CLAUDE.md template is a copyable Claude Code blueprint to help engineers implement a Website Analytics SaaS using Next.js, TypeScript, Supabase, Clerk, Stripe, AI traffic insights, conversion funnels, and SEO suggestions. It provides a ready-to-paste CLAUDE.md block and a stack-specific blueprint you can adapt for production.

Direct answer: This CLAUDE.md Template yields a complete, ready-to-paste Claude Code instruction block for a Next.js + TS + Supabase + Clerk + Stripe SaaS with AI insights and SEO features.

When to Use This CLAUDE.md Template

• When building a Website Analytics SaaS with a modern frontend (Next.js) and a scalable backend (Supabase).
• When you need Clerk-based authentication and Stripe-based billing integrated into the stack.
• When you require AI-driven traffic insights, conversion funnel tracking, and SEO suggestions as core features.
• When you want a copyable Claude Code blueprint that enforces architecture and deployment best practices.

Copyable CLAUDE.md Template

# CLAUDE.md

Role: You are a Senior Software Architect for a Website Analytics SaaS stack.

Stack: Next.js, TypeScript, Supabase, Clerk, Stripe, AI traffic insights, conversion funnels, SEO suggestions.

Architecture Rules:
- Build with Next.js App Router; TypeScript; use server components for data access; client components for dashboards.
- Use Supabase as the backend database and as the primary data store for events, analytics, and user data.
- Clerk handles authentication; rely on Clerk's Next.js SDK for session management.
- Stripe for subscriptions; implement webhooks for events and plan changes.
- AI traffic insights module processes raw events into actionable recommendations and trend analyses.
- SEO suggestions engine recommends on-page improvements based on analytics data.
- Each data path is bounded by explicit data contracts; avoid leaking internal IDs to the client.

File Structure Rules:
- Keep a clean modular layout under src/
- app/ contains all UI routes; lib/ contains shared logic; services/ contains API clients; components/ holds UI primitives.
- Do not place DB logic in UI folders; separate concerns clearly.
- Do not include unrelated tech stacks in this CLAUDE.md.

Authentication Rules:
- Use Clerk for auth with email/password and OAuth providers.
- Gate all data access with server actions or protected API routes.
- Redirect unauthenticated users to /sign-in.

Database Rules:
- Supabase Postgres with tables: users, organizations, subscriptions, projects, analytics_events, funnels, seo_suggestions, ai_insights, audit_logs.
- Enforce RLS policies to limit access to user_id and organization_id.
- Use parameterized queries; never interpolate user input into SQL strings.

Validation Rules:
- Validate payloads with strict TypeScript interfaces; use runtime validation for external inputs.
- Ensure numeric fields, dates, and IDs have correct types before processing.

Security Rules:
- Do not log secrets or private keys in logs.
- Sign and verify Stripe webhooks; validate signatures for all payment events.
- Implement CSRF protection for mutating endpoints.

Testing Rules:
- Unit tests for utilities and data validation using Vitest.
- Integration tests for API routes and Clerk-auth flows.
- End-to-end tests for signup, billing, and analytics dashboards.

Deployment Rules:
- Deploy on Vercel with environment variables: NEXT_PUBLIC_SUPABASE_URL, SUPABASE_ANON_KEY, CLERK_FRONTEND_API, CLERK_API_KEY, STRIPE_WEBHOOK_SECRET.
- Wire Stripe webhooks to the deployment domain; validate webhook signatures.
- Use edge middleware for authentication and rate-limiting where appropriate.

Things Claude Must Not Do:
- Do not access server secrets on the client; never embed private keys in client code.
- Do not bypass Clerk or Stripe validation; never trust client-sent IDs without verification.
- Do not hardcode production data in tests or code.

Recommended Project Structure

my-analytics-saas/
  src/
    app/
      dashboard/
        page.tsx
        layout.tsx
      analytics/
        page.tsx
    lib/
      supabase.ts
    components/
      ui.tsx
      analytics-card.tsx
    services/
      analytics-service.ts
      seo-service.ts
    styles/
      globals.css
  db/
    schema.sql
  README.md

Core Engineering Principles

• Single source of truth: all analytics data flows through strongly typed contracts.
• End-to-end type safety with TypeScript across client and server boundaries.
• Secure auth and billing: Clerk for auth; Stripe for subscriptions; protect endpoints with server-side checks.
• Data-first architecture: define data models in Supabase; never duplicate across services.
• Observability: structured logs, metrics, and tracing for production issues.
• Deterministic tests and predictable deployments to avoid drift.

Code Construction Rules

• Use Next.js App Router with TS; separate server actions from client components.
• Prefer API Routes or Edge Functions for sensitive data access; never call DB directly from UI.
• Define TypeScript interfaces for all payloads and responses; validate at runtime with a schema validator.
• Encapsulate Supabase client initialization; avoid leaking keys to the client.
• Modularize the AI insights and SEO suggestions as independent services with clear interfaces.

Security and Production Rules

• RLS enabled on all tables; policies bound to user_id and organization_id.
• Webhooks verified using Stripe signature; store only minimal necessary data in events.
• Environment variables managed through CI/CD; never commit secrets.
• CSRF protection on mutating endpoints; use proper HTTP verbs.

Testing Checklist

• Unit tests for utilities and data validation functions.
• Integration tests for auth flows and API routes.
• End-to-end tests for signup, billing, and analytics dashboards.
• CI checks run on PRs; ensure type checks and lint pass.

Common Mistakes to Avoid

• Hardcoding secrets or keys in code or environment files.
• Skipping Stripe webhook signature verification.
• Mixing client and server logic; calling DB from the UI layer directly.
• Ignoring RLS policies and over-fetching data to the client.

Related implementation resources: AI Use Case for Athletic Coaches Using Wearable Heart Rate Data To Prevent Athlete Overtraining and Injury Risks and Production-grade billing logic governed by project rules.

FAQ

• What is a CLAUDE.md Template? A copyable Claude Code blueprint that defines role, architecture, and rules to build a specific stack as a CLAUDE.md page.
• Which files should I customize first? Start with the CLAUDE.md code block to understand architecture, then tailor the file structure and services for your project.
• How do I handle authentication with Clerk in this template? Use Clerk’s Next.js SDK and server actions to gate data fetching and protect routes.
• How is data secured in Supabase with RLS? Enable Row-Level Security and implement policies that constrain access by user_id and organization_id.
• How do I deploy this SaaS to Vercel with Stripe webhooks? Configure environment vars, deploy to Vercel, and verify Stripe signatures in webhooks.