stack.yaml

# frontend-stack-blueprint/stack.yaml
# Machine-readable stack manifest for LLMs and tooling
# This file is the single source of truth for versions.

schema_version: "1.0"
blueprint_version: "1.5.0"
updated: "2026-03-09"

core:
  typescript:
    min: ">=5.9.0"
    current: "5.9.3"
    install: "typescript"
  react:
    min: ">=19.2.0"
    current: "19.2.4"
    install: "react react-dom"
    types: "@types/react @types/react-dom"
  routing:
    default: "tanstack-router"
    alternative: "react-router"
    tanstack_router:
      min: ">=1.0.0"
      install: "@tanstack/react-router @tanstack/router-devtools"
    react_router:
      min: ">=7.1.0"
      install: "react-router"

build:
  vite:
    min: ">=7.0.0"
    current: "7.3.1"
    install: "vite"
    plugins: "@vitejs/plugin-react"
    node_requires: ">=20.19.0 || >=22.12.0"

tooling:
  package_manager:
    default: "pnpm"
    alternative: "npm"
    note: "pnpm is the priority package manager. Use Corepack to provision it by default; npm remains compatible but secondary."
  runtime:
    default: "node"
    alternative: "bun"
    default_requires: ">=20.19.0 || >=22.12.0"
    note: "Node.js is the default runtime. Bun is an alternative runtime only and does not replace pnpm as the default package manager."
  pnpm:
    status: "priority"
    install: "corepack enable pnpm"
    add: "pnpm add <package>"
    add_dev: "pnpm add -D <package>"
    dlx: "pnpm dlx <package>@latest <command>"
    exec: "pnpm exec <command>"
  bun:
    status: "alternative"
    min: ">=1.0.0"
    note: "Alternative JavaScript runtime for projects that validate Bun compatibility."

test:
  vitest:
    min: ">=3.2.0"
    recommended: ">=4.0.0"
    install: "vitest @testing-library/react @testing-library/jest-dom"

quality:
  husky:
    install: "husky"
    init: "pnpm exec husky init"
  lint_staged:
    install: "lint-staged"
  eslint:
    install: "eslint @eslint/js typescript-eslint"
  prettier:
    install: "prettier"

ui:
  radix:
    install: "@radix-ui/react-dialog @radix-ui/react-popover @radix-ui/react-select @radix-ui/react-tabs"
    note: "Install primitives individually as needed"
  shadcn_ui:
    status: "recommended"
    init: "pnpm dlx shadcn@latest init"
    note: "Copy-paste components, not an npm dependency"
  floating_ui:
    install: "@floating-ui/react"
  embla_carousel:
    install: "embla-carousel-react"
  cmdk:
    install: "cmdk"

styling:
  tailwind:
    min: ">=4.0.0"
    install: "tailwindcss @tailwindcss/vite"
  clsx:
    install: "clsx"
    note: "Always used with tailwind-merge via cn() helper"
  tailwind_merge:
    install: "tailwind-merge"
    note: "Resolves Tailwind class conflicts"
  motion:
    install: "motion"
    note: "Successor to framer-motion. Import from 'motion/react'"

forms:
  react_hook_form:
    install: "react-hook-form"
  zod:
    install: "zod @hookform/resolvers"

data_access:
  default: "prisma"
  note: "Prisma is the approved ORM default when server-side or edge data access is needed. Drizzle ORM remains under evaluation until it reaches v1 GA."
  prisma:
    status: "recommended-optional"
    min: ">=6.0.0"
    current: "6.18.0"
    install: "prisma @prisma/client"
    tooling: "prisma"
    note: "Recommended only when a project has backend, server-side, or edge runtime and needs ORM-backed relational data access. Do not install for purely static frontend apps. Cloudflare D1 is supported via the official Prisma D1 guide, but Prisma Migrate is not the default D1 workflow."

auth:
  better_auth:
    status: "recommended-optional"
    min: ">=1.0.0"
    current: "1.5.1"
    install: "better-auth"
    tooling: "@better-auth/cli"
    note: "Recommended when a project needs authentication. Requires a server-side runtime/auth handler and is not mandatory for public or static apps without login."

managed_services:
  neon:
    provider: "Neon"
    role: "database"
    engine: "postgres"
    status: "recommended-optional"
    evaluated: "2026-03-09"
    tooling: "neonctl"
    note: "Recommended when a project needs managed Postgres. `@neondatabase/serverless` is the preferred JS/edge integration only when the project actually needs direct JavaScript, serverless, or edge access."
  cloudflare_d1:
    provider: "Cloudflare D1"
    role: "database"
    engine: "sqlite"
    status: "recommended-optional"
    evaluated: "2026-03-09"
    tooling: "wrangler"
    note: "Recommended when a project needs Cloudflare-native serverless SQL with Workers or edge runtime. D1 has SQLite semantics, does not replace Postgres, and should not be added to purely static frontend apps."
  cloudflare_r2:
    provider: "Cloudflare R2"
    role: "object-storage"
    status: "recommended-optional"
    evaluated: "2026-03-09"
    tooling: "wrangler"
    note: "Recommended when a project needs object storage. Integrate via the S3-compatible API or Cloudflare bindings; no default npm package is mandated by this blueprint."
  cloudflare_kv:
    provider: "Cloudflare KV"
    role: "key-value-storage"
    status: "recommended-optional"
    evaluated: "2026-03-09"
    tooling: "wrangler"
    note: "Recommended when a project needs key-value storage for read-heavy or eventually consistent workloads in the Cloudflare ecosystem. It is not a relational or strongly consistent transactional store."
  resend:
    provider: "Resend"
    role: "transactional-and-marketing-email"
    status: "recommended-optional"
    evaluated: "2026-03-09"
    note: "Recommended when a project needs transactional email or audience/broadcast workflows. The `resend` SDK is the usual backend integration when email sending is required."

dates:
  date_fns:
    min: ">=4.1.0"
    install: "date-fns"
  date_fns_tz:
    install: "@date-fns/tz"
    note: "First-class timezone support via TZDate (date-fns v4+)"

state:
  zustand:
    status: "core"
    install: "zustand"
    note: "Primary client state manager. Lightweight, minimal boilerplate."
  tanstack_store:
    status: "under-evaluation"
    install: "@tanstack/store @tanstack/react-store"
    note: "Alpha (v0.x). Not GA yet. When v1 ships, TanStack Store becomes the priority state manager, replacing Zustand."
  tanstack_query:
    min: ">=5.60.0"
    install: "@tanstack/react-query @tanstack/react-query-devtools"

content:
  lexical:
    status: "primary"
    install: "lexical @lexical/react"
  prosemirror:
    status: "fallback"
    install: "prosemirror-state prosemirror-view prosemirror-model"
  shiki:
    install: "shiki"

i18n:
  formatjs:
    install: "react-intl"

observability:
  sentry:
    install: "@sentry/react"
  opentelemetry:
    install: "@opentelemetry/api @opentelemetry/sdk-trace-web"
  statsig:
    install: "@statsig/react-bindings"

icons:
  default: "lucide"
  lucide:
    install: "lucide-react"
  phosphor:
    install: "@phosphor-icons/react"
  tabler:
    install: "@tabler/icons-react"

targets:
  cloudflare_pages:
    status: "priority-optional"
    type: "cloud-frontend-hosting"
    evaluated: "2026-03-09"
    tooling: "wrangler"
    note: "Default cloud frontend deployment target when a project needs frontend hosting and no provider is specified. Cloudflare data services such as D1, KV, or R2 remain optional and should only be added when the project also has edge or server-side runtime needs."
  vercel:
    status: "secondary-optional"
    type: "cloud-frontend-hosting"
    evaluated: "2026-03-09"
    tooling: "vercel"
    note: "Secondary cloud frontend deployment target when explicitly requested or when Cloudflare Pages is not a fit."
  electron:
    min: ">=33.0.0"
    install: "electron"
    tooling: "@electron-forge/cli"
  tauri:
    min: ">=2.10.0"
    note: "Requires Rust toolchain"
  pwa:
    install: "vite-plugin-pwa"

banned:
  - { name: "any (type)", reason: "Use unknown + type guards" }
  - { name: "redux", reason: "Use Zustand" }
  - { name: "mobx", reason: "Use Zustand" }
  - { name: "styled-components", reason: "Use Tailwind CSS" }
  - { name: "emotion", reason: "Use Tailwind CSS" }
  - { name: "css-in-js (any)", reason: "Use Tailwind CSS" }
  - { name: "jest", reason: "Use Vitest" }
  - { name: "moment", reason: "Use date-fns" }
  - { name: "dayjs", reason: "Use date-fns" }
  - { name: "formik", reason: "Use React Hook Form + Zod" }
  - { name: "yup", reason: "Use Zod" }
  - { name: "class components", reason: "Use functional components" }
  - { name: "deep relative imports", reason: "Use @/* path aliases" }