docs: add v1 to v2 migration guide

[dinwwwh]

Adds a "Migrating from oRPC v1" guide to the docs site, covering every end-user API change between v1 and v2 with side-by-side v2/v1 code groups. Also restores ContractRouterClient as a deprecated alias so contract-first apps keep compiling during migration.

Docs

• New page docs/migrations/from-v1.md, registered in the sidebar above "Migrating from tRPC".
• Opens with the three highest-risk items: the v1-incompatible wire format, the removed automatic middleware deduplication, and the inverted Batch Plugin exclude -> filter semantics.
• Sections cover package renames, routing via openapi() metadata, procedure builder, middleware, error handling, AsyncIteratorObject, RPC handler, server/client plugins, RPCLink, contract-first, OpenAPI, integrations, and helpers, ending with a deprecated-alias cheat sheet. Most sections link to the relevant v2 docs page.
• Content was researched by diffing the v1 and v2 llms-full.txt dumps; every v2 snippet symbol was verified against the current packages/* source, and all internal links resolve to existing pages.

Contract

• @orpc/contract now exports RouterContractClient as ContractRouterClient (type-only, @deprecated), matching the pattern of the other v1 aliases in index.ts. The guide and its cheat sheet reflect that the old name still compiles.

Testing

• eslint passes on the changed files; tsc --noEmit passes for packages/contract; contract export tests pass.
• Docs site not built locally; markdown and sidebar entry verified manually.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
orpc	Ready	Preview	Aug 4, 2026 12:42pm

[pkg-pr-new]

More templates

• @orpc/bun-playground
• @orpc/cloudflare-playground
• @orpc/nest-playground
• @orpc/next-playground

@orpc/ai-sdk

npm i https://pkg.pr.new/@orpc/ai-sdk@1785

@orpc/arktype

npm i https://pkg.pr.new/@orpc/arktype@1785

@orpc/bun

npm i https://pkg.pr.new/@orpc/bun@1785

@orpc/client

npm i https://pkg.pr.new/@orpc/client@1785

@orpc/cloudflare

npm i https://pkg.pr.new/@orpc/cloudflare@1785

@orpc/contract

npm i https://pkg.pr.new/@orpc/contract@1785

@orpc/experimental-effect

npm i https://pkg.pr.new/@orpc/experimental-effect@1785

@orpc/evlog

npm i https://pkg.pr.new/@orpc/evlog@1785

@orpc/hibernation

npm i https://pkg.pr.new/@orpc/hibernation@1785

@orpc/json-schema

npm i https://pkg.pr.new/@orpc/json-schema@1785

@orpc/nest

npm i https://pkg.pr.new/@orpc/nest@1785

@orpc/next

npm i https://pkg.pr.new/@orpc/next@1785

@orpc/openapi

npm i https://pkg.pr.new/@orpc/openapi@1785

@orpc/opentelemetry

npm i https://pkg.pr.new/@orpc/opentelemetry@1785

@orpc/pinia-colada

npm i https://pkg.pr.new/@orpc/pinia-colada@1785

@orpc/pino

npm i https://pkg.pr.new/@orpc/pino@1785

@orpc/publisher

npm i https://pkg.pr.new/@orpc/publisher@1785

@orpc/ratelimit

npm i https://pkg.pr.new/@orpc/ratelimit@1785

@orpc/server

npm i https://pkg.pr.new/@orpc/server@1785

@orpc/shared

npm i https://pkg.pr.new/@orpc/shared@1785

@orpc/swr

npm i https://pkg.pr.new/@orpc/swr@1785

@orpc/tanstack-query

npm i https://pkg.pr.new/@orpc/tanstack-query@1785

@orpc/trpc

npm i https://pkg.pr.new/@orpc/trpc@1785

@orpc/valibot

npm i https://pkg.pr.new/@orpc/valibot@1785

@orpc/zod

npm i https://pkg.pr.new/@orpc/zod@1785

commit: b95999f

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[codspeed-hq]

Merging this PR will not alter performance

✅ 25 untouched benchmarks

---

_{Comparing dinwwwh:claude/orpc-v1-v2-migration-26082c (b95999f) with main (7973def)}

[pullfrog]

✅ No new issues found.

Reviewed changes

• docs/migrations/from-v1.md — a thorough 1153-line v1→v2 migration guide covering package renames, routing via openapi() metadata, the procedure builder, middleware, error handling, AsyncIteratorObject, the RPC handler, server/client plugins, RPCLink, contract-first, OpenAPI, integrations, and helpers, with side-by-side v2/v1 code groups and a deprecated-alias cheat sheet.
• Sidebar registration — adds the "Migrating from v1" entry above "Migrating from tRPC" in apps/content/.vitepress/config.ts.
• packages/contract alias — re-exports RouterContractClient as ContractRouterClient (type-only, @deprecated), matching the existing deprecated-alias pattern in index.ts.

I spot-checked the load-bearing symbols and links against the current packages/* source and the docs tree, and everything holds up: the ContractRouterClient alias resolves (router-client.ts exports RouterContractClient, no name collision with the export *), RPC_DEFAULT_ALLOW_METHODS lives in @orpc/server/standard, SimpleCsrfProtectionHandlerPlugin, RPCSerializer, COMMON_ERROR_STATUS_MAP/errorStatusMap, the Next.js server-function hooks and aliases, the Hibernation renames (HibernationAsyncIteratorClass + 'close' event), the extensions/callable|route|actionable subpaths, the renamed packages and their key exports (MemoryPublisher/RedisPublisher in @orpc/publisher, createPiniaColadaUtils in @orpc/pinia-colada), and all the internal doc links resolve to existing pages. The v1-side claims can't be verified against this repo since the v1 source isn't present, but the v2 side of every checked claim is accurate.

The code change is a clean, behavior-preserving restoration of a deprecated alias so contract-first apps keep compiling during migration. Nice work.

  ^{｜ View workflow run ｜ Using DeepSeek Flash (free via Pullfrog for OSS) ｜ 𝕏}

[pullfrog]

✅ No new issues found.

Reviewed changes

• Skipped [v1] code fences in the docs-JSDoc verifier — previous-major snippet imports in the new migration guide are no longer validated against v2 APIs, which correctly prevents false failures for v1-only symbols.
• Verified the regex /\[v1\]\s*$/ matches the exact ```ts [v1] opening format used across all 34 v1 snippets in docs/migrations/from-v1.md, and that the verifier now passes cleanly (0 errors, 0 warnings).

This closes the loop on the docs-side of the migration PR: real (v2) fences stay verified, while v1 reference snippets are excluded. Good, minimal fix.

  ^{｜ View workflow run ｜ Using DeepSeek Flash (free via Pullfrog for OSS) ｜ 𝕏}

[pullfrog]

✅ No new issues found.

Reviewed changes

• Docs prose rework — rewrote from-v1.md writing: wrapped inline warnings into proper ::: warning / ::: tip admonitions, and reframed the .callable and .actionable sections to recommend v2-first approaches (call / createRouterClient, createServerFunctionable) while demoting the compatibility extensions to a "if you prefer v1 style" tip.
• Snippet fixes — added missing imports to v2/v1 code groups (e.g. BatchLinkPlugin from @orpc/client/plugins) and corrected the createServerFunctionable example to match its actual factory signature.
• Cheat-sheet additions — added the useOptimisticServerAction → useOptimisticServerFunction and createORPCVueColadaUtils → createPiniaColadaUtils rows, plus an explicit createFormAction → createServerFormFunction note.

I verified every new symbol introduced in this increment against the current packages/* source: createServerFunctionable (packages/next/src/server-functionable.ts), call (packages/server/src/procedure-utils.ts — the call(getting, undefined, { context: {} }) usage matches the signature), and BatchLinkPlugin in @orpc/client/plugins. The admonition structure (each ::: warning / ::: tip opened and closed, code groups intact) is coherent in the final file. The v2-first guidance is accurate and an improvement over the previous framing.

  ^{｜ View workflow run ｜ Using DeepSeek Flash (free via Pullfrog for OSS) ｜ 𝕏}

[pullfrog]

✅ No new issues found.

Reviewed changes

• Batch Plugin section rework — rewrote the ### Batch Plugin section of from-v1.md: a lead claim that the v2 plugin supports every response type (including AsyncIteratorObject and File/Blob) so exclude can usually be removed outright, a simplified v2 code-group tab with the filter line dropped, an expanded v1 exclude example using ['planets/getImage', 'planets/subscribe'].includes(path.join('/')), and the skip-batching cases (e.g. Hibernation) moved into a ::: warning with a negated filter example.

I verified the load-bearing v2-side claims against packages/client/src/plugins/batch.ts: v2 BatchLinkPlugin takes filter (defaulting to () => true) and runs in streaming/buffered modes that support all response types; filter returning false means "not batched," which matches both the guide's wording and the plugin's own tests. The v2 code-group tab is valid (no filter is a valid configuration), and the negated filter example (path.join('/') !== 'chat/subscribe') correctly yields false only for the procedure that must stay unbatchable. The chore claim that exclude was mainly a workaround for unsupported response types is coherent with the surrounding v1-compatibility narrative.

  ^{｜ View workflow run ｜ Using DeepSeek Flash (free via Pullfrog for OSS) ｜ 𝕏}

[pullfrog]

✅ No new issues found.

Reviewed changes

• Corrected the Contract Impl (implementer) section — the previous claim that the v2 implementer "gained" .$context, .use, and .middleware was inaccurate; the guide now states implement(contract) supports these exactly as in v1, and clarifies that v2 additionally accepts a procedure config either as a second argument or through .$config, with a single v2 code example using implement(contract, { disableOutputValidation: true }).

I verified the v2-side claims against packages/server/src/implementer.ts: the second argument is a ProcedureConfig (implementer.ts:28), .$config (implementer.ts:41-42) and .$context (implementer.ts:38-39) are both supported, and disableOutputValidation is a valid config option. The linked /docs/advanced/validation-customization page exists. Accurate and coherent.

  ^{｜ View workflow run ｜ Using DeepSeek Flash (free via Pullfrog for OSS) ｜ 𝕏}