Bundle Analysis | Bootspring Docs

Patterns for analyzing and optimizing JavaScript bundle size.

Overview#

Bundle analysis helps you understand what's in your JavaScript bundles. This pattern covers:

Next.js bundle analyzer setup
Identifying large dependencies
Code splitting strategies
Tree shaking optimization
Import cost awareness

Prerequisites#

npm install @next/bundle-analyzer

Code Example#

Bundle Analyzer Setup#

// next.config.js
const withBundleAnalyzer = require('@next/bundle-analyzer')({
  enabled: process.env.ANALYZE === 'true'
})

/** @type {import('next').NextConfig} */
const nextConfig = {
  // Your existing config
}

module.exports = withBundleAnalyzer(nextConfig)

# Run analysis
ANALYZE=true npm run build

Package Import Optimization#

// next.config.js
/** @type {import('next').NextConfig} */
const nextConfig = {
  experimental: {
    optimizePackageImports: [
      'lucide-react',
      '@radix-ui/react-icons',
      'date-fns',
      'lodash',
      '@heroicons/react',
      'recharts'
    ]
  }
}

module.exports = nextConfig

Smart Imports#

// AVOID: Importing entire libraries
// This pulls in the entire library
import { format, parse, addDays, subDays, isAfter } from 'date-fns'
import { debounce, throttle, merge, cloneDeep } from 'lodash'
import { Search, Menu, X, ChevronDown, ChevronUp } from 'lucide-react'

// BETTER: Import specific functions
import { format } from 'date-fns/format'
import { parseISO } from 'date-fns/parseISO'
import debounce from 'lodash/debounce'
import throttle from 'lodash/throttle'

// With optimizePackageImports, this is automatically tree-shaken:
import { Search, Menu } from 'lucide-react'

Dynamic Imports for Heavy Libraries#

// components/Charts.tsx
'use client'

import dynamic from 'next/dynamic'

// Heavy charting library - only load when needed
const ResponsiveContainer = dynamic(
  () => import('recharts').then(mod => mod.ResponsiveContainer),
  { ssr: false }
)

const LineChart = dynamic(
  () => import('recharts').then(mod => mod.LineChart),
  { ssr: false }
)

const Line = dynamic(
  () => import('recharts').then(mod => mod.Line),
  { ssr: false }
)

// Or load all at once
const Recharts = dynamic(
  () => import('recharts'),
  {
    ssr: false,
    loading: () => <div className="h-64 animate-pulse bg-gray-200" />
  }
)

Code Splitting by Route#

// Next.js App Router automatically splits by route
// Each page.tsx becomes its own chunk

// app/
// |-- page.tsx           -> (main bundle ~50KB)
// |-- dashboard/
// |   |-- page.tsx       -> (dashboard bundle ~30KB)
// |-- admin/
// |   |-- page.tsx       -> (admin bundle ~40KB)

// Check bundle sizes
// After build, check .next/analyze/client.html

Conditional Feature Bundles#

// lib/features.ts
export const loadEditorBundle = () =>
  import('@/features/editor').then(mod => mod.Editor)

export const loadAnalyticsBundle = () =>
  import('@/features/analytics').then(mod => mod.Analytics)

export const loadAdminBundle = () =>
  import('@/features/admin').then(mod => mod.AdminPanel)

// components/FeatureLoader.tsx
'use client'

import { Suspense, lazy } from 'react'

const featureComponents = {
  editor: lazy(() => import('@/features/editor')),
  analytics: lazy(() => import('@/features/analytics')),
  admin: lazy(() => import('@/features/admin'))
}

export function FeatureLoader({
  feature,
  enabled
}: {
  feature: keyof typeof featureComponents
  enabled: boolean
}) {
  if (!enabled) return null

  const Component = featureComponents[feature]

  return (
    <Suspense fallback={<FeatureSkeleton />}>
      <Component />
    </Suspense>
  )
}

Webpack Bundle Analysis Script#

// scripts/analyze-bundle.ts
import fs from 'fs'
import path from 'path'

interface ChunkInfo {
  name: string
  size: number
  modules: string[]
}

function analyzeBundle() {
  const statsPath = path.join(process.cwd(), '.next/stats.json')

  if (!fs.existsSync(statsPath)) {
    console.log('Run: ANALYZE=true npm run build')
    return
  }

  const stats = JSON.parse(fs.readFileSync(statsPath, 'utf-8'))

  // Find largest chunks
  const chunks: ChunkInfo[] = stats.chunks
    .map((chunk: any) => ({
      name: chunk.names[0] || 'unknown',
      size: chunk.size,
      modules: chunk.modules?.map((m: any) => m.name) || []
    }))
    .sort((a: ChunkInfo, b: ChunkInfo) => b.size - a.size)

  console.log('\nLargest chunks:')
  chunks.slice(0, 10).forEach((chunk, i) => {
    console.log(`${i + 1}. ${chunk.name}: ${(chunk.size / 1024).toFixed(2)} KB`)
  })

  // Find largest node_modules
  const moduleSizes = new Map<string, number>()

  stats.modules?.forEach((module: any) => {
    const match = module.name?.match(/node_modules\/(@[^/]+\/[^/]+|[^/]+)/)
    if (match) {
      const pkg = match[1]
      moduleSizes.set(pkg, (moduleSizes.get(pkg) || 0) + module.size)
    }
  })

  console.log('\nLargest dependencies:')
  Array.from(moduleSizes.entries())
    .sort((a, b) => b[1] - a[1])
    .slice(0, 10)
    .forEach(([pkg, size], i) => {
      console.log(`${i + 1}. ${pkg}: ${(size / 1024).toFixed(2)} KB`)
    })
}

analyzeBundle()

Size Limit Configuration#

// package.json
{
  "scripts": {
    "size": "size-limit",
    "size:why": "size-limit --why"
  },
  "size-limit": [
    {
      "path": ".next/static/chunks/main-*.js",
      "limit": "100 KB"
    },
    {
      "path": ".next/static/chunks/pages/_app-*.js",
      "limit": "50 KB"
    },
    {
      "path": ".next/static/chunks/framework-*.js",
      "limit": "50 KB"
    }
  ]
}

npm install --save-dev size-limit @size-limit/preset-app

Alternative Lighter Libraries#

// Instead of moment.js (300KB)
// Use date-fns (tree-shakeable) or dayjs (2KB)
import dayjs from 'dayjs'

// Instead of lodash (70KB full)
// Use individual functions or native JS
import debounce from 'lodash/debounce' // Just the function

// Instead of axios (13KB)
// Use native fetch or ky (3KB)
import ky from 'ky'

// Instead of uuid (7KB)
// Use crypto.randomUUID() (native)
const id = crypto.randomUUID()

// Instead of classnames (1KB)
// Use clsx (228B) or cn utility
import { clsx } from 'clsx'

Monitoring Bundle Size in CI#

# .github/workflows/bundle-size.yml
name: Bundle Size

on: [pull_request]

jobs:
  size:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
          cache: 'npm'

      - run: npm ci
      - run: npm run build

      - name: Check bundle size
        uses: preactjs/compressed-size-action@v2
        with:
          repo-token: "${{ secrets.GITHUB_TOKEN }}"
          pattern: ".next/static/**/*.js"

Usage Instructions#

Run ANALYZE=true npm run build to generate bundle analysis
Review the treemap visualization in .next/analyze/
Identify and optimize the largest dependencies
Use dynamic imports for heavy, rarely-used features
Set up bundle size budgets in CI

Best Practices#

Analyze regularly - Check bundle size on each PR
Set budgets - Define and enforce size limits
Prefer smaller alternatives - Use lighter libraries
Dynamic import heavy code - Split non-critical features
Tree shake - Enable and verify tree shaking works
Remove unused code - Audit and remove dead dependencies
Monitor trends - Track bundle size over time

Lazy Loading - Load on demand
Optimization - Performance tips
Code Splitting - Split bundles
Profiling - Find bottlenecks