<!-- Generated from models/_canonical by scripts/build-model-variants.js. Edit the canonical source, not this file. Behavioural profile for Claude: scripts/model-profiles.json -->

<critical_constraints> FORBIDDEN: Truncating code or writing placeholders such as "// ... existing code ..." or "# rest unchanged". Every edit is complete and applies as written. FORBIDDEN: Reporting a check as passed without showing the command and its output. REQUIRED: Reason through the rules below before the first edit; when two rules conflict, the one stated first wins. </critical_constraints>

---

#Purpose

Rules for controlling shipped JavaScript. A byte of JavaScript costs far more than a byte of image: it must be downloaded, parsed, compiled and executed on the main thread, on a device you do not control.

Two rules govern everything: measure before cutting, and enforce a budget, because bundles grow one innocuous pull request at a time.

---

#Budget first, in CI

json
// .size-limit.json
[
  { "path": "dist/assets/index-*.js", "limit": "160 KB" },
  { "path": "dist/assets/vendor-*.js", "limit": "120 KB" }
]

• Measure compressed size (Brotli/gzip) — that is what users download — and track uncompressed too, because parse and execute cost scales with the uncompressed bytes.
• Fail the build on a regression. A warning is ignored; a failing check is discussed.
• Report the delta on every pull request, so the cost of a dependency is visible at the moment someone proposes it.

Reasonable starting targets for an application shell: < 160 KB compressed initial JavaScript, and < 100 KB for a content site. Treat them as budgets to defend, not achievements to reach once.

---

#Analyse before optimising

bash
npx vite-bundle-visualizer                 # Vite/Rollup
ANALYZE=true next build                    # Next.js
npx source-map-explorer 'dist/**/*.js'     # any bundler with source maps

It is almost always one or two dependencies, not a hundred small things. Look for:

• The single largest module.
• Duplicate copies of one library at different versions — check with npm ls <pkg> and deduplicate in the lockfile.
• Anything in the initial chunk not needed for first paint.
• Polyfills for browsers you no longer support: check the browserslist target, which frequently still says something from years ago.

---

#Dependency discipline

The highest-value habit: check the cost before adding, not after.

ts
import _ from "lodash";               // ❌ pulls the whole library
import debounce from "lodash/debounce";   // ✅ one function
import { debounce } from "lodash-es";     // ✅ tree-shakeable build

The platform has absorbed most small utilities. Before adding a dependency, check bundlephobia.com for its cost including transitive dependencies, and check whether a standard API already does it.

Never ship a library for one function. A 70 KB dependency imported for debounce is the most common single avoidable regression.

---

#Make tree shaking work

Tree shaking removes unused exports — but only when the bundler can prove removal is safe. It silently fails to shake when:

• The package ships CommonJS only. require() is dynamic, so nothing can be proven. Prefer ESM builds.
• The package has side effects at module scope and no "sideEffects": false in its package.json.
• You import * as x and then index dynamically.
• A barrel file (index.ts re-exporting everything) pulls in a module chain the bundler cannot prune. Barrel files are a common and invisible cause.

json
// In your own package: tell bundlers it is safe to drop unused modules
{ "sideEffects": ["*.css"] }

Verify rather than assume: build, then search the output for a symbol you believe was removed. Tree shaking is frequently believed to be working when it is not.

---

#What else to cut

• Polyfills: target modern browsers and let older ones get a separate legacy bundle, rather than serving everyone the polyfills the oldest needs.
• Locale and timezone data: import the active locale, not all forty.
• Source maps: generate them, upload them to your error tracker, and do not serve them publicly.
• Development-only code: assert that NODE_ENV is production so development branches are eliminated.
• Duplicated framework runtimes: two versions of React in one bundle is both a size problem and a runtime bug.
• Third-party scripts are not in your bundle but are on your critical path — analytics and tag managers are frequently the largest script on the page and nobody owns them. Inventory and defer them. → Frontend/performance

Then split what remains, so the initial download is only what the first screen needs. → Frontend/code-splitting

---

#Anti-patterns

---

#Checklist

• A compressed-size budget is enforced in CI and fails the build
• Uncompressed size is tracked for parse and execute cost
• Pull requests report the bundle-size delta
• The bundle has been analysed and the largest modules identified
• No duplicate copies of a library exist at different versions
• Dependency cost is checked before adding, not after
• No dependency is included for a single small utility
• Imports are named, from tree-shakeable ESM builds
• sideEffects is declared in first-party packages
• Tree shaking is verified against the built output, not assumed
• Barrel files are not on hot import paths
• browserslist reflects actually supported browsers
• Only the active locale's data is bundled
• Source maps are uploaded to error tracking, not served publicly
• Development-only code is eliminated in production builds
• Third-party scripts are inventoried, deferred and owned
• Remaining code is split so the initial chunk serves the first screen only