Bundle optimization

Bundle, Build, and Code Splitting

This skill measures production build output and turns the data into reviewable findings. It does not promise gains from reducing raw bytes: a change is an improvement only when the same scenario shows lower transfer or parse cost, or faster interaction, without regressions in requests or behavior.

Memory and patterns

Read the local MEMORY.md and follow ../.shared/SKILL-MEMORY-PROTOCOL.md; use node "<skills-root>/.shared/src/memory-cli.js" append ... for actionable results. The utility validates, renumbers, and retains up to 12 entries.

Before making decisions influenced by existing code, follow ../.shared/PATTERN-LEARNING-PROTOCOL.md and query the repository catalog with node "<skills-root>/.shared/src/pattern-learning/pattern-cli.js" query ...; after confirming a new or refined pattern in the code, consolidate it with node "<skills-root>/.shared/src/pattern-learning/pattern-cli.js" upsert ....

Compatibility

Compatible with React 18/19, Vite 7/8, and Node 22.13+.

When not to use

• The bottleneck is re-renders, Context propagation, or component structure; use the memoization, state-management, or component-refactoring skills.
• No reproducible production build exists yet; this skill requires comparable artifacts.
• The goal is removing unreachable code; use the dead-code-elimination skill.

Reproducible workflow

1. Use the same commit, lockfile, Node version, and build command for the baseline and improved version.

2. Add createBundleStatsPlugin() to the Vite configuration's plugins. The plugin writes dist/stats.json using the versioned schema below. It records JavaScript chunks; CSS and other assets must still be measured through the project's build report or waterfall.

3. Run the analyzer with explicit limits:

   node "<skill-dir>/scripts/analyze-bundle.js" dist/stats.json \
     --format json --output-dir validation-results/bundle
   

   Output behavior follows the shared CLI contract in ../.shared/README.md; this analyzer also accepts --output-dir <dir> for the report destination.

4. In the same initial flow, compare bytes, gzipBytes, brotliBytes, request count, and interaction time. Repeat the measurements; size alone is not a UX metric.

Stats schema

bundleStatsPlugin and analyze-bundle.js share schemaVersion: 1:

{
  "schemaVersion": 1,
  "chunks": [{
    "name": "index.js",
    "bytes": 45000,
    "gzipBytes": 12500,
    "brotliBytes": 10800,
    "isEntry": true,
    "imports": ["vendor.js"],
    "dynamicImports": ["reports.js"],
    "modules": [{ "name": "src/main.jsx", "bytes": 2048 }]
  }],
  "modules": [{ "name": "src/main.jsx", "bytes": 2048 }]
}

The producer calculates all three representations from actual content. The analyzer rejects invalid JSON or unknown versions with an explicit error. Fixtures without schemaVersion are still normalized for compatibility with the supported input format, but new reports must use schema 1.

Code splitting and manualChunks

React.lazy(() => import('./pages/Reports.jsx')) is appropriate for a route or feature outside the initial flow. The module must expose a default export and must be inside Suspense with a stable fallback. Do not lazy-load small or critical components without measuring the cost of an additional request.

Load a large module conditionally, via import() inside an effect or handler, only when its feature is activated, and pair it with loading and error states. To reduce perceived latency, preload the chunk on user intent (hover or focus on the trigger) or when a feature flag turns on; measure the interaction gain against the extra request.

manualChunks is optional. For Vite 7 and Rollup, start with default grouping, measure it, and only then use an allowlist of libraries or routes whose waterfall and caching improved. Returning 'vendor' for all of node_modules can increase initial loading and invalidate caches; the example configuration does not do so. In Vite 8, build.rollupOptions is a deprecated alias of build.rolldownOptions, and output.manualChunks (especially its object form) was removed or deprecated. Migrate to Rolldown's code-splitting options instead of copying the Rollup example. Always validate against the installed version.

Barrel files are a tree-shaking hypothesis, not proof of a regression. Compare the graph and bundle before changing imports; a modern bundler may eliminate unused re-exports.

Interpreting findings

• Large initial chunk: investigate dynamic imports by route and compressed cost; do not apply manualChunks automatically.
• Large async chunk: confirm it is truly on demand and that fragmentation did not multiply requests.
• Heavy vendor code: try selective imports or lazy loading. Keep a manual chunk only if the scenario's metric improves.
• No violations: this does not guarantee good UX; monitor RUM or Lighthouse and the waterfall for each regression.

See checklists/bundle-checklist.md, the before and after examples, and fixtures/stats.json for a local smoke test of the schema and output flags.