[jackmisner]

What this is, and what it isn't

The investigation this came from recommended against the change it was investigating. There is no code here.

The question was whether to engineer away a ~26 KB penalty that a CommonJS consumer of the root entry pays. Measured, the penalty is real but lands almost entirely where CommonJS consumers aren't, and every in-package fix measured worse than the one-line change the affected consumer has to make anyway. What's left worth doing is telling them which line that is.

The measurements behind it

	require	static import	await import() destructured	await import() namespace
esbuild	27,788	1,358	~28,100	~28,100
Rollup	27,853	323	464	27,561
Rolldown (Vite 8)	27,512	994	27,867	27,866
webpack 5	1,109	469	~2,350	~2,349

Per entry, require vs static import:

entry	esbuild	webpack 5
root	+26,430 B	+640 B
./react	+2,695 B	+471 B
./server	+389 B	+202 B

Three things follow, and they are why this PR has no code:

1. "CommonJS can't be tree-shaken" is false for webpack 5. It produced 1,109 bytes from a 54,621-byte CJS module. The 20× is an esbuild/Rollup/Rolldown property, not a property of the format.
2. ./server — the one entry where CommonJS consumers are realistic — costs 87–204 gzipped bytes, and can't be improved: a static import already retains ~89% of it, because normalizeUtmParams genuinely needs the sanitizer, PII filter and defaults.
3. To get hit you need all three of bundling for a browser, writing require(), and importing from the root barrel. Vite, Next, Remix, Astro, Rollup, esbuild and webpack 5 all resolve the import condition for a browser target by default.

Why the note earns its place

A consumer who notices the root entry is heavy reaches for await import(), and on three of four bundlers it buys nothing — on webpack it is worse than require, because it forces a separate chunk. They would measure no improvement and conclude the library is simply fat. Only a static import reliably helps, and nothing said so.

What changed

• Installation: a paragraph on what a require() of the root costs, per bundler, that await import() is not a dependable substitute, and that a static import at the call site is.
• Platform Support → Node.js: unbundled Node loads the whole entry file either way, so the bundle figures do not apply there at all — the cost is a one-off ~52KB parse, or ~6KB for /server.
• A correction to the /server size comparison, which gave "roughly 5KB against the root entry's 52KB" without saying those are raw files in the package rather than what a consumer ships — and the server figure was 6KB.

Options rejected, with the evidence

• tsup splitting for CJS. Works, and check:package passes fully green, which is what makes it a trap. Measured: root CJS +22%, /react CJS +57%, /server CJS +56%, ESM roughly neutral; only the tarball improves (−24%). splitting: false tree-shakes each entry independently; splitting hoists the union into chunks and nothing can be dropped across a chunk boundary.
• Finer-grained subpaths. Technically effective (capture-only 28.3 → 10.3 KB) but using one requires editing the import line — and a consumer willing to do that can switch require to import and get 3.1 KB instead of 10.3 KB. Six permanent public entry points to offer something 3× worse. Two slices also duplicate their shared common/*, so three slices is worse than the barrel.
• Dropping the require condition. Fails our own gate: attw reports a live node16 (from CJS) error, and require(esm) only landed in Node 20.19/22.12, so engines.node >= 20.0.0 would have to rise.

Review

Docs-only needs no review under the repo's tiers, but this prose is almost entirely measured numbers, so it got a claim audit — which was the right call. It found that my await import() explanation was backwards: destructuring is what lets Rollup prune (464 B) rather than what stops it (27,561 B read as m.x), "keeps every export" was false for webpack, and the Vite inference was stale since vite@latest depends on Rolldown, not Rollup. I re-verified every corrected figure myself, Rolldown included, before rewriting. One earlier figure I caught myself: /react is ~2.7 KB on esbuild, not the "few hundred bytes" I first wrote.

Follow-ups, not in this PR

• Module-scope purity in src/config/defaults.ts and src/common/keys.ts. Array spreads and Object.keys() at module scope stop esbuild proving them pure, costing ~1 KB on the ESM path — the path nearly everyone is on. Format-independent, no API change, and worth more than this PR. Agreed as the next one.
• A latent dual-instance hazard, unrelated to size. A consumer whose dependency tree reaches the package through both conditions gets two copies of defaultProtocol, so setDefaultProtocol applies to half their app. Inherent to dual-format publishing with module-level mutable state.
• The multi-entry case is unmeasured. Nobody measured a consumer importing both the root and ./react; splitting: false duplicates shared modules across entries, which could be ~13 KB. It wouldn't change a docs-only outcome, so it is flagged rather than guessed at.