CodeVetter · Repo Unpack · Contributor handoff
trpc/trpc
Read the procedure and HTTP core before editing. Tests run against source via Vitest aliases, but typecheck and consumers need pnpm build because packages ship dist built by tsdown. Keep adapters thin, put behavior changes in unstable-core-do-not-import, and add a regression under packages/tests. Do not treat examples or www as the library. OpenAPI fixtures are generated and checked in CI. Public types are the product, so signature changes are breaking even when runtime behavior is not.
- Files to read first: CONTRIBUTING.md (package map and the resolveResponse walkthrough), initTRPC.ts, procedureBuilder.ts, router.ts, http/resolveResponse.ts, http/contentType.ts, createTRPCClient.ts, and the adapter you are changing. The CONTRIBUTING page names those as the mental model for server, client, react-query, and next.
- Safe command set is pnpm install, pnpm build, pnpm dev, pnpm test <filter>, pnpm lint, and pnpm typecheck-packages. pnpm test 3085-style filters are the documented way to run one regression. Do not run publish-canary, publish-prerelease, or the release workflow unless asked.
- Each of @trpc/server, @trpc/client, @trpc/react-query, @trpc/next, and @trpc/openapi sets eslint no-restricted-imports on its own package name. Inside a package, import sibling files relatively. Cross-package imports must use the public export, and client code reaches internals only through @trpc/server/unstable-core-do-not-import.
- Vitest aliases point at src, so a unit test does not require dist. turbo typecheck and lint depend on ^build, and the e2e job runs pnpm build first. After a type-only change, run pnpm typecheck-packages; after a runtime change, run pnpm test with a filename filter before the full suite.
- Put new behavioral regressions in packages/tests/server, matching existing names (regression issue tests, batching, streaming, websockets). Colocate type-level tests next to the module when that is the local pattern (procedureBuilder.test.ts, router.test.ts). React hook tests belong in packages/react-query/test.
- Do not hand-edit packages/openapi/test/routers. CI fails the unit job if that tree is dirty and prints the exact command pnpm -C packages/openapi codegen. @trpc/openapi is version 11.19.0-alpha, so treat its API as unstable relative to the 11.19.0 libraries.
- Router keys then, call, and apply throw at createRouterFactory. Procedures are functions; isProcedure uses typeof === 'function', which is also why lazy loaders are stored separately. Do not add callable properties that would be mis-detected as procedures.
- Never invoke a procedure as a normal function from application code. createProcedureCaller throws a fixed message unless opts contains getRawInput. Server-side calls go through createCallerFactory. Client calls go through the proxy.
- isDev and isServer are environment gates. isServerDefault is true when window is undefined, Deno is present, or NODE_ENV is test, or JEST_WORKER_ID or VITEST_WORKER_ID is set. Forcing the server build into a browser bundle requires allowOutsideOfServer and will throw otherwise.
- Examples and www are not safe refactor targets when changing the library. Examples pin workspace packages and demonstrate patterns (some insecure on purpose, such as the mock GitHub provider and empty Prisma context). www/vercel.json redirects are easy to break by renaming a docs slug.
- Peer dependencies are exact: @trpc/client requires @trpc/server 11.19.0. Shipping a server change without bumping the peer, or testing with mismatched workspace versions, will not match what npm users install. prepack and version run tsx scripts/version.ts.
- The widest blast radius is the procedure and router generics (ProcedureBuilder, DecorateCreateRouterOptions, DecoratedProcedureRecord). They are copied into every client package. A type-only break will fail pnpm typecheck-packages and the example typecheck step even when Vitest is green. (inferred)