Quick answer: Tree shaking drops code that is never imported and has no side effects, but a generated API client often bundles every operation, model, and serializer in a structure the bundler cannot split. Your bundle shrinks only when the generator emits static ES modules, you use named imports, and nothing reaches the unused code at runtime.
Why a generated client can weigh more than you expect
A generator emits a method for every operation, a type for every schema, plus serialization, encoding, error handling, and an HTTP transport. The output is sized for full coverage, not your slice of the API, a point the OpenAPI codegen guide returns to: generators optimize for completeness, and trimming is a separate step.
When a billing service calls three endpoints on a 120-endpoint spec, the other 117 methods still sit in the source. That alone does not decide their fate. A bundler traces imports from your entry point and ships anything reachable from that graph, even if no line you wrote invokes it.
What tree shaking actually needs
Tree shaking is build-time dead-code removal based on the static structure of ES modules. Since import and export are top-level and fixed at runtime, a bundler sees which exports are used before anything runs. CommonJS require can sit inside conditions and resists that analysis.
Two conditions decide the result. The package must ship ES module entry points through the module or exports field, and it must declare side effects. A module with top-level code that touches global state, registers polyfills, or imports CSS cannot be dropped even if none of its exports is used. sideEffects: false says unused files are safe to remove; listing the effectful files is more precise.
| Factor | When it helps | When it blocks removal |
|---|---|---|
| Module format | Static ES module imports and exports | CommonJS or dynamic require |
| Import style | Named import of one resource | Namespace import with dynamic access |
| package.json | sideEffects false or an exact list | No sideEffects field on effectful files |
| File layout | One file per resource or model | A barrel that re-exports everything |
| Runtime shape | Plain exported functions | Methods on a shared client object |
How generated code structure changes the result
Generators that emit one file per resource or tag give the bundler natural cut points: if billing.ts is the only file you import and it pulls only its own models, other resource files are unreachable and fall out. A giant client or a barrel that re-exports every operation can defeat this, though modern bundlers trace re-exports unless a top-level side effect keeps the module alive.
The runtime shape matters too. When every method hangs off one client instance or a registry of handlers, the whole registry is reachable through a single object and individual methods cannot be pruned. Plain exported functions imported by name are easier to remove because an unused name is provably dead. Nested $ref chains behave the same way: one serializer can drag in a chain of related types.
How to measure and shrink the real output
Do not estimate from generated line count; measure the shipped bundle. esbuild can write a metafile, and tools such as rollup-plugin-visualizer or webpack-bundle-analyzer show which modules survived and why. A resource you never call still appears because something imports it, usually a barrel, registry, or shared model.
Then make the changes that reduce bytes:
- Use named imports for the specific resource and model instead of the whole namespace.
- Confirm the package ships ESM and sets sideEffects before you rely on shaking.
- Generate only what you need when the generator supports path or tag filters.
- Use dynamic import to split rarely used endpoints out of the initial bundle rather than delete them.
- Run the production build with minification so development-only branches drop.
After you trim a client, confirm the calls you kept still work against the real API. In Powerduck you can send those requests and run a scenario that asserts each response, so a bundle cleanup does not silently break the endpoints that remain.
Frequently asked questions
Does tree shaking work on CommonJS clients? Not reliably. CommonJS require can run conditionally, so an unused export is hard to prove, and transpiling ESM down to CommonJS loses the static structure.
Will sideEffects false remove my CSS or polyfills? It can, if they come from files the bundler treats as unused. List such files in the sideEffects array rather than marking the whole package false.
Why does an unused model still ship? It is reachable from something you use, often a serializer, parent schema, or barrel. The metafile shows the chain; break it and the model drops.
Is smaller generated source the same as a smaller bundle? No. Bundle size is the output after reachability and minification. Measure the final gzip or brotli bytes, not the input files.
The bottom line
Tree shaking is not a switch that rescues any client; it follows from static, split, side-effect-free modules. A generator emitting ESM per resource, with named imports and an accurate sideEffects declaration, lets the bundler delete the operations you never touch. If everything funnels through one object or barrel, fix the generator and import style, not the bundler. Measure the metafile, drop what is unreachable, and verify the surviving calls with real requests.
Top comments (0)