bundle-size-guardian

name

bundle-size-guardian

description

Keep the persian-tools published bundle small, tree-shakable, and side-effect-free. Use whenever a change might add or grow the bundle — a new dataset, a new module, a new dependency, or a refactor that moves code between files. Also use when "JS bundle" or "Type definitions" size-limit checks fail in CI. Covers the .skip.ts convention, sideEffects: false, the 860 kB JS / 100 kB types budget, and how to investigate which symbols pushed it over.

Keeping the bundle small

The package is published as ESM + CJS with TypeScript declarations. The published size is enforced by size-limit via the test:size step that runs after every build. This skill explains the rules and how to fix overages.

The current budget

From .size-limit.json:

Artifact	Path	Limit
JS bundle	build/index.js + build/index.mjs	860 kB
Type definitions	build/index.d.ts + build/index.d.mts	100 kB

These are un-gzipped sizes (gzip: false, brotli: false). When you raise the limit, justify it in the PR description and update both numbers together if both grew.

Tree-shaking is on — keep it that way

package.json declares "sideEffects": false. Bundlers can therefore drop any module the user didn't import. To preserve this guarantee:

1. Never run effectful code at module top-level. No console.log, no global registration, no Object.defineProperty(globalThis, ...). Top-level should only declare constants/types/functions.