ADR-0002 App framework
Company standard full-stack app framework — TanStack Start.
- Decision
- TanStack StartBuild the app
- Status
- Accepted
- Date
- Scope
- Company-wide default for all new apps
Connections
Builds on
Cited by
- 0001UI framework
- 0003Deploy target
- 0004API layer
- 0009Auth
- 0010Rate limiting
- 0011Styling
- 0012Data fetching & state
- 0018Tables
- 0019Virtual lists
- 0020Charts
- 0021Markdown
- 0022Syntax highlighting
- 0024Keyboard shortcuts
- 0025AI SDK
- 0026Project structure
- 0031Internationalization
- 0034Dates, time zones & money
- 0035Runtime & toolchain
Context
Section titled “Context”React (ADR-0001) is a UI library, not a full-stack framework. We need routing, SSR/streaming, server functions, data loading, and build tooling as one coherent layer. This choice shapes the deploy target (ADR-0003) and everything after.
Options considered
Section titled “Options considered”1. TanStack Start
Section titled “1. TanStack Start”Full-stack React framework from the TanStack team, built on TanStack Router (type-safe routing) and Vite. Server functions, streaming SSR, deploy-anywhere adapters.
Pros
- Type-safe end to end: routes, params, search, server functions — TypeScript flows through everything
- Framework-agnostic deployment: Vercel, Cloudflare, Node/Docker — no lock-in
- Vite-based: fast dev, standard build output
- Server functions are simple typed RPC — no separate API layer needed for most apps
- Aligns with the TanStack ecosystem (Query, Table, Form) we can adopt piecemeal later
Cons
- Younger than Next.js; smaller community, fewer Stack Overflow answers
- API surface moved fast before 1.0 (stable since 2026-10-13, APIs now committed)
- Less hand-holding; you own more architecture decisions
2. Next.js
Section titled “2. Next.js”The incumbent React meta-framework.
Pros
- Biggest ecosystem and community; every problem has a tutorial
- Vercel deployment is zero-friction
- Server components and caching are powerful at scale
Cons
- Vercel-shaped: self-hosting works but is a second-class citizen; conflicts with our Docker deploy target (ADR-0003)
- Caching semantics are increasingly complex and surprising
- App Router churn has been costly for teams
3. Remix / React Router v7
Section titled “3. Remix / React Router v7”Data-loading-focused React framework, now merged into React Router v7.
Pros
- Excellent data-loading model (loaders/actions)
- Deploy-anywhere, standards-based (web fetch API)
- Stable, boring, predictable
Cons
- Weaker type-safety story than TanStack Start
- Future direction folded into React Router; the “Remix” identity is fading
- Smaller mindshare than Next.js
Decision
Section titled “Decision”TanStack Start is the company-standard full-stack framework for all new React apps.
The deciding factors: end-to-end type safety, deploy-anywhere adapters (works with our Docker target, ADR-0003), Vite tooling, and typed server functions that eliminate a separate API layer for most apps. We accept the smaller community in exchange for the best TypeScript experience in the React ecosystem.
Consequences
Section titled “Consequences”Easier: type-safe routing and data flow, deployment flexibility, incremental adoption of TanStack Query/Table/Form.
Harder: fewer copy-paste answers than Next.js; the team must be comfortable reading TanStack docs and source. Hiring screens should probe for TypeScript depth, not Next.js experience.
Given up: Next.js’s ecosystem gravity and Vercel zero-friction deploys. Accepted — deploy flexibility and type safety matter more to us.