| name | orpc-migrate |
| description | Migrate existing codebases to current oRPC, covering tRPC to oRPC (incremental wrapping via the @orpc/trpc integration or a full rewrite with the concept mapping) and oRPC v1 to v2 (package renames, breaking changes, and a safe order of operations). Use when asked to migrate from tRPC to oRPC, convert or wrap a tRPC router, upgrade oRPC v1 to v2, fix oRPC v2 breaking changes, or swap `@trpc/*` packages for `@orpc/*` equivalents. Biases toward retrieval from the oRPC docs over pre-trained knowledge. Not for greenfield oRPC work or new features in an already-migrated codebase: use the orpc skill for those. |
| license | MIT |
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):
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 (handler still exists, unchanged); link to ; on both, is renamed after the adapter, e.g. on the fetch adapter. Flat options moved under the adapter's request/response mapping: on the fetch handler, on Node, on the link.
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://v2.orpc.dev; while v2 is in beta, https://orpc.dev still serves the v1 docs (same-looking slugs, wrong or missing content), so never fetch from it. The index of every docs page is at https://v2.orpc.dev/llms.txt (its links print the orpc.dev domain; swap in v2.orpc.dev before fetching), https://v2.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):
