The canonical frontend stack reference for AI coding agents.
A public repository that serves as the single source of truth for modern frontend technology decisions. Designed from the ground up to be read and applied by AI coding agents (Claude Code, GitHub Copilot, Codex, Cursor, Gemini) when bootstrapping or contributing to any new frontend project.
- Specification of the recommended frontend stack for any new project
- Prescriptive, versioned documentation optimized for LLMs
- Architectural principles and quality rules that agents must follow
- An evolving reference with semantic versioning
- Not a boilerplate/template with executable code
- Not specific to web OR desktop — it's for both and more
- Not documentation for any single technology
┌──────────────────────────────────────────────────────────────┐
│ FRONTEND STACK BLUEPRINT │
├──────────────────────────────────────────────────────────────┤
│ │
│ LANGUAGE TypeScript ≥5.9 (strict, no `any`) │
│ UI FRAMEWORK React ≥19.2 (functional only) │
│ ROUTING TanStack Router ≥1 (default) │
│ React Router ≥7.1 (alternative) │
│ TOOLING pnpm (priority) · Bun ≥1 (runtime alt) │
│ BUILD Vite ≥7 (Node.js >=20.19 or >=22.12) │
│ TEST Vitest ≥3.2 (4.x recommended) │
│ QUALITY Husky + lint-staged + ESLint + Prettier │
│ │
│ COMPONENTS Radix UI · Floating UI · Embla · cmdk │
│ UI PRE-STYLED shadcn/ui (recommended) │
│ STYLING Tailwind CSS ≥4 + clsx + tailwind-merge │
│ ANIMATION Motion (`import from 'motion/react'`) │
│ │
│ FORMS React Hook Form + Zod │
│ DATA ACCESS Prisma ≥6 (optional) │
│ AUTH (opt) Better Auth ≥1 │
│ MANAGED (opt) Neon Postgres · Cloudflare D1 │
│ Cloudflare R2 · Cloudflare KV · Resend │
│ DATES date-fns ≥4.1 (+@date-fns/tz) │
│ STATE Zustand │
│ SERVER STATE TanStack Query ≥5.60 │
│ │
│ RICH TEXT Lexical (primary) · ProseMirror (fallback) │
│ SYNTAX Shiki │
│ I18N Format.js + react-intl │
│ │
│ OBSERVABILITY Sentry · OpenTelemetry · Statsig │
│ ICONS Lucide (default) | Phosphor | Tabler │
│ │
├──────────────────────────────────────────────────────────────┤
│ TARGETS (opt) Browser · Cloudflare Pages · Vercel │
│ Electron · Tauri · PWA │
└──────────────────────────────────────────────────────────────┘
This repository provides multiple entry points optimized for different coding agents:
| File | Agent | Purpose |
|---|---|---|
CLAUDE.md |
Claude Code | Full entry point with deep-dive links |
AGENTS.md |
Universal | AGENTS.md standard (compact) |
.cursor/rules/frontend-stack-blueprint.mdc |
Cursor IDE | Cursor rules (modern format) |
.cursorrules |
Cursor (legacy) | Legacy format (kept for compat) |
llms.txt |
Any LLM | Structured index |
llms-full.txt |
Any LLM | Complete stack in one file |
stack.yaml |
Tooling | Machine-readable manifest |
.github/copilot-instructions.md |
GitHub Copilot | Repository-level instructions |
Claude Code — Add to your project's CLAUDE.md:
@../frontend-stack-blueprint/CLAUDE.md
GitHub Copilot — The repo includes .github/copilot-instructions.md which Copilot reads automatically. You can also reference AGENTS.md.
Cursor — The repo includes .cursor/rules/*.mdc (modern) and .cursorrules (legacy). Cursor auto-reads project rules from .cursor/rules/.
Any Agent — Point the agent to llms-full.txt for complete context.
- Official CLI-First: if official docs recommend a CLI, agents must prefer that CLI over manual scaffolding.
- Impact Preflight: before any official CLI execution, agents must evaluate file changes, overwrite risk, structural conflicts, and config compatibility.
- If impact is non-trivial or uncertain, agents must ask for developer confirmation before running the CLI.
frontend-stack-blueprint/
│
├── 📋 Entry Points (Tier 0)
│ ├── CLAUDE.md / AGENTS.md / .cursor/rules/*.mdc
│ ├── .cursorrules (legacy) / .github/copilot-instructions.md
│ ├── llms.txt / llms-full.txt
│ └── stack.yaml
│
├── 📦 stack/ (Tier 1 — The Stack)
│ ├── STACK.md Full manifesto
│ ├── architecture.md Mandatory principles
│ ├── core.md TypeScript, React, Routing
│ ├── tooling.md pnpm, Node.js, Bun
│ ├── build-and-test.md Vite, Vitest, Quality
│ ├── ui.md Radix, shadcn/ui, Floating UI
│ ├── forms.md RHF + Zod
│ ├── data-access.md Data Access (optional)
│ ├── auth.md Better Auth (optional)
│ ├── managed-services.md Managed Services (optional)
│ ├── styling.md Tailwind, Motion
│ ├── state-and-data.md Zustand + TanStack Query
│ ├── dates.md date-fns
│ ├── content.md Lexical, ProseMirror, Shiki
│ ├── i18n.md Format.js
│ ├── observability.md Sentry, OTel, Statsig
│ └── icons.md Lucide, Phosphor, Tabler
│
├── 🎯 targets/ (Tier 2 — Optional)
│ ├── cloudflare-pages.md / vercel.md
│ └── electron.md / tauri.md / pwa.md
│
├── 📖 guides/ (Tier 2)
│ ├── new-project-setup.md
│ ├── package-versions.md
│ ├── project-structure.md
│ └── migration-paths.md
│
├── 🔧 templates/ (Tier 2)
│ ├── tsconfig / vite / vitest / tailwind / eslint configs
│ ├── cn-utility.md / zod-form-example.md
│
├── 💡 rationale/ (Tier 3 — Why Each Choice)
│ ├── why-pnpm.md / why-bun-runtime.md
│ ├── cloudflare-pages-vs-vercel.md
│ ├── why-prisma.md / why-cloudflare-d1.md / why-cloudflare-kv.md
│ ├── why-neon.md / why-cloudflare-r2.md / why-resend.md
│ └── why-*.md files for every technology
│
└── 🔮 backlog/ (Tier 4 — Evolution)
├── ROADMAP.md / under-evaluation.md / deprecated.md
| Type | Bump | Examples |
|---|---|---|
| MAJOR | X.0.0 | Swap core tech (React → other), new principle |
| MINOR | 1.X.0 | New lib, new target, new category |
| PATCH | 1.0.X | Version bump, docs fix |
See CHANGELOG.md for history.
See .github/CONTRIBUTING.md for guidelines on proposing additions, removals, and upgrades.
⚠️ Note on entry point sync: Multiple files duplicate stack rules (CLAUDE.md,AGENTS.md,.cursor/rules/*.mdc,llms-full.txt). When updating rules, ensure all entry points are updated consistently.
MIT — see LICENSE for details.