CLAUDE.md Template: Newsletter SaaS with Next.js, TypeScript, Supabase, Clerk, Stripe (CLAUDE.md template)

Overview

CLAUDE.md template is a copyable Claude Code blueprint for building a complete Newsletter SaaS stack using Next.js, TypeScript, Supabase, Clerk, Stripe, with an AI writing assistant, subscriber management, and campaign analytics. This CLAUDE.md template is tailored to Next.js + TS + Supabase + Clerk + Stripe, with production-oriented constraints and a ready-to-paste instruction block for Claude Code.

Direct answer: Use this CLAUDE.md template to generate a production-grade Newsletter SaaS starter that stitches Next.js (App Router) with Supabase, Clerk authentication, Stripe billing, an AI writing assistant for composing newsletters, robust subscriber management, and campaign analytics. It includes a copyable Claude Code block, a stack-specific project structure, security guidelines, tests, and deployment notes.

When to Use This CLAUDE.md Template

• You need a production-ready starter for a Newsletter-as-a-Service using modern React tooling (Next.js, TS) with serverless-friendly patterns.
• You require integrated user authentication (Clerk), payments (Stripe), and a clean data model (Supabase) with RLS.
• You want to automate content generation with an AI writing assistant and track campaigns with analytics hooks.
• You need a comprehensive blueprint that you can paste into Claude Code to generate the boilerplate and guardrails, not just a high-level description.

Copyable CLAUDE.md Template

# CLAUDE.md

Project Role: You are a senior frontend/full-stack engineer tasked with delivering a production-grade Newsletter SaaS using Next.js, TypeScript, Supabase, Clerk, Stripe, an AI writing assistant, subscriber management, and campaign analytics. Produce a complete, modular, and secure starter with a ready-to-run Claude Code prompt. Favor clear file structure, explicit guardrails, and testable components.

Architecture Rules:
- Tech: Next.js 14 (App Router) + TypeScript
- Data: Supabase (Postgres) with Row Level Security (RLS) and audited schemas
- Auth: Clerk for authentication and user roles
- Payments: Stripe for subscriptions and one-time payments, with webhook verification
- AI Content: Integrated AI writing assistant for composing newsletters; prompts must be deterministic and auditable
- API: Edge-safe serverless functions for webhooks and heavy tasks
- Analytics: In-database analytics via Postgres and client-side dashboards
- Environment: Use environment-based config; avoid hard-coded secrets
- Deploy: Prefer Vercel or similar serverless host with CI/CD integration

File Structure Rules:
- Provide a minimal but complete repository layout tailored to Next.js + Supabase + Clerk + Stripe
- Do not include irrelevant folders or unused libraries
- Key folders: apps/web, apps/web/src, lib, components, hooks, services, pages/api or app/, prisma is not used

Authentication Rules:
- Clerk-based auth with roles: admin, editor, subscriber
- Admins manage pricing, campaigns, and settings; editors craft content; subscribers access newsletters
- All sensitive endpoints validated on the server side; no direct DB access from the client

Database Rules:
- Supabase Postgres with tables: users, subscriptions, newsletters, campaigns, subscribers, analytics, content
- Implement RLS policies restricting access by role and data ownership
- Encrypt sensitive fields at rest where appropriate (e.g., API keys, user data)

Validation Rules:
- Use strict schemas with Zod for inputs; do not rely on client-side validation for security
- Validate emails, URLs, and required fields; sanitize inputs to prevent XSS

Security Rules:
- CSRF protection for forms and API routes
- Validate Stripe webhook signatures
- Secrets managed via environment variables; rotate credentials regularly

Testing Rules:
- Unit tests for utilities and helpers
- Integration tests for API routes and auth flows
- E2E tests with Playwright for major user journeys (signup, subscription, newsletter creation)
- CI should run tests on PRs and merge

Deployment Rules:
- Deploy on Vercel or equivalent with environment-based config
- Connect a dedicated Supabase project for staging/production
- Configure Stripe webhooks and ensure webhook endpoints are secure

Do Not Do:
- Do not use Prisma or Mongoose (not part of this stack)
- Do not bypass RLS or expose direct DB access from the client
- Do not hardcode secrets or keys in code
- Do not implement business rules on the client without server/API guardrails

Recommended Project Structure

project-root/
├── apps/
│   └── web/
│       ├── (src/)
│       │   ├── app/
│       │   │   ├── newsletter/
│       │   │   │   └─ page.tsx
│       │   │   ├── admin/
│       │   │   │   └─ dashboard.tsx
│       │   │   └── subscriber/
│       │   │       └─ newsletter.tsx
│       │   ├── components/
│       │   ├── hooks/
│       │   ├── lib/
│       │   │   └── supabase.ts
│       │   └── styles/
│       ├── next.config.js
│       ├── tsconfig.json
│       └── package.json
├── lib/
│   ├── supabaseClient.ts
│   └── clerkClient.ts
├── services/
│   ├── stripe.ts
│   ├── aiWriter.ts
│   └── subscriberManager.ts
├── scripts/
│   └── seed.ts
├── public/
└── README.md

Core Engineering Principles

• Security first: enforce server-side validation, proper access control, and validated webhooks.
• Explicit contracts: clear interfaces between UI, API, and database layers.
• Separation of concerns: authentication, payments, content generation, and analytics live in distinct modules.
• Reliability: idempotent operations for webhook handling and retries for failed tasks.
• Observability: structured logging, metrics, and tracing for key workflows.

Code Construction Rules

• Do not bypass server-side validation for any input; rely on Zod schemas.
• Do not perform business logic in the client without API guards.
• Use strongly typed API routes and endpoints; export types for reuse.
• Do not hardcode API keys or secrets in code; fetch from environment vars.
• Prefer modular, testable components; avoid large monolith files.
• Structure code to support multi-tenant scenarios and scalable analytics data models.

Security and Production Rules

• Use Stripe webhook signing secrets and verify signatures on receipt of events.
• Implement CSRF protection on state-changing POST endpoints.
• Enable Supabase Row Level Security with role-based policies.
• Encrypt sensitive fields at rest where applicable; rotate credentials regularly.
• Limit data exposure by default; expose only necessary fields in API responses.

Testing Checklist

• Unit tests for utility functions and data transformations.
• Integration tests for auth flows, API routes, and Stripe webhooks.
• End-to-end tests for signup, subscription, newsletter creation, and content generation.
• CI runs linting, type checks, tests, and build validation on PRs.

Common Mistakes to Avoid

• Assuming client-side validation is sufficient for security.
• Exposing Stripe or API keys in frontend code or public repositories.
• Skipping RLS policies or relying on naive authorization checks.
• Mixing content generation with production data paths without proper validation.

Related implementation resources: AI Use Case for Software Agencies Using Github Copilot To Accelerate Boilerplate Code Generation for New Client Mvps and Skill Files for PMs: Building Realistic Clickable SaaS Demos with CLAUDE.md Templates.

FAQ

Q: What is included in this CLAUDE.md Template?

A: A copyable Claude Code prompt, stack-specific file structure, and guardrails for a production-ready Newsletter SaaS.

Q: Which stack does this template target?

A: Next.js (App Router) with TypeScript, Supabase, Clerk, Stripe, and an AI writing assistant.

Q: How do I customize the AI prompts?

A: Modify the aiWriter.ts prompts and the Claude Code block; align prompts with your content guidelines and brand voice.

Q: How is security addressed?

A: RLS policies, Stripe webhook validation, CSRF protection, and environment-based secret management are included.

Q: How do I deploy this template?

A: Deploy on a serverless host like Vercel; connect a separate Supabase project; configure Stripe webhooks and environment variables.

FAQ (structured)

// FAQ Schema (embedded for quick reference)