Production bundle under 250KB gzipped for initial route

A JavaScript bundle over 250KB gzipped on the initial route directly punishes mobile users and anyone on a slower connection. ISO 25010:2011 time-behaviour is the formal hook, but the real-world impact is measured in seconds: Google's research shows that each additional second of load time increases bounce rate by up to 20%. An oversized initial bundle means users see a blank or non-interactive page while megabytes of JavaScript parse and execute — before a single product, article, or dashboard widget appears.

Run npx @next/bundle-analyzer or npx webpack-bundle-analyzer on your production build to identify the largest contributors. Replace heavy utility libraries (e.g., replace moment with date-fns, full lodash with lodash-es named imports). Move any route-specific code behind dynamic imports so it only loads when needed.

# Analyze your production build
NEXT_PUBLIC_BUNDLE_ANALYZE=true npm run build
# Or: npx source-map-explorer .next/static/chunks/*.js

• ID: bundle-size-critical

• Severity: critical

• What to look for: Count all JavaScript chunks loaded for the initial route by examining the production build output. Examine the production build output. For Next.js, check the output of npm run build or .next/static/chunks/ directory. For other frameworks, look in dist/, build/, or equivalent output directory. Use source-map-explorer, webpack-bundle-analyzer, or esbuild's --metafile to analyze bundle composition. Measure the gzipped size of the main JavaScript bundle(s) loaded for the initial route.

• Pass criteria: The combined gzipped size of JavaScript bundles required to render the initial page route is under 250KB. Vendor code, framework core, and application code combined must be under 250KB gzipped. Report: "X chunks totaling Y KB gzipped for initial route."

• Fail criteria: The initial route's gzipped bundle size exceeds 250KB, or bundle size cannot be measured from the build output.

• Skip (N/A) when: Never — every web application should measure and optimize bundle size.

• Do NOT pass when: Bundle is under 250KB only because CSS is extracted separately but CSS itself exceeds 100KB gzipped, or tree-shaking is disabled and unused code inflates the apparent size.

• Report even on pass: Report the exact gzipped size and top 3 chunks by size: "Initial bundle: X KB gzipped across Y chunks."

• Cross-reference: For CSS bundle size concerns, see the css-purging-enabled check. For code splitting strategy, see the code-splitting-routes check.

• Detail on fail: Report the measured gzipped bundle size and list the top 3-5 largest dependencies by size. Example: "Initial bundle is 412KB gzipped. Top dependencies: lodash (85KB), moment.js (78KB), moment-timezone (64KB), marked (45KB)"

• Remediation: Large bundles cause slow page load times. Use a bundle analyzer tool to identify large dependencies that can be replaced, removed, or dynamically loaded. Common culprits are utility libraries (lodash, moment) that can be replaced with smaller alternatives (date-fns, native APIs). Implement dynamic imports (code splitting) for route-specific code so only the current route's code is loaded. For Next.js, examine .next/static/chunks/ or run npx @next/bundle-analyzer from the app/ directory.