Bundling and Tree-Shaking
What the @tolki packages promise your bundler, and the few cases where you add a /* @__PURE__ */ comment yourself.
The results below were measured on Rollup 4.68.5, Rolldown 1.3.2 (Vite 8), esbuild 0.28.2, webpack 5.112.2 and Rspack 2.3.3, against the published form of each package. The repository's pnpm treeshake:check repeats the measurements and fails when a bundler changes an outcome, so this page is updated with it.
What the packages guarantee
- Unused imports leave your bundle. Every package sets
"sideEffects": false, and named imports shake in all five bundlers. - Unused calls leave too. A function with no side effects carries
/* @__NO_SIDE_EFFECTS__ */. Rollup, Rolldown, webpack and Rspack then drop a call whose result nothing uses, including a call at the top level of a module. - Importing a package runs no setup code. The packages' own module-level calls are marked
/* @__PURE__ */, so a bundler drops them when nothing uses them, esbuild included. - Functions with effects are always kept. A function that changes what you pass, writes module state, runs a callback for its effects or exists to throw has no annotation, so a call to it stays. Each package page names its own, such as
popandshiftin Arrays & Objects anduseLocalein Numbers.
Namespace imports
A namespace import shakes exactly like named imports when you read its members by name:
import * as Str from "@tolki/str";
export const title = Str.after(input, ":");Only Str.after and what it needs end up in the bundle. The same holds for @tolki/arr, @tolki/num and the other packages.
Two uses keep the whole package, because the bundler can no longer tell which members you need:
- passing the namespace object around, as in
register(Str); - reading a computed member, as in
Str[name].
Per bundler
| Bundler | An unused call to a helper | What you do |
|---|---|---|
| Rollup | Dropped, and nothing is left behind. | Nothing. |
| Rolldown (Vite 8) | Dropped. For the helpers in Dependency residue, the code behind them can stay. In the generated route shape, the curried helpers are kept (see below). | Nothing for helpers. /* @__PURE__ */ for the curried routes, and on the dependency-residue calls. |
| esbuild | Kept. esbuild never follows /* @__NO_SIDE_EFFECTS__ */ from one file to another. | Write /* @__PURE__ */ fn(...) on every call you want removed. |
| webpack | Dropped, and nothing is left behind. In the generated route shape, the curried helpers are kept (see below). | Nothing for helpers. /* @__PURE__ */ for the curried routes. |
| Rspack | Dropped. A few helpers leave code behind (see Dependency residue), and so does an enum file that derives a list. | Nothing, or /* @__PURE__ */ on those calls. |
"Dropped" means the bundle came out byte-identical to one without the call.
When to write /* @__PURE__ */
Put the comment right before the call, on the call itself and on each call nested in its arguments:
export const id = /* @__PURE__ */ uuid();You need it in these cases:
- esbuild. It drops the call only with the comment. With it, an unused call drops in all five bundlers.
- Generated routes with a curried helper. See below.
- A class.
new Collection(...),new Translator(...)andnew Stringable(...)can stay in the bundle without it, because a bundler cannot mark a constructor. A call-site/* @__PURE__ */ new Collection(...)drops them in every bundler. - A helper that leaves dependency code behind in Rolldown or Rspack. See below.
Dependency residue
In Rolldown and Rspack, an unused top-level call to one of these helpers drops the call but can keep the code of the package behind it. Writing /* @__PURE__ */ before the call drops everything.
The cause is how the packages are published: Rolldown honours /* @__NO_SIDE_EFFECTS__ */ across files only on a function exported inline (export function f), and the published files use export lists. So the call goes, and the dependency of the helper's module stays.
| Helpers | What can stay behind |
|---|---|
uuid, uuid7 | the uuid package |
ulid | the ulid package |
plural, singular, counted, isPlural, isSingular, pluralStudly, pluralPascal, matchCase, uncountable | pluralize |
markdown, inlineMarkdown, markDownRenderer | markdown-it |
slug, ascii | transliteration |
str, of | the whole Stringable class and its dependencies |
collect | the Collection class and its helpers |
Rspack alone has two more:
createLang(@tolki/langand@tolki/lang/vue) leaves dead@tolki/utilscode under Rspack's default minifier settings. SWCcompress.passes: 3inoptimization.minimizerremoves it.spellandspellOrdinal(@tolki/num) keep the chunk-loading runtime for the dynamicimport()of their locale files.
Rollup and webpack drop all of these cleanly.
Large dependencies
Some imports are big on their own, and no bundler setting changes that, because the code is used when you call them:
slugandasciicarrytransliteration, which holds the character tables for every script. Import them only where you need them.markdown,inlineMarkdownandmarkDownRenderercarrymarkdown-it.strandofreturn aStringable, a class with every string helper as a method, so a bundle that uses either keeps the whole class and every dependency it uses. For small bundles, import the string functions one by one instead.collectandnew Collectionkeep the wholeCollectionclass.
Generated enums and routes
A file generated by the TypeScript publisher is a module-level call such as export const Status = defineEnum({...}). Whether an unused one drops depends on the shape and on the bundler:
| Generated shape | Rollup | Rolldown | esbuild | webpack | Rspack |
|---|---|---|---|---|---|
An enum alone, or a plain defineRoute({...}) | dropped | dropped | kept | dropped | dropped |
An enum file that also derives a list, as in values(Status) | dropped | dropped | kept | dropped | kept |
A curried route, annotatePageProps<T>()(defineRoute({...})) or annotateRequestPayload<T>()(defineRoute({...})) | dropped | kept | kept | kept | dropped |
Any of the above with /* @__PURE__ */ on each call | dropped | dropped | dropped | dropped | dropped |
For a curried route, write the comment on the outer call and on the inner defineRoute:
export const show = /* @__PURE__ */ annotatePageProps<ShowProps>()(
/* @__PURE__ */ defineRoute({ url: "/users/{user}", methods: ["get"] }),
);The Enums and Routing pages show the same notes beside the generated code.
Where to read more
Each package page has a short Bundling section with its own exceptions: