All implementation for the rewrite lives here. The old v11 tree, in the repo's v11/ (packages/, examples/, …), is reference only until it is deleted at 12.0.0. The docs site, every version's, is the repo's www/.
Agents: start with AGENTS.md. Design docs live in .agent-docs/. Brief: .agent-docs/decisions/brief.md.
User docs: v12.trpc.io/v12/docs, written in www/v12/docs/.
v12/
AGENTS.md agent instructions for this code root
.agent-docs/ proposals, decisions, reference, spike notes (design only)
.repos/ vendored dependency source (vendor-src, read-only)
packages/trpc/ core package (the brief: single `@trpc12/trpc` package)
packages/tanstack-query/ `@trpc12/tanstack-query`: framework-agnostic TanStack Query helpers
packages/tanstack-react-query/ `@trpc12/tanstack-react-query`: the React TanStack adapter
packages/experimental-tanstack-*-query/ `@trpc12/experimental-tanstack-{preact,vue,solid,svelte,angular,lit}-query`: the other adapters, one package each
packages/experimental-react/ `@trpc12/experimental-react`: stable `use()` promises, features as links
packages/experimental-react-atom/ `@trpc12/experimental-react-atom`: queries and mutations as Effect Atoms
packages/experimental-tanstack-db/ `@trpc12/experimental-tanstack-db`: TanStack DB collections synced by a subscription
packages/upgrade/ `@trpc12/upgrade`: the v11 → v12 codemod (`trpc12-upgrade` bin)
packages/experimental-nest/ `@trpc12/experimental-nest`: contracts implemented in NestJS controllers (`@Implement`, `TrpcModule`)
examples/ workspace-linked examples
packages/*/src/**/*.test.ts tests beside the code they show; shared fixtures in `src/**/fixtures/`
test/integration/ recipes with third-party libraries (AI SDK, Better Auth, Firebase callable, publisher backends)
spikes/ throwaway experiments; results in .agent-docs/notes/
tooling/portability/ TS2742/TS2883 check: a consumer package that emits declarations
tooling/tsconfig/ `@tooling/tsconfig`: the shared, strictest tsconfigs every package, suite and tool extends (examples stay standalone)
tooling/docs-lint/ lints the code blocks in www/v12/docs/ (oxlint skips Markdown)
tooling/vercel-ignore/ Vercel's ignored build step for the docs site: skips a deployment when nothing it renders changed
tooling/release/ checks the Changesets release plan (`../.changeset/config.json`): dependents bump with their dependencies
Work inside this folder (cd v12). It's part of the root's pnpm workspace, with ../v11/, ../www/ (the site, served at https://v12.trpc.io, with the v12 docs in www/v12/docs/ and the apps their code blocks compile in in www/samples/) and ../tooling/ui/ (@shared/ui, the site's shadcn components) (decision). New vNext packages go under v12/.
Vite+ (vite-plus, CLI vp) bundles Vitest, Oxlint, Oxfmt and tsdown. Config lives in vite.config.ts. Requires Node ≥ 24.11.
Node is pinned in .nvmrc (26.12.0, same version as v11/.nvmrc). From this directory, nvm use selects it. Then:
nvm use
pnpm install
pnpm test
pnpm examplepnpm install: installs deps;prepareinstalls the git hook dispatcher.pnpm typecheck:tsc(TypeScript 7.1 beta, the only version the repo builds with) in every package underv12/, through turbo: a package whose inputs and dependencies didn't change since a run here or in CI replays its output (--forcereruns everything,--summarizesays why each one ran) (decision).pnpm check:vp check(format check, lint and type-aware lint/type check), thenpnpm lint:docs.pnpm lint:docs: lints the code blocks inwww/v12/docs/with the rules that hold for examples (tooling/docs-lint/), since oxlint skips Markdown.pnpm fix:vp check --fix, formatting and autofixing.pnpm test:vp test run, Vitest, including*.test-d.tstype tests.pnpm test <file or folder>runs only those;--project packages-solidor--project packages-svelteruns those adapters' Vitest projects, which use browser conditions.pnpm coverage: the packages' tests (thepackages*Vitest projects:packages/*/srcandtest/) with v8 coverage overpackages/*/src; fails below 98% statements, branches, functions or lines. The docs site, tooling, examples and spikes have no coverage requirement;pnpm test --project '!packages*'runs their tests.pnpm test:bun:@trpc12/trpc's Bun tests (*.bun.test.ts); needsbunonPATH.pnpm example: runs every example'ssmokescript (examples/*).realtimeneeds Redis atREDIS_URLand Postgres atDATABASE_URL;runtime-matrixneedsbunanddeno.pnpm build:vp packper package (tooling/pack/): unbundled ESM and declarations indist/, published throughpublishConfig.exports, and the examples' builds, through turbo.pnpm docs:dev: the docs site at http://localhost:3000, reloading aswww/v12/docs/changes.pnpm docs:build: builds the packages the site compiles against, then prerenders the site towww/dist/client, and its Vercel output towww/.vercel/output; fails on a type error in a twoslash block or a broken link.pnpm bench budget: gzip size of the client bundles inbudgets(tooling/bench/bench.ts), against their targets; reports only, never fails.pnpm land: lands the current branch's commits onv12: rebase, reinstall when needed,vp checkon the changed files, push, retry (tooling/dev/).pnpm ci:wait [commit]: waits for the first finishednext.ymlrun onv12that includes the commit, and lists its failed jobs.
Run them all before pnpm land: pnpm fix, pnpm check, pnpm typecheck, pnpm coverage and pnpm test --project '!packages*' (together, every test), pnpm test:bun, pnpm example, pnpm build, pnpm docs:build when the site or the docs changed, and pnpm bench budget. When a change moves a client bundle's size, update the table in .agent-docs/notes/benchmarks.md.
Each package's README.md (packages/<name>/) says what it exports, and Packages and stability lists every package and @trpc12/trpc entry point with its docs. @trpc12/trpc imports no node:*: Node comes from NodeHttpServer.layer in @effect/platform-node (decision).
Pre-commit: .vite-hooks/pre-commit runs vp staged (see staged in vite.config.ts): vp check --fix on staged files under v12/, plus vp test related for staged .ts files. .vite-hooks/post-merge reruns pnpm --filter www sponsors:readme when a merge changed the root's README.md. pnpm install enables the hooks via vp config unless core.hooksPath is already set to something else, as it is in Cursor's Cloud Agents. Skip once with VP_GIT_HOOKS=0 git commit ….
CI: ../.github/workflows/next.yml runs for changes under v12/, www/, tooling/, v11/packages/ (which the site compiles against) and the root's workspace files: typecheck, check, coverage, the other tests, example (with Redis, Postgres, Bun and Deno) and bench budget (sizes in the log, no ceilings); the site's checks and build, as v12.trpc.io and as trpc.io; typecheck and test against the latest effect@4.x; and test:bun. Its turbo tasks share Vercel's remote cache. fix and v12/'s build aren't in CI, so run them locally. After landing, pnpm ci:wait reports the first finished run that includes your commit. The v11-* workflows check v11.
Releases: Changesets in the root's .changeset/, nothing published yet (decision). Each package has its own version, and a bump also releases every package that depends on the bumped one (dependencies or peerDependencies). Integrations keep "@trpc12/trpc": "workspace:*" peers during 0.x, published as exact versions, so users update @trpc12/* together. pnpm changeset records a change (pnpm changeset --minor @trpc12/trpc -m "…" skips the prompts); a breaking bump, a minor on 0.x, names each dependent with the same bump, which tooling/release/release.test.ts checks. Don't add changesets before the first release, which publishes each package's 0.1.0 as it stands.