CLAUDE.md Template for Next.js + TypeScript + Supabase + Clerk + Stripe: AI Knowledge Base SaaS

Overview

A CLAUDE.md template page for building a complete AI Knowledge Base SaaS powered by Next.js, TypeScript, Supabase, Clerk, Stripe, semantic search, article generation, and a customer support widget. This page is a copyable CLAUDE.md template that developers can paste into Claude Code to bootstrap a production-ready project with all stack-integrated primitives.

Direct answer: This CLAUDE.md template provides a structured Claude Code block and stack-specific rules to implement a full AI knowledge base with secure auth, payments, semantic retrieval, AI-generated articles, and a live support widget.

When to Use This CLAUDE.md Template

• Starting a new AI Knowledge Base SaaS using Next.js, TypeScript, Supabase, Clerk, Stripe.
• Standardizing architecture for semantic search-enabled article generation and a customer support widget.
• Onboarding new engineers with a concrete, copyable Claude Code blueprint.
• Prototyping rapid proof-of-concept to production migrations with clear deployment rules.

Copyable CLAUDE.md Template

# CLAUDE.md

Role: You are Claude Code, a production-ready software agent that writes Claude Code blocks to scaffold a Next.js + TypeScript + Supabase + Clerk + Stripe AI Knowledge Base SaaS. The blocks must be paste-ready and self-contained.

Architecture rules:
- Tech stack: Next.js (App Router), TypeScript, Supabase (Postgres), Clerk (auth), Stripe (billing), semantic search (Postgres FTS / external vector store as needed), article generation, and a responsive support widget.
- Follow a modular, testable architecture with clear separation between UI, API, and data layers.
- Use server components for data-sensitive operations; keep client components lean.
- Prefer strict type-safety (TypeScript), runtime validation (Zod), and robust error handling.
- Ensure accessible UI and responsive design patterns.

File structure rules:
- src/app/ ... (App Router)
- src/components/ ... reusable UI pieces
- src/hooks/ ... React hooks
- src/lib/ ... shared utilities
- src/services/ ... API adapters and business logic
- src/pages/api/ ... API routes (Next.js API Routes if needed)
- public/ ... static assets

Authentication rules:
- Use Clerk for authentication and session management.
- Guard pages and API routes with requireAuth where sensitive data is processed.
- Store user roles in Supabase and enforce access control at the API layer.

Database rules:
- Use Supabase with Postgres; enable Row Level Security (RLS) on all user data tables.
- Define policies for knowledge base articles, user profiles, and billing records.
- Never expose service_role keys in frontend; use server-side calls with restricted API keys.

Validation rules:
- Validate all input on both client and server; use Zod schemas for API payloads.
- Normalize and sanitize all strings; enforce length and allowed pattern constraints.

Security rules:
- Use HttpOnly cookies for sessions; set Secure and SameSite flags.
- Implement CSRF protection for state-changing endpoints.
- Enforce content security policy (CSP) and strict transport security (HSTS).

Testing rules:
- Unit tests for utilities and services; integration tests for API handlers; E2E tests for user flows.
- Use Playwright for end-to-end tests; mock external calls where appropriate.

Deployment rules:
- Deploy on Vercel; configure environment variables securely; enable preview environments.
- Ensure production builds pass all tests and linting; enable automatic deployment on PR merges.

Things Claude must not do:
- Do not hardcode secrets; do not bypass server-side validation; do not instantiate clients with elevated privileges in frontend code.
- Do not skip tests or degrade error handling for edge cases.

Recommended Project Structure

my-ai-kb-app/
  package.json
  tsconfig.json
  next.config.js
  .env.local
  /public
  /src
    /app
      /layout.tsx
      /page.tsx
      /kb
        /[slug]
          /page.tsx
      /api
        /auth
        /kb
    /components
      /ui
      /widgets
    /hooks
    /lib
      /apiClient.ts
      /validators.ts
    /services
      /billing.ts
      /search.ts
      /articles.ts
    /styles
  /scripts
  /db

Core Engineering Principles

• Explicit, stack-specific architecture to minimize drift and onboarding friction.
• Strong typing and runtime validation for every boundary (client, API, DB).
• Security by default: least privilege, proper auth, and secure data handling.
• Testability: unit, integration, and E2E tests with CI integration.
• Performance: efficient semantic search, caching, and streaming article generation when possible.
• Maintainability: clear module boundaries and documentation within Claude Code blocks.

Code Construction Rules

• Prefer App Router with server components for data-heavy pages.
• TypeScript everywhere; strict mode; no implicit any.
• Use Zod for input validation and schema inference.
• Keep UI components pure and reusable; avoid duplicating logic.
• API routes should be lean; reuse shared services for business logic.
• All external requests should be centralized in a service layer with proper error handling.
• Be explicit about what Claude can and cannot generate; avoid unsafe or non-deterministic patterns.

Security and Production Rules

• Enable Supabase Row Level Security and define per-table policies for activities, articles, and billing.
• Authenticate all protected endpoints via Clerk; validate sessions on server side.
• Use Stripe Webhooks securely; verify signatures and log events with minimal data retention.
• Store secrets in environment variables; never commit secrets to the repository.
• Enforce CSP, secure cookies, CSRF protection, and consistent HTTPS usage.

Testing Checklist

• Unit tests for utilities, validators, and services.
• Integration tests for API routes with a real or mocked Supabase instance.
• End-to-end tests covering sign-in, knowledge base search, article generation, and widget usage.
• CI workflow runs tests, linting, and type checks on pull requests.

Common Mistakes to Avoid

• Assuming client-side code is safe to access secrets; never expose service keys or admin endpoints.
• Skipping server-side validation and trust in client data.
• Over-fetching data or leaking DB schemas in API responses.
• Under-structuring files; creating monolithic modules with mixing concerns.

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 maintainable AI middleware.

FAQ

Q: What is a CLAUDE.md Template?

A: A copyable Claude Code instruction block designed to bootstrap a stack-specific project.

Q: Which stack is this template for?

A: Next.js, TypeScript, Supabase, Clerk, Stripe, semantic search, article generation, and a support widget.

Q: Can I paste the CLAUDE.md block into Claude Code as-is?

A: Yes; it’s written to be paste-ready with explicit rules and file structure guidance.

Q: Does this template enforce security best practices?

A: Yes; it includes authentication, authorization, encryption considerations, and secure deployment rules.

Q: How do I extend the knowledge base features?

A: Extend services/ and hooks/ with new search connectors, article templates, and widget integrations while keeping the architecture boundaries intact.