Skip to main content

Bundle Size Analysis

This document explains the bundle size analysis implementation in the Cypress Dashboard project.

Overview​

The bundle size analysis feature automatically monitors the size of the client application bundle and ensures that changes don't significantly increase the bundle size without proper justification.

Features​

1. Automated CI/CD Analysis​

  • Trigger: Runs on every pull request that modifies client code
  • Comparison: Compares current PR bundle size with main branch
  • Thresholds:
    • Maximum size increase: 512KB
    • Maximum percentage increase: 10%
  • Failure: PR fails if thresholds are exceeded

2. Local Development Tools​

  • Bundle analysis script: npm run bundle-size
  • Interactive visualization: npm run build:analyze
  • Detailed reporting: File-by-file breakdown with optimization suggestions

Implementation Details​

GitHub Actions Workflow​

The bundle size analysis is implemented in .github/workflows/pr-validation.yml with three main steps:

  1. Bundle size analysis: Builds the project and calculates current bundle sizes
  2. Compare with main branch: Fetches main branch, builds it, and compares sizes
  3. Bundle size validation: Applies thresholds and fails if exceeded

Local Scripts​

  • client/scripts/analyze-bundle.js: Node.js script for local bundle analysis
  • client/vite.config.ts: Vite configuration with rollup-plugin-visualizer
  • client/package.json: Scripts for bundle analysis commands

Usage​

For Developers​

Local Analysis​

# Quick bundle size summary
cd client
npm run bundle-size

# Detailed interactive analysis
npm run build:analyze
# Opens dist/bundle-analysis.html in browser

CI/CD Integration​

The analysis runs automatically on pull requests. If your PR fails due to bundle size:

  1. Review the failure message for specific size increases
  2. Consider optimization strategies:
    • Code splitting with dynamic imports
    • Lazy loading of components
    • Tree shaking unused dependencies
    • Analyzing large dependencies
  3. Run local analysis to identify large files
  4. Implement optimizations and test locally

For Reviewers​

When reviewing PRs, check the bundle size analysis output:

  • ✅ Green: Bundle size decreased or stayed the same
  • ⚠️ Yellow: Bundle size increased but within limits
  • ❌ Red: Bundle size increased beyond acceptable thresholds

Configuration​

Thresholds​

Current thresholds can be modified in .github/workflows/pr-validation.yml:

MAX_SIZE_INCREASE=524288  # 512KB in bytes
MAX_PERCENT_INCREASE=10   # 10% increase

Bundle Analyzer​

The interactive bundle analyzer is configured in client/vite.config.ts:

visualizer({
  filename: 'dist/bundle-analysis.html',
  open: true,
  gzipSize: true,
  brotliSize: true,
})

Optimization Strategies​

Code Splitting​

// Use dynamic imports for large components
const LazyComponent = lazy(() => import('./LargeComponent'));

// Route-based code splitting
const Dashboard = lazy(() => import('./pages/Dashboard'));

Tree Shaking​

// Import only what you need
import { debounce } from 'lodash-es';
// Instead of: import _ from 'lodash';

Bundle Analysis​

# Identify large dependencies
npm run build:analyze

# Check what's included in your bundle
npm run bundle-size

Troubleshooting​

Common Issues​

Bundle size increased unexpectedly:

  1. Check if new dependencies were added
  2. Verify tree shaking is working correctly
  3. Look for duplicate dependencies
  4. Consider if the increase is justified

Analysis script fails:

  1. Ensure the project builds successfully first
  2. Check that dist/ directory exists
  3. Verify Node.js version compatibility

CI/CD analysis fails:

  1. Check GitHub Actions logs for specific errors
  2. Verify the main branch builds successfully
  3. Ensure all dependencies are properly locked

Future Enhancements​

Potential improvements to consider:

  • Bundle size tracking over time
  • Performance budget integration
  • Automated optimization suggestions
  • Integration with performance monitoring tools
  • Bundle composition change detection