docs(openapi): note that prefixes now apply to every procedure

[dinwwwh]

In v1, .prefix was a no-op for procedures that did not define a path, so those endpoints kept the bare router-derived path. In v2 the prefix is merged onto the derived path as well, which silently moves every such endpoint. Nothing in the migration guide said so, and the change is invisible until a client 404s.

Docs

The "Routing Moved to OpenAPI Metadata" section now carries a warning with a side-by-side example: the same pathless planet.create is POST /planet/create under a v1 .prefix('/api/v2') and POST /api/v2/planet/create in v2. The change is also listed in the "Read these first" callout at the top of the page, next to the other upgrades that break at runtime rather than at compile time.

Verification

Confirmed against both versions rather than from memory: v1's prefixRoute returns the route untouched when path is unset, while v2 computes meta.path ?? pathToHttpPath(path) first and merges the prefix onto the result. A scratch test against OpenAPIGenerator produced POST /api/v2/planet/create for the documented example.

[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@1971

@orpc/arktype

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

@orpc/bun

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

@orpc/client

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

@orpc/cloudflare

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

@orpc/contract

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

@orpc/experimental-effect

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

@orpc/evlog

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

@orpc/hibernation

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

@orpc/json-schema

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

@orpc/experimental-msw

npm i https://pkg.pr.new/@orpc/experimental-msw@1971

@orpc/nest

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

@orpc/next

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

@orpc/node

npm i https://pkg.pr.new/@orpc/node@1971

@orpc/openapi

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

@orpc/opentelemetry

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

@orpc/pinia-colada

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

@orpc/pino

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

@orpc/publisher

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

@orpc/ratelimit

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

@orpc/server

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

@orpc/shared

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

@orpc/swr

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

@orpc/tanstack-query

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

@orpc/trpc

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

@orpc/valibot

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

@orpc/zod

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

commit: 9024b60

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[cloudflare-workers-and-pages]

Deploying with    Cloudflare Workers

The latest updates on your project. Learn more about integrating Git with Workers.

Status	Name	Latest Commit	Preview URL	Updated (UTC)
✅ Deployment successful! View logs	orpc	9024b60	Commit Preview URL Branch Preview URL	Sep 01 2026, 02:31 AM

[pullfrog]

✅ No new issues found.

Reviewed changes

• Add a "Read these first" checklist item noting that .prefix/prefix now applies to every procedure, not only those that define a path.
• Add a :::warning[Prefixes now apply to every procedure] callout with a v1/v2 <CodeGroup> example showing a pathless planet.create under a /api/v2 prefix.

I verified the two behavioral claims against the source rather than trusting the description: the v1 matcher used route.path ?? toHttpPath(path) and prefixRoute returns the route untouched when path is unset (confirmed in v1 packages/contract/src/route.ts, pre-v2 commit), while v2 computes meta.path ?? pathToHttpPath(path) first and then merges the prefix (packages/openapi/src/openapi-generator.ts:131-132). The example paths (POST /planet/create vs POST /api/v2/planet/create), the default POST method, and both link targets (#basic-routing in apps/content/docs/openapi/routing.mdx, #routing-moved-to-openapi-metadata in from-v1.mdx) all check out.

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

[codspeed-hq]

Merging this PR will not alter performance

✅ 30 untouched benchmarks

---

_{Comparing claude/orpc-v1-routing-migration-docs-1f3818 (9024b60) with main (b941fbe)¹}

Footnotes

1. No successful run was found on main (4f728f0) during the generation of this report, so b941fbe was used instead as the comparison base. There might be some changes unrelated to this pull request in this report. ↩