Migrating to oRPC

Playbook for two migrations: tRPC to oRPC, and oRPC v1 to v2. Work in small mechanical steps and run the project's typecheck and test suite after each one, so any failure points at the last step. Pretrained knowledge of oRPC describes v1 and is often wrong for v2: derive every import path, builder method, and option name from the docs pages listed at the end, never from memory. For core v2 concepts while rewriting (the

os

builder, routers, middleware, clients), load the

orpc

skill. v2 currently ships under the

beta

npm dist-tag and plain installs get v1; drop the

@beta

suffix once

npm view @orpc/server dist-tags

shows

latest

at 2.x.

tRPC to oRPC

Two paths. Pick incremental when the app must keep shipping or the tRPC router is large; pick the full rewrite when the router is small enough to convert in one pass.

Incremental: wrap the existing tRPC router

Install

@orpc/trpc@beta

and convert. The result is a regular oRPC router: expose it through an RPC or OpenAPI handler, or call it with a server-side client, while the tRPC code keeps working untouched.

import { toORPCRouter } from '@orpc/trpc'

const orpcRouter = toORPCRouter(trpcRouter)

tRPC error formatting is not supported: tRPC errors arrive wrapped in
```
ORPCError
```
with the
```
TRPCError
```
as
```
cause
```
(and a
```
ZodError
```
below that for validation failures). Reshape them in a handler interceptor if consumers need structured errors.
```
toTRPCMeta
```
bridges oRPC
```
openapi()
```
metadata into tRPC
```
.meta()
```
so converted procedures get OpenAPI routing. Chained tRPC
```
.meta()
```
calls merge shallowly, so keep all oRPC metadata inside a single
```
toTRPCMeta
```
call.

Then rewrite leaf routers to native oRPC one at a time, mounting each next to the converted router in one plain object.

Full rewrite: concept map

Concept	tRPC	oRPC
Router	`t.router({...})`	plain object
Procedure builder	`t.procedure`	`os`
Context	`initTRPC.context<T>()`	`os.$context<T>()`
Create middleware	`t.middleware(fn)`	`os.middleware(fn)`
Use middleware	`.use(mw)`	`.use(mw)`
Validation	`.input(schema)` / `.output(schema)`	same names
Implementation	`.query()` / `.mutation()` / `.subscription()`	`.handler()` for all three
Errors	`new TRPCError({ code, ... })`	`new ORPCError(code, { ... })`
Serializer	`superjson` transformer	built in, remove `superjson`

Steps, in order, verifying after each:

Packages. Remove

@trpc/server

@trpc/client

@trpc/tanstack-react-query

; install

@orpc/server@beta

@orpc/client@beta

@orpc/tanstack-query@beta

Base file. Port the context factory unchanged, then rebuild the shared procedures. In handlers and middleware,

ctx

becomes

context

import { ORPCError, os } from '@orpc/server'

const o = os.$context<Awaited<ReturnType<typeof createContext>>>()

export const publicProcedure = o.use(timingMiddleware)
export const protectedProcedure = publicProcedure.use(({ context, next }) => {
  if (!context.session?.user)
    throw new ORPCError('UNAUTHORIZED')
  return next({ context: { session: context.session } })
})

Procedures. Replace

.query

.mutation

.subscription

with

.handler

;

.input

and

.output

carry over as is.

App router. Delete every
```
createTRPCRouter()
```
wrapper; nested plain objects are the router.

Server. Replace the tRPC adapter with an oRPC handler for the runtime (fetch shown; other adapters exist for Node, Fastify, AWS Lambda, WebSocket):

import { RPCHandler } from '@orpc/server/fetch'

const handler = new RPCHandler(appRouter)

const { response } = await handler.handle(request, {
  prefix: '/api/orpc',
  context: await createContext({ headers: request.headers }),
})

Client.

RPCLink

plus

createORPCClient

, typed by

RouterClient

. Call sites drop the

.query()

.mutate()

suffixes:

import type { RouterClient } from '@orpc/server'
import { createORPCClient } from '@orpc/client'
import { RPCLink } from '@orpc/client/fetch'

const link = new RPCLink({ origin: 'http://localhost:3000', url: '/api/orpc' })
export const client: RouterClient<typeof appRouter> = createORPCClient(link)

const { planets } = await client.planet.list({ cursor: 0 })

TanStack Query.
```
createTanstackQueryUtils(client)
```
replaces the provider and
```
useTRPC
```
hook entirely; use the utils object directly. Input moves inside an
```
input
```
key:
```
orpc.planet.list.queryOptions({ input: { cursor: 0 } })
```
,
```
orpc.planet.create.mutationOptions()
```
. For infinite queries,
```
infiniteOptions
```
takes
```
input
```
as a function of the page param.

oRPC v1 to v2

Most v1 names still compile through deprecated aliases (strike-through hints, not errors), so migrate in passes. Order of operations:

Update packages. Install every

@orpc/*

package from the

beta

dist-tag (

npm install @orpc/server@beta @orpc/client@beta

, and so on). Swap renamed ones first:

@orpc/react-query

@orpc/vue-query

@orpc/solid-query

@orpc/svelte-query

all became

@orpc/tanstack-query

;

@orpc/openapi-client

merged into

@orpc/openapi

;

@orpc/react

became

@orpc/next

;

@orpc/otel

became

@orpc/opentelemetry

; the

experimental-

packages were promoted (

@orpc/publisher

@orpc/ratelimit

@orpc/pino

@orpc/swr

);

@orpc/vue-colada

became

@orpc/pinia-colada

. Typecheck: the remaining errors are the hard breaks.

Fix the hard breaks (no aliases):
- Routing:
```
.route
```
  ,
```
.prefix
```
  ,
```
.tag
```
  ,
```
.$route
```
  are gone from the builder. Use
```
.meta(openapi({ method, path, prefix, tags }))
```
  from
```
@orpc/openapi
```
  , or restore
```
.route
```
  with
```
import '@orpc/openapi/extensions/route'
```
  .
- ```
.callable
```
  and
```
.actionable
```
  : use
```
call
```
  /
```
createRouterClient
```
  from
```
@orpc/server
```
  and
```
createServerFunctionable
```
  from
```
@orpc/next
```
  , or the corresponding extension imports.
- ```
RPCLink
```
  : the single
```
url
```
  split into
```
origin
```
  plus a path-only
```
url
```
  .
- Errors:
```
status
```
  was removed from
```
ORPCError
```
  and
```
.errors
```
  definitions; map codes to HTTP status with
```
errorStatusMap
```
  on the handler.
- ```
safe()
```
  : the third tuple element is now the typed error itself (or
```
null
```
  ) and a fourth
```
isSuccess
```
  element was added.
- Option renames, scoped: handler
```
rootInterceptors
```
  to
```
routingInterceptors
```
  (handler
```
clientInterceptors
```
  still exists, unchanged); link
```
clientInterceptors
```
  to
```
transportInterceptors
```
  . Flat
```
eventIterator*
```
  options moved under the adapter's request/response mapping:
```
toFetchResponse.eventStream
```
  on the fetch handler,
```
sendStandardResponse.eventStream
```
  on Node,
```
toFetchRequest.eventStream
```
  on the link.
- ```
adapterInterceptors
```
  was removed from handlers and links, because regular interceptors can now customize body parsing behavior.
Audit silent behavior changes (compile fine, behave differently):
- Wire format changed: a v1 link cannot talk to a v2 server, in either direction. Deploy the upgraded server and clients together.
- Automatic middleware deduplication removed: middleware applied at both router and procedure level now runs twice, with no warning. Guard shared middleware with the context-flag pattern from the dedupe-middleware recipe.
- Batch Plugin
  exclude
  became
  filter
  with the opposite meaning. Usually delete
```
exclude
```
  ; if skipping is still needed, negate the predicate.
- RPCHandler
  rejects GET by default (
```
allowMethods
```
  defaults to POST/PUT/PATCH/DELETE). Simplest fix: stop sending GET from the link; only allow GET deliberately, with CSRF protection.
- Handler
  filter
  takes positional arguments now; the v1 destructured form still type-checks but reads wrong values.
- .input
  /
  .output
  now stack: a repeated call adds a schema instead of replacing the previous one.
Sweep deprecated aliases last:
```
eventIterator
```
to
```
asyncIteratorObject
```
, handler plugins gained a
```
HandlerPlugin
```
suffix and link plugins a
```
LinkPlugin
```
suffix,
```
ContractRouter*
```
types became
```
RouterContract*
```
. The from-v1 guide ends with the full alias cheat sheet.

Verification: typecheck and unit tests after steps 1, 2, and 4; step 3 needs integration or e2e tests, since those changes never surface at compile time. Before finishing, grep for old package names and remaining deprecation strike-throughs.

Docs retrieval

Fetch pages instead of recalling them, and if this skill and a fetched page disagree, trust the page. The v2 docs live at https://orpc.dev and the v1 docs at https://v1.orpc.dev; slugs look alike across both hosts, so check which host a page came from before copying anything from it. The index of every v2 docs page is at https://orpc.dev/llms.txt, https://orpc.dev/llms-full.txt bundles the entire docs in one large file, and appending

.md

to any page URL returns its exact source markdown.

Authoritative pages to consult during the migration (this skill deliberately omits their full mapping tables):

https://orpc.dev/docs/migrations/from-trpc : side-by-side tRPC/oRPC code for every step, including server setup per framework
https://orpc.dev/docs/migrations/from-v1 : every v2 breaking change with v1/v2 comparisons, package rename table, and the deprecated alias cheat sheet
https://orpc.dev/docs/integrations/trpc :
```
toORPCRouter
```
and
```
toTRPCMeta
```
reference for the incremental path

orpc-migrate

NPX Install

SKILL.md Content

Migrating to oRPC

tRPC to oRPC

Incremental: wrap the existing tRPC router

Full rewrite: concept map

oRPC v1 to v2

Docs retrieval