Bundle Optimization
On this page
Bundle Optimization Goals
- Reduce initial JS cost for faster first interaction.
- Keep long term performance stable with budgets and gates.
- Prevent regressions caused by accidental heavy imports.
Primary Bloat Sources
- Large third party libraries imported into critical routes.
- Shared barrel exports pulling extra code into client bundles.
- Client boundary expansion: importing server only modules into client components.
- Multiple versions of the same dependency in the tree.
Operational Controls
- Set bundle size budgets per route group.
- Track changes per pull request and fail on large regressions.
- Lock dependency versions and audit additions.
- Prefer small focused packages over large frameworks for single functions.
Split Strategy
- Split by route and heavy feature boundaries.
- Lazy load rarely used admin and settings areas.
- Defer non critical widgets and analytics to after interaction.
Tree Shaking Discipline
- Prefer ESM imports for tree shaking.
- Avoid importing entire libraries when only one function is needed.
- Watch for side effect imports that disable tree shaking.
Cache Friendly Deploys
- Use content hashed asset filenames for long term caching.
- Keep entry chunks stable to improve cache reuse.
- Avoid unnecessary chunk churn from inconsistent import patterns.
Failure Modes
- Small code change causes large bundle increase due to barrel export pull in.
- Client only code accidentally imports server modules and expands bundle.
- Chunk duplication due to inconsistent imports and version conflicts.
- Over splitting creates many requests and waterfall loading.
Optimization Checklist
- Budgets exist and are enforced in CI.
- Heavy dependencies are isolated behind lazy boundaries.
- Imports are direct and avoid pulling entire libraries.
- Duplicate dependency versions are removed.
- Route level splitting is aligned with user journeys.