CLAUDE.md Template for Next.js 16 + TimescaleDB + NextAuth.js + TypeORM

Overview

A CLAUDE.md template page for Next.js 16 + TimescaleDB time-series data, NextAuth.js authentication, and TypeORM. It provides a ready-to-paste Claude Code template to scaffold a production-ready app.

When to Use This CLAUDE.md Template

• When building a time-series application with Next.js 16 and TypeORM on PostgreSQL/TimescaleDB.
• When you need robust authentication with NextAuth.js and serverless deployment readiness.
• When you want a copyable Claude Code template that includes architecture, file structure, and security rules.

Copyable CLAUDE.md Template

# CLAUDE.md
Project role: You are Claude Code. Build a Next.js 16 app with TimescaleDB time-series data, NextAuth.js authentication, and TypeORM ORM. Ensure a clean architecture and scalable data model.
Architecture rules:
- Use Next.js 16 app router with app dir; server components where safe; client components for interactive UI.
- TimescaleDB as the database; hypertables for time-series data; PostgreSQL dialect for TypeORM.
- Centralized ORM in src/orm with data-source.ts; entities in src/orm/entities; migrations in src/orm/migrations.
File structure rules:
- Do not scatter ORM config in app code; keep in src/orm. Entities live in src/orm/entities.
- NextAuth config in src/auth/nextauth.ts; API routes under app/api.
- Env vars in .env; do not hard-code secrets.
Authentication rules:
- Use NextAuth.js with PostgreSQL (TimescaleDB) adapter; session store in DB; secure cookies.
- Require CSRF protection for credential flows; disable on trusted server calls.
Database rules:
- Connect to TimescaleDB; hypertable for time-series data; define constraints and indices properly.
- Use TypeORM migrations for schema changes; run migrations on startup in production.
Validation rules:
- Validate API inputs with a strict schema (eg Zod); never trust client payloads.
- Validate time-series ingestion payloads for timestamp, value, and tags.
Security rules:
- Do not expose DB credentials in client code.
- Use httpOnly secure cookies; enable CSRF protection; set strong secrets.
Testing rules:
- Unit tests for ORM entities and data-access methods; integration tests for API routes.
- E2E tests for authentication flows and timeseries ingestion.
Deployment rules:
- Use environment-based config; run migrations during startup; seed data in a controlled way.
Things Claude must not do:
- Do not perform raw DB dumps; do not bypass migrations; do not hard-code secrets.

Recommended Project Structure

myapp/
├─ app/
│  ├─ api/
│  │  ├─ auth/
│  │  │  └─ [...nextauth].ts
│  │  └─ timeseries/
│  │     └─ data.ts
│  ├─ layout.tsx
│  └─ page.tsx
├─ src/
│  ├─ orm/
│  │  ├─ data-source.ts
│  │  ├─ entities/
│  │  │  └─ TimeSeries.ts
│  │  └─ migrations/
│  ├─ lib/
│  │  └─ database.ts
│  ├─ config/
│  ├─ services/
│  └─ utils/
├─ .env
├─ package.json

Core Engineering Principles

• Clear separation of concerns between app, ORM, and auth layers
• Reproducible migrations and seed data
• Type-safe data access with TypeORM
• Secure by default with proper auth and session handling
• Performance-oriented indexing for hypertables

Code Construction Rules

• Use TypeORM DataSource with PostgreSQL driver; define entities under src/orm/entities
• Define migrations under src/orm/migrations and run on startup in production
• In NextAuth.js, store sessions in TimescaleDB via PostgreSQL adapter
• Define Timescale hypertables for time-series tables and create them via migrations
• Validate API payloads using a strict schema (Zod)
• All DB credentials read from environment variables

Security and Production Rules

• Use HTTPS; set secure cookies and httpOnly flags
• Store secrets in environment variables; never commit to VCS
• Limit data exposure via API and server-side rendering boundaries
• Enable CSRF protection for state-changing requests

Testing Checklist

• Unit tests for ORM entities and repository methods
• Integration tests for API routes with a test DB
• Migration tests to ensure schema changes apply cleanly
• End-to-end tests for authentication and data-ingestion flows

Common Mistakes to Avoid

• Skipping migrations or manually altering tables in production
• Hard-coding credentials or secrets
• Using client-side validation instead of server-side
• Ignoring TimescaleDB hypertable requirements

FAQ

Q1 How do I start using this CLAUDE.md Template with Next.js 16 and TimescaleDB?

A1 Start by configuring environment variables, installing dependencies, and running the migration script as described in the code block.

Q2 Can I adapt this for different authentication providers?

A2 Yes, by updating NextAuth.js providers in the NextAuth config.

Q3 How are time-series data ingested?

A3 Use an API route or server action to validate and store data into a TimescaleDB hypertable via TypeORM.

Q4 Where should I put migrations?

A4 Under src/orm/migrations and run automatically on startup in production.