fix: mark @orpc packages as sideEffect-free for cross-pkg tree-shaking by voidborne-d · Pull Request #1540 · middleapi/orpc

voidborne-d · 2026-05-05T17:04:47Z

Closes #1490.

Background

Importing only oz.file() from @orpc/zod was pulling ~21 kB of @orpc/server runtime into client bundles via the chain:

@orpc/zod  →  @orpc/openapi  →  @orpc/server

Because @orpc/zod re-exports JSONSchemaFormat etc. from @orpc/openapi, and @orpc/openapi/dist/index.mjs has top-level import { ORPCError, createRouterClient } from '@orpc/server'. Those top-level cross-package imports are preserved by the consumer's bundler unless the package is annotated as side-effect free, because the bundler cannot otherwise prove the import has no observable effect.

Fix

Add "sideEffects": false to the all oRPC's packages

I audited the source for global mutations / prototype patches / side-effecting class registrations at import time and found none — the published modules are pure, so the annotation is safe.

Reproducer

Stand-alone Vite app that mirrors the issue body:

// client.ts
import { oc } from '@orpc/contract'
import { z } from 'zod/v3'
import { oz } from '@orpc/zod'

export const myRouter = oc.router({
  downloadFile: oc
    .route({ method: 'GET', path: '/download/{id}' })
    .input(z.object({ id: z.string() }))
    .output(oz.file()),
})

Bundled with vite build --minify esbuild --target es2022 and external: ['zod', 'zod/v3']:

Variant	Bundle	Gzipped	`@orpc/server` symbols leaked
Before this PR	37.9 kB	9.54 kB	`ORPCError`, `Procedure`, `createRouterClient`, `isProcedure`, `resolveContractProcedures`
After this PR	14.8 kB	4.76 kB	none from `@orpc/server` (the remaining `ORPCError` is from `@orpc/contract`, which is legitimately needed because `oc.router()` returns objects that use it)

Net savings: 23.1 kB minified (61% reduction) / 4.78 kB gzipped (50%).

Why this rather than the subpath split suggested in #1490

The reporter (correctly) suggested splitting ZodToJsonSchemaConverter into a separate @orpc/zod/json-schema subpath and removing it from the main entry. That would also fix the bug, but it is a breaking change for everyone currently importing the converter from @orpc/zod (incl. all in-repo playgrounds that use @orpc/zod/zod4's sister export, README example, etc.) and the subpath split is bundler-independent only insofar as users don't accidentally re-export the heavy entry transitively.

sideEffects: false is non-breaking, lands in 6 lines, and — as the numbers show — actually achieves the bundle reduction the reporter expected. If the cross-package tree-shaking turns out insufficient for some consumer's bundler, the subpath split is still available as a follow-up.

The reporter's original claim that sideEffects: false alone wouldn't fix this assumed it was set on @orpc/zod only; the chain only tree-shakes when every package along the cross-package import path is marked, which is what this PR does.

Local gates

pnpm --filter='./packages/*' run -r build ✓ all packages build, dist outputs unchanged in shape (sideEffects flag does not alter the rolled-up bundle, only the package.json of the published artifact)
pnpm test ✓ 4720 pass / 48 skipped / 5 todo across 280 test files (untouched by this change)
pnpm run type:check ✓ clean across all packages
pnpm lint ✓ clean (auto-formatter sorted the new key after keywords per jsonc/sort-keys)

I was happy to find this fits in 6 lines — happy to fold in the subpath split as a follow-up if any reviewer measures their bundler still needs it.

🤖 Generated with Claude Code

Summary by CodeRabbit

Chores
- Updated package metadata across many packages to mark them as side-effect free for improved bundling behavior.
New Features
- Exposed a package entry point for one package, updating its public exports.

…shaking Adds `"sideEffects": false` to @orpc/contract, @orpc/json-schema, @orpc/openapi, @orpc/server, @orpc/shared, and @orpc/zod. Without this flag, bundlers (Vite/Rollup/webpack/esbuild) conservatively preserve cross-package top-level imports even when the imported binding is unused, because they cannot prove the import target is side-effect free. Closes middleapi#1490, where importing only `oz.file()` from `@orpc/zod` pulled ~21 kB of `@orpc/server` runtime into client bundles via the chain `@orpc/zod` -> `@orpc/openapi` (re-exports `JSONSchemaFormat` etc.) -> top-level `import { ORPCError, createRouterClient } from '@orpc/server'`. All published modules in these packages are pure (no global registration, no prototype patches, no side-effecting class registrations at import time), so this annotation is safe. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

coderabbitai · 2026-05-05T17:05:02Z

📝 Walkthrough

Walkthrough

Added a top-level "sideEffects": false flag to many package.json manifests; additionally, packages/trpc/package.json gained a top-level exports mapping exposing "." -> "./src/index.ts".

Changes

Side-effects metadata update

Layer / File(s)	Summary
Manifest Metadata `packages/*/package.json` (`packages/contract/package.json`, `packages/json-schema/package.json`, `packages/openapi/package.json`, `packages/server/package.json`, `packages/shared/package.json`, `packages/zod/package.json`, `packages/ai-sdk/package.json`, `packages/arktype/package.json`, `packages/client/package.json`, `packages/durable-iterator/package.json`, `packages/hey-api/package.json`, `packages/interop/package.json`, `packages/nest/package.json`, `packages/openapi-client/package.json`, `packages/otel/package.json`, `packages/pino/package.json`, `packages/publisher-durable-object/package.json`, `packages/publisher/package.json`, `packages/ratelimit/package.json`, `packages/react-query/package.json`, `packages/react-swr/package.json`, `packages/react/package.json`, `packages/solid-query/package.json`, `packages/standard-server-aws-lambda/package.json`, `packages/standard-server-fastify/package.json`, `packages/standard-server-fetch/package.json`, `packages/standard-server-node/package.json`, `packages/standard-server-peer/package.json`, `packages/standard-server/package.json`, `packages/svelte-query/package.json`, `packages/tanstack-query/package.json`, `packages/valibot/package.json`, `packages/vue-colada/package.json`, `packages/vue-query/package.json`)	Added `"sideEffects": false` at the top level of each package.json (inserted typically after `keywords`). No other fields, scripts, dependencies, or exported/public TypeScript entities were changed.

trpc exports addition

Layer / File(s)	Summary
Manifest Metadata `packages/trpc/package.json`	Added `"sideEffects": false` and a top-level `exports` mapping exposing `"."` -> `"./src/index.ts"`. This adds an explicit public entrypoint in package manifest in addition to existing publishConfig. No code files or types were changed.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Possibly related PRs

middleapi/orpc#586: Modifies package manifests across packages/* (related at the manifest/packaging level).

Suggested labels

size:L

Poem

🐰 I hopped through manifests wide and far,

"sideEffects": false — a tidy little star.
No stray imports to make bundles bloat,
A tiny export added, just one small note.
Hooray! I thumped my foot and gave a joyful toot.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title accurately describes the main change: adding 'sideEffects': false to multiple `@orpc` packages to enable better tree-shaking. It is specific, concise, and directly related to the changeset.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

Create PR with unit tests

Tip

💬 Introducing Slack Agent: The best way for teams to turn conversations into code.

Slack Agent is built on CodeRabbit's deep understanding of your code, so your team can collaborate across the entire SDLC without losing context.

Generate code and open pull requests
Plan features and break down work
Investigate incidents and troubleshoot customer tickets together
Automate recurring tasks and respond to alerts with triggers
Summarize progress and report instantly

Built for teams:

Shared memory across your entire org—no repeating context
Per-thread sandboxes to safely plan and execute work
Governance built-in—scoped access, auditability, and budget controls

One agent for your entire SDLC. Right inside Slack.

👉 Get started

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

gemini-code-assist

Code Review

This pull request adds the "sideEffects": false property to the package.json files of several packages, including contract, json-schema, openapi, server, shared, and zod, to enable more efficient tree-shaking by bundlers. There are no review comments to address, and I have no further feedback to provide.

codecov · 2026-05-06T02:47:02Z

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

pkg-pr-new · 2026-05-06T02:47:21Z

More templates

@orpc/ai-sdk

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

@orpc/arktype

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

@orpc/client

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

@orpc/contract

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

@orpc/experimental-durable-iterator

npm i https://pkg.pr.new/@orpc/experimental-durable-iterator@1540

@orpc/hey-api

npm i https://pkg.pr.new/@orpc/hey-api@1540

@orpc/interop

npm i https://pkg.pr.new/@orpc/interop@1540

@orpc/json-schema

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

@orpc/nest

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

@orpc/openapi

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

@orpc/openapi-client

npm i https://pkg.pr.new/@orpc/openapi-client@1540

@orpc/otel

npm i https://pkg.pr.new/@orpc/otel@1540

@orpc/experimental-pino

npm i https://pkg.pr.new/@orpc/experimental-pino@1540

@orpc/experimental-publisher

npm i https://pkg.pr.new/@orpc/experimental-publisher@1540

@orpc/experimental-publisher-durable-object

npm i https://pkg.pr.new/@orpc/experimental-publisher-durable-object@1540

@orpc/experimental-ratelimit

npm i https://pkg.pr.new/@orpc/experimental-ratelimit@1540

@orpc/react

npm i https://pkg.pr.new/@orpc/react@1540

@orpc/react-query

npm i https://pkg.pr.new/@orpc/react-query@1540

@orpc/experimental-react-swr

npm i https://pkg.pr.new/@orpc/experimental-react-swr@1540

@orpc/server

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

@orpc/shared

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

@orpc/solid-query

npm i https://pkg.pr.new/@orpc/solid-query@1540

@orpc/standard-server

npm i https://pkg.pr.new/@orpc/standard-server@1540

@orpc/standard-server-aws-lambda

npm i https://pkg.pr.new/@orpc/standard-server-aws-lambda@1540

@orpc/standard-server-fastify

npm i https://pkg.pr.new/@orpc/standard-server-fastify@1540

@orpc/standard-server-fetch

npm i https://pkg.pr.new/@orpc/standard-server-fetch@1540

@orpc/standard-server-node

npm i https://pkg.pr.new/@orpc/standard-server-node@1540

@orpc/standard-server-peer

npm i https://pkg.pr.new/@orpc/standard-server-peer@1540

@orpc/svelte-query

npm i https://pkg.pr.new/@orpc/svelte-query@1540

@orpc/tanstack-query

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

@orpc/trpc

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

@orpc/valibot

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

@orpc/vue-colada

npm i https://pkg.pr.new/@orpc/vue-colada@1540

@orpc/vue-query

npm i https://pkg.pr.new/@orpc/vue-query@1540

@orpc/zod

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

commit: 9350fad

dinwwwh · 2026-05-06T02:48:50Z

Thanks for your PR, @voidborne-d, I didn't even know this existed 😅

I'm wondering why you didn't add this config to all packages. Do you think we should disable sideEffects by default across every package?

voidborne-d · 2026-05-06T06:35:42Z

Good question — kept it narrow on purpose to keep #1490 review cheap, but the answer is: yes, ideally every package should have it, and I just audited all 35 to confirm none have actual side effects. Quick rundown of the audit (grep'd every packages/*/src/index.ts):

All entry files are pure re-exports (export *, export { … } from '…', export type …)
Zero top-level statements that could be flagged as side-effecty: no globalThis.X = …, no window.…, no top-level function calls (register…(), etc.), no decorator-time global registrations
Spot-checked the suspect ones: nest/src/index.ts (NestJS decorators apply at class-declaration time inside user code, not at package import time), otel/src/index.ts (just export * from './instrumentation' — actual OpenTelemetry registration happens at user .register() call), pino / interop / ratelimit (all pure re-export plugins)

So: safe to flip the default across the full packages/* tree. Two options:

Extend this PR — I'll add "sideEffects": false to the remaining 29 packages in this branch. Same one-line change per package, same keywords-after lint placement. Single review surface for the whole monorepo policy.
Follow-up PR — keep fix: mark @orpc packages as sideEffect-free for cross-pkg tree-shaking #1540 scoped to the oz.file() bug-chain fix, ship a separate "make sideEffects: false the monorepo default" PR.

Either works for me. (1) is logically cleaner since the policy decision is global; (2) is friendlier if you'd rather merge the bug fix first and discuss the broader policy in a fresh thread. Let me know which you prefer and I'll push.

Two notes for the broader rollout:

playgrounds/* is out of PR scope (per pnpm --filter='./packages/*' run -r build); they don't ship to npm so sideEffects doesn't affect downstream bundlers
If you ever add a package whose entry runs work at import (e.g. polyfill auto-install), the per-package opt-out is "sideEffects": ["./dist/side-effecting-file.js"] — defaulting on false doesn't lock you out of that future

Copilot

Pull request overview

Marks a broad set of @orpc/* packages as side-effect free ("sideEffects": false) so consumer bundlers can safely tree-shake unused cross-package imports, addressing the transitive bundle-size leak described in #1490.

Changes:

Add "sideEffects": false to multiple @orpc/* package manifests to enable cross-package tree-shaking.
Applies the metadata change not only to the @orpc/zod → @orpc/openapi → @orpc/server chain, but also to many related runtime/integration packages to keep bundling behavior consistent across the monorepo.

Reviewed changes

Copilot reviewed 35 out of 35 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
packages/ai-sdk/package.json	Mark package as side-effect free for bundlers.
packages/arktype/package.json	Mark package as side-effect free for bundlers.
packages/client/package.json	Mark package as side-effect free for bundlers.
packages/contract/package.json	Mark package as side-effect free for bundlers.
packages/durable-iterator/package.json	Mark package as side-effect free for bundlers.
packages/hey-api/package.json	Mark package as side-effect free for bundlers.
packages/interop/package.json	Mark package as side-effect free for bundlers.
packages/json-schema/package.json	Mark package as side-effect free for bundlers.
packages/nest/package.json	Mark package as side-effect free for bundlers.
packages/openapi/package.json	Mark package as side-effect free for bundlers.
packages/openapi-client/package.json	Mark package as side-effect free for bundlers.
packages/otel/package.json	Mark package as side-effect free for bundlers.
packages/pino/package.json	Mark package as side-effect free for bundlers.
packages/publisher/package.json	Mark package as side-effect free for bundlers.
packages/publisher-durable-object/package.json	Mark package as side-effect free for bundlers.
packages/ratelimit/package.json	Mark package as side-effect free for bundlers.
packages/react/package.json	Mark package as side-effect free for bundlers.
packages/react-query/package.json	Mark package as side-effect free for bundlers.
packages/react-swr/package.json	Mark package as side-effect free for bundlers.
packages/server/package.json	Mark package as side-effect free for bundlers.
packages/shared/package.json	Mark package as side-effect free for bundlers.
packages/solid-query/package.json	Mark package as side-effect free for bundlers.
packages/standard-server/package.json	Mark package as side-effect free for bundlers.
packages/standard-server-aws-lambda/package.json	Mark package as side-effect free for bundlers.
packages/standard-server-fastify/package.json	Mark package as side-effect free for bundlers.
packages/standard-server-fetch/package.json	Mark package as side-effect free for bundlers.
packages/standard-server-node/package.json	Mark package as side-effect free for bundlers.
packages/standard-server-peer/package.json	Mark package as side-effect free for bundlers.
packages/svelte-query/package.json	Mark package as side-effect free for bundlers.
packages/tanstack-query/package.json	Mark package as side-effect free for bundlers.
packages/trpc/package.json	Mark package as side-effect free for bundlers.
packages/valibot/package.json	Mark package as side-effect free for bundlers.
packages/vue-colada/package.json	Mark package as side-effect free for bundlers.
packages/vue-query/package.json	Mark package as side-effect free for bundlers.
packages/zod/package.json	Mark package as side-effect free for bundlers (primary repro path).

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

dosubot Bot added the size:XS This PR changes 0-9 lines, ignoring generated files. label May 5, 2026

dosubot Bot added the bug Something isn't working label May 5, 2026

gemini-code-assist Bot reviewed May 5, 2026

View reviewed changes

dinwwwh changed the title ~~fix: mark @orpc packages as sideEffect-free for cross-pkg tree-shaking (closes #1490)~~ fix: mark @orpc packages as sideEffect-free for cross-pkg tree-shaking May 6, 2026

fix: mark all packages as sideEffect-free for improved tree-shaking

0bdbf12

dinwwwh approved these changes May 6, 2026

View reviewed changes

dosubot Bot added the lgtm This PR has been approved by a maintainer label May 6, 2026

dinwwwh requested a review from Copilot May 6, 2026 07:19

Copilot started reviewing on behalf of dinwwwh May 6, 2026 07:20 View session

Copilot AI reviewed May 6, 2026

View reviewed changes

Comment thread packages/zod/package.json

dinwwwh merged commit 683f2ee into middleapi:main May 6, 2026
9 checks passed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

fix: mark @orpc packages as sideEffect-free for cross-pkg tree-shaking#1540

fix: mark @orpc packages as sideEffect-free for cross-pkg tree-shaking#1540
dinwwwh merged 2 commits intomiddleapi:mainfrom
voidborne-d:fix/sideEffects-1490

voidborne-d commented May 5, 2026 •

edited by dinwwwh

Loading

Uh oh!

coderabbitai Bot commented May 5, 2026 •

edited

Loading

Walkthrough

Changes

Estimated code review effort

Possibly related PRs

Suggested labels

Poem

Uh oh!

gemini-code-assist Bot left a comment

Uh oh!

codecov Bot commented May 6, 2026

Uh oh!

pkg-pr-new Bot commented May 6, 2026 •

edited

Loading

Uh oh!

dinwwwh commented May 6, 2026

Uh oh!

voidborne-d commented May 6, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Uh oh!

Conversation

voidborne-d commented May 5, 2026 • edited by dinwwwh Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Background

Fix

Reproducer

Why this rather than the subpath split suggested in #1490

Local gates

Summary by CodeRabbit

Uh oh!

coderabbitai Bot commented May 5, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Walkthrough

Changes

Estimated code review effort

Possibly related PRs

Suggested labels

Poem

Uh oh!

gemini-code-assist Bot left a comment

Choose a reason for hiding this comment

Code Review

Uh oh!

codecov Bot commented May 6, 2026

Codecov Report

Uh oh!

pkg-pr-new Bot commented May 6, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

dinwwwh commented May 6, 2026

Uh oh!

voidborne-d commented May 6, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

voidborne-d commented May 5, 2026 •

edited by dinwwwh

Loading

coderabbitai Bot commented May 5, 2026 •

edited

Loading

pkg-pr-new Bot commented May 6, 2026 •

edited

Loading