A complete reference for building modern web applications with Next.js, React, TypeScript, and the tools that work best together.
Two complementary layers:
| Layer | Purpose | When to Use |
|---|---|---|
| Docs (this site) | Reference material, setup guides, integration patterns | Starting a new project or setting up a tool |
Rules (rules/) |
AI agent coding rules via Ruler | Copy to .ruler/ in any project → generates CLAUDE.md |
The docs teach how to set things up. The rules tell AI agents how to write code following these conventions.
| Package | Minimum | Why |
|---|---|---|
| next | 16.0.0 | Turbopack stable, async params/headers |
| react | 19.0.0 | ref-as-prop, use() hook, no forwardRef |
| typescript | 5.8.0 | Improved inference |
| tailwindcss | 4.0.0 | Config-free, CSS-first |
| zod | 4.0.0 | Breaking inference changes |
| node | 20.9.0 | Required for Next.js 16 |
See version-requirements.md for breaking changes and upgrade paths.
Next.js 16.x + React 19.x + TypeScript 5.9.x
Tailwind v4 + PostCSS
Biome + Ultracite (formatting/linting)
Drizzle ORM + Neon (PostgreSQL)
Clerk (auth) + tRPC (API)
TanStack Query (data fetching)
Playwright (E2E) + Vitest (unit)
pnpm + Turborepo (monorepos)
| File | Purpose |
|---|---|
| new-project-checklist.md | Bootstrap a new project step-by-step |
| production-checklist.md | Pre-launch: SEO, analytics, deployment |
| project-structure.md | Monorepo vs single-app patterns |
| File | Purpose |
|---|---|
| version-requirements.md | Mandatory versions + breaking changes |
| stack-overview.md | Complete tech stack with versions |
| dependencies.md | All dependencies by category |
| scripts.md | Standard npm scripts |
How to set up and use specific tools:
| File | Purpose |
|---|---|
| clerk-auth.md | Authentication |
| drizzle-neon.md | Database ORM + serverless PostgreSQL |
| trpc.md | Type-safe APIs |
| env-validation.md | Type-safe env vars (Zod, not t3-env) |
| zustand.md | State management (when to use vs Context) |
| forms.md | Form handling (native, react-hook-form, Zod) |
| resend-email.md | Transactional email |
| openrouter.md | Multi-model AI |
| fal-ai.md | Image generation |
| voyage-embeddings.md | Text/image embeddings |
| uploadthing.md | File uploads |
| biome-ultracite.md | Formatting and linting |
The rules/ directory contains coding conventions formatted for Ruler—a tool that generates CLAUDE.md, .cursorrules, etc.
To use in a project:
# Copy rules to your project
cp -r /path/to/build/rules /your-project/.ruler
# Rename the index
mv /your-project/.ruler/README.md /your-project/.ruler/agents.md
# Generate agent files
npx @intellectronica/ruler applySee ruler.md for full documentation and rules/README.md for the rule index.
| Category | Files |
|---|---|
| Code | code-style, typescript, react, nextjs, tailwind |
| Workflow | git, testing, env, turborepo, integrations |
| Interface | animation, forms, interactions, layout, design, performance, accessibility |
Code is always canonical. No backward compatibility layers, deprecation warnings, or legacy patterns. When updating patterns or APIs, update ALL usage sites immediately. The codebase reflects current best practices only.
This means:
- No migration periods or compatibility shims
- Refactor fearlessly
- The current code IS the way
| Area | Preference |
|---|---|
| Migrations | db:push over formal migrations |
| Components | Base UI primitives over Radix |
| Scaffolding | shadcn (own the code) |
| Gray palette | gray-* only (not slate/zinc/neutral) |
| AI text | google/gemini-2.5-flash via OpenRouter |
| AI images | fal-ai/gpt-image-1.5 |
| Embeddings | voyage-3-large (text), voyage-multimodal-3 (images) |