CLAUDE.md Template: Next.js 16 + SingleStore Real-Time Data + Custom JWT Auth + Drizzle ORM

Overview

A CLAUDE.md template for building a real-time Next.js 16 application using SingleStore DB, custom JWT authentication, and Drizzle ORM. It provides Claude Code instructions that you can paste into CLAUDE.md to scaffold the stack end-to-end.

When to Use This CLAUDE.md Template

• When building a real-time dashboard with Next.js 16 App Router and SingleStore Real-Time Data features.
• When you need JWT-based authentication with secure HttpOnly cookies.
• When you want to integrate Drizzle ORM with Next.js and TypeScript.
• When you require a repeatable CLAUDE.md template for this technology stack.

Copyable CLAUDE.md Template

# CLAUDE.md
Project role: Senior Full Stack Engineer focused on Next.js 16, SingleStore Real-Time Data, Drizzle ORM, and JWT auth.

Architecture rules:
- Build with Next.js 16 App Router using server components for data fetch and client components for UI.
- Implement a dedicated real-time data path using SingleStore CHANGEFEED to stream changes to connected clients via a WebSocket gateway.
- Use Drizzle ORM for type-safe SQL queries and migrations.
- Centralize auth in a custom JWT provider; issue, rotate, and revoke tokens securely.
- All API routes are stateless; rely on signed cookies instead of local storage.

File structure rules:
- Place app routes under app/ and next.config.js at repo root.
- Use drizzle/ for Drizzle ORM setup (drizzle.config.ts, migrations/, schema.ts).
- Use lib/auth/ for JWT utilities (generateToken, verifyToken, refresh).
- Use lib/db/ for SingleStore connection pool and CHANGEFEED listeners.
- Use components/ and hooks/ for UI logic and data fetching wrappers.
- Keep environment variables in .env.local and accessed via process.env.

Authentication rules:
- Use HttpOnly, Secure cookies for access and refresh tokens.
- Verify tokens on every protected API route; reject invalid tokens with 401.
- Enforce short-lived access tokens (e.g., 15 minutes) with rotation via refresh token.
- Do not store tokens in localStorage or sessionStorage.

Database rules:
- Use SingleStore DB connection pool; use CHANGEFEED for real-time events.
- Use parameterized queries to prevent SQL injection.
- Use migrations with Drizzle to evolve schema; keep types generated.

Validation rules:
- Validate inputs on both client and server side; use zod for runtime validation.
- Normalize and sanitize data to avoid XSS/SQL injection.

Security rules:
- Use CSRF protection for state-changing requests.
- Do not leak stack traces to clients; map errors to user-friendly messages.
- Enforce TLS in production; rotate keys.

Testing rules:
- Unit tests for utilities; integration tests for auth and DB interactions.
- Mock SingleStore with a test container; use real CHANGEFEED streams in integration tests where possible.
- E2E tests cover login, real-time updates, and data CRUD.

Deployment rules:
- Deploy with environment-specific configs; set NEXT_PUBLIC variables to client-safe values only.
- Use CI to run tests on pull requests; run migrations in deployment.

Things Claude must not do:
- Do not bypass auth checks or expose internal DB calls.
- Do not emit raw SQL in responses.
- Do not assume browser storage for tokens.
- Do not bypass type-safety checks; avoid any unsafe casts.

Recommended Project Structure

my-nextjs-app/
  app/
    layout.jsx
    page.jsx
  drizzle/
    drizzle.config.ts
    schema.ts
    migrations/
  lib/
    auth/
      jwt.ts
      verify.ts
    db/
      client.ts
      changelog.ts
  components/
  hooks/
  public/
  next.config.js
  tsconfig.json
  package.json

Core Engineering Principles

• Embrace type-safety with Drizzle ORM and TypeScript across API routes and UI components.
• Prefer server-first rendering for data-heavy pages to optimize real-time performance.
• Minimize surface area for authentication; keep secrets on the server and cookies HttpOnly.
• Ensure real-time data integrity via CHANGEFEED and a robust WebSocket gateway.
• Maintain clear separation of concerns between data access, business logic, and presentation.

Code Construction Rules

• Use Drizzle ORM for all SQL queries; avoid raw SQL in business logic except in migrations.
• Type exports from drizzle.config.ts must be used for API input/output schemas.
• All API routes must use middleware for auth and input validation (Zod schemas).
• Indicate data models with explicit types and avoid any unsafe any usage.
• Use TSConfig and eslint/prettier to enforce coding standards in CI.
• Do not use localStorage for tokens or app state.
• Do not bypass server-side rendering for protected pages.

Security and Production Rules

• Implement HttpOnly cookies for both access and refresh tokens; rotate tokens on refresh.
• Validate JWTs with a secret key from environment variables; never log secrets.
• Enable CSRF protection for mutating requests; enforce content security policy.
• Use database migrations to evolve schema in a controlled manner.
• Disable debugging logs in production; ensure proper error boundaries.

Testing Checklist

• Unit tests for auth utilities and utilities in lib/.
• Integration tests for API routes; simulate SingleStore interactions with a test container.
• End-to-end tests for login, token refresh, and real-time updates.
• Performance tests for real-time data streaming under load.

Common Mistakes to Avoid

• Storing tokens in localStorage or exposing token keys in frontend code.
• Using unsafe queries or skipping input validation.
• Forgetting to establish CHANGEFEED listeners for real-time data.
• Not rotating JWTs or failing to revoke compromised tokens.
• Over-fetching data leading to unnecessary network load.

FAQ