Next.js Bundle Streamlined

Analyze and optimize your Next.js application bundle size with webpack-bundle-analyzer integration, dependency auditing, code splitting configuration, and actionable size reduction recommendations.

When to Use This Command

Run this command when you need to understand and reduce your Next.js application's bundle size.

• Your production build is larger than expected and you need to identify heavy dependencies
• You want to set up @next/bundle-analyzer with optimal webpack configuration
• You need to audit production vs. development dependencies for unnecessary inclusions
• You want to implement code splitting and tree-shaking optimizations

Use it also when:

• You need to configure optimizePackageImports for icon and utility libraries
• You want to set up custom webpack split chunks for vendor and common code separation

Quick Start

Copy
# .claude/commands/nextjs-bundle-streamlined.md
name: nextjs-bundle-streamlined
description: Analyze and optimize Next.js bundle size
arguments:
  mode: analyze | optimize | audit

Copy
# Run bundle analysis
claude nextjs-bundle-streamlined "analyze"

Expected output:
Bundle Analysis:
  Total Size: 487 KB (gzipped)
  Largest Chunks:
    vendors.js    218 KB  (lucide-react: 89 KB)
    commons.js     94 KB  (date-fns: 42 KB)
    main.js        68 KB

  Recommendations:
    1. Add lucide-react to optimizePackageImports (-67 KB)
    2. Switch to date-fns/esm for tree-shaking (-28 KB)
    3. Dynamic import the chart library (-34 KB)

Core Concepts

Concept	Description
Bundle Analyzer	Visual treemap of your webpack output showing module sizes
Code Splitting	Breaking your bundle into smaller chunks loaded on demand
Tree Shaking	Eliminating unused code during the build process
Vendor Chunk	Separate bundle for node_modules dependencies
Package Imports	Next.js optimization for auto-barrel-file libraries

Optimization Pipeline:
  Build ──> Analyze ──> Identify Bloat ──> Apply Fixes
    │                       │                  │
    v                       v                  v
  .next/              Treemap HTML       next.config.js
  (build output)      (visualization)    (optimizations)

Configuration

Parameter	Default	Description
mode	analyze	Operation mode: analyze, optimize, audit
threshold	50KB	Flag chunks larger than this size
format	html	Analysis output: html (treemap), json, text
gzip	true	Show gzipped sizes in analysis
include-dev	false	Include devDependencies in audit

Best Practices

1. Run analysis after every major dependency change -- Adding a new library can dramatically affect bundle size. Analyze after each npm install to catch bloat early.

2. Use optimizePackageImports for icon libraries -- Libraries like lucide-react, @heroicons/react, and date-fns have barrel files that import everything. Add them to optimizePackageImports.

3. Dynamic import heavy components -- Use next/dynamic for components that are not needed on initial page load, such as charts, maps, or rich text editors.

4. Set coverage thresholds in CI -- Add bundle size checks to your CI pipeline to prevent regressions. Fail the build if the bundle exceeds a defined size limit.

5. Separate vendor chunks by update frequency -- Group rarely-updated libraries (React, Next.js) into a stable vendor chunk that benefits from long-term browser caching.

Common Issues

1. No build found for analysis -- Run npm run build before analyzing. The bundle analyzer needs the .next/ output directory to generate the treemap.

2. ANALYZE environment variable not set -- The bundle analyzer only runs when ANALYZE=true. Set it before building: ANALYZE=true npm run build.

3. False positives in dependency audit -- Some devDependencies appear in the audit because they have production sub-dependencies. Use --include-dev false to filter these out.