CLI Interface

# Basic usage
size-limit

# Common options
size-limit [options]

# Key options:
--json                    # Output results in JSON format
--silent                  # Silent mode (no console output except errors)
--watch                   # Watch mode for file changes during development
--why                     # Bundle analysis mode with detailed breakdown
--config FILE             # Use specific configuration file
--limit SIZE              # Override size limit for all checks
--save-bundle DIR         # Save bundle to directory for analysis
--clean-dir               # Clean bundle directory (requires --save-bundle)
--hide-passed             # Hide passed checks in output
--highlight-less          # Highlight improvements
--compare-with FILE       # Compare with previous stats.json (requires --why)
--debug                   # Show internal configs for issue report
--help                    # Show help information
--version                 # Show version information

# Basic size check using package.json configuration
size-limit

# JSON output for CI integration
size-limit --json

# Silent mode for scripts
size-limit --silent

# Watch mode for development
size-limit --watch

# Bundle analysis
size-limit --why

# Use specific configuration file
size-limit --config .size-limit.json

# Override size limit for all checks
size-limit --limit "50 kB"

# Save bundle for analysis
size-limit --save-bundle ./analysis-output

# Clean and save bundle
size-limit --save-bundle ./analysis-output --clean-dir

# Bundle analysis with comparison
size-limit --why --compare-with previous-stats.json

# Hide passed checks in output
size-limit --hide-passed

# Highlight improvements
size-limit --highlight-less

# Debug mode
size-limit --debug

# Standard console output shows:
# - Check names and file paths
# - Size measurements with limits
# - Pass/fail status with color coding
# - Time measurements when enabled
# - Summary of results

size-limit
# Example output:
#   Package size: 12.34 kB with all dependencies, minified and gzipped
#   Size limit:   15 kB
#   
#   Running time: 0.1 s
#   Time limit:   1 s
#   
#   ✓ Passed

# JSON output for programmatic consumption
size-limit --json

# Example JSON structure:
# [
#   {
#     "name": "Main Bundle",
#     "passed": true,
#     "size": 12636,
#     "sizeLimit": 15360,
#     "running": 100,
#     "loading": 250
#   }
# ]

# Configuration priority (highest to lowest):
# 1. .size-limit.js (dynamic configuration)
# 2. .size-limit.json
# 3. package.json "size-limit" field
# 4. Command line arguments

// package.json
{
  "size-limit": [
    {
      "path": "dist/bundle.js",
      "limit": "10 kB"
    },
    {
      "path": "dist/worker.js",
      "limit": "5 kB",
      "webpack": false
    }
  ]
}

// .size-limit.json
[
  {
    "name": "Main Bundle",
    "path": "dist/app.js",
    "limit": "100 kB",
    "running": false
  }
]

// .size-limit.js
module.exports = [
  {
    name: "Dynamic Config",
    path: process.env.BUNDLE_PATH || "dist/bundle.js",
    limit: "50 kB",
    modifyWebpackConfig: (config) => {
      // Custom webpack modifications
      return config;
    }
  }
];

# Plugin detection rules:
# - Scans package.json dependencies and devDependencies  
# - Loads plugins matching @size-limit/* pattern
# - Loads plugins matching size-limit-* pattern
# - Plugins are loaded automatically based on configuration needs

# Install core plugins
npm install --save-dev @size-limit/file
npm install --save-dev @size-limit/webpack
npm install --save-dev @size-limit/time

# Install preset (includes multiple plugins)
npm install --save-dev @size-limit/preset-app
npm install --save-dev @size-limit/preset-big-lib
npm install --save-dev @size-limit/preset-small-lib

# Watch mode for development
size-limit --watch

# Features:
# - Monitors configured files for changes
# - Debounced re-execution (200ms delay)
# - Real-time feedback during development
# - Throttled to prevent excessive runs

# Bundle analysis requires @size-limit/webpack-why or @size-limit/esbuild-why
size-limit --why

# Features:
# - Detailed bundle breakdown
# - Dependency analysis
# - Tree-shaking effectiveness
# - Module size contributions
# - Interactive reports (when supported)

# CI-friendly features:
# - Exit codes: 0 for pass, 1 for fail
# - JSON output for parsing
# - Silent mode for clean logs
# - No interactive prompts

# GitHub Actions
- name: Check bundle size
  run: npx size-limit --json > size-report.json

# Check exit code
- name: Validate size limits
  run: npx size-limit --silent

# Shell script integration
if npx size-limit --silent; then
  echo "Size limits passed"
else
  echo "Size limits exceeded"
  exit 1
fi

# Common error scenarios:
# - Missing configuration
# - Plugin dependencies not installed  
# - Invalid configuration format
# - File path errors
# - Limit exceeded errors

# Error output includes:
# - Clear error descriptions
# - Configuration examples
# - Plugin installation suggestions
# - Helpful debugging information

# Missing configuration
size-limit
# Error: Create Size Limit config in package.json
# Example configuration shown

# Missing plugin
size-limit
# Error: Add @size-limit/webpack plugin to Size Limit
# Installation command provided

# Global installation
npm install -g size-limit

# Usage from anywhere
cd /path/to/project
size-limit

# Or use npx for one-time execution
npx size-limit