tessl/npm-size-limit

CLI tool and programmatic API for performance budget monitoring that measures JavaScript bundle size and execution time with plugin support for webpack, esbuild, and various bundlers.

—

Pending

Overview

Eval results

Files

Configuration

Name: tessl/npm-size-limit
Author: tessl

Size Limit provides flexible configuration options supporting multiple formats, validation, and environment-specific setups.

Capabilities

Configuration Sources

Size Limit loads configuration from multiple sources with a defined priority order.

// Configuration priority (highest to lowest):
// 1. .size-limit.js (dynamic configuration with functions)
// 2. .size-limit.json (static JSON configuration)  
// 3. package.json "size-limit" field
// 4. Programmatic API configuration object

Check Configuration

Each size check is defined by a configuration object with multiple options.

interface Check {
  // Required
  path: string | string[];           // File paths or glob patterns
  
  // Limits
  limit?: string;                    // Size or time limit (e.g., "100 kB", "500 ms")
  
  // Identification
  name?: string;                     // Check name for multi-section configs
  
  // Compression
  brotli?: boolean;                  // Enable Brotli compression (default: true)
  gzip?: boolean;                    // Use Gzip instead of Brotli
  
  // Bundling
  webpack?: boolean;                 // Enable webpack bundling (default: true)
  config?: string;                   // Path to custom webpack/bundler config
  entry?: string | string[];         // Custom bundler entry points
  
  // Tree-shaking and Analysis
  import?: string | Record<string, string>; // Partial import testing
  ignore?: string[];                 // Files/dependencies to exclude
  
  // Time Measurement
  running?: boolean;                 // Enable execution time measurement (default: true)
  time?: TimeOptions;                // Time measurement configuration
  
  // Advanced Options
  module?: boolean;                  // Module-related option
  hidePassed?: boolean;              // Hide passed checks in output
  highlightLess?: boolean;           // Highlight improvements
  compareWith?: string;              // Path to stats.json for comparison
  uiReports?: object;               // Custom Statoscope UI reports
  disableModuleConcatenation?: boolean; // Disable webpack module concatenation
  
  // Configuration Modifiers (JS config only)
  modifyWebpackConfig?: (config: any) => any; // Webpack config modifier
  modifyEsbuildConfig?: (config: any) => any; // ESBuild config modifier
}

interface TimeOptions {
  networkSpeed?: string;    // Network speed (default: "50 kB")
  latency: string;         // Network latency simulation (default: "0")
  loadingMessage?: string; // Loading message (default: "on slow 3G")
}

type SizeLimitConfig = Check[];

Package.json Configuration

The most common configuration method using the package.json file.

Usage Examples:

{
  "name": "my-package",
  "size-limit": [
    {
      "path": "dist/bundle.js",
      "limit": "10 kB"
    }
  ]
}

{
  "size-limit": [
    {
      "name": "Main Bundle",
      "path": "dist/app.js",
      "limit": "100 kB",
      "webpack": true,
      "running": false
    },
    {
      "name": "Web Worker",
      "path": "dist/worker.js", 
      "limit": "50 kB",
      "webpack": false,
      "brotli": false,
      "gzip": true
    },
    {
      "name": "Library Export",
      "path": "dist/lib.js",
      "import": "{ createLibrary }",
      "limit": "25 kB"
    }
  ]
}

JSON Configuration File

Static configuration in a dedicated JSON file.

.size-limit.json:

[
  {
    "name": "Application Bundle",
    "path": ["dist/app.js", "dist/vendor.js"],
    "limit": "200 kB",
    "time": {
      "networkSpeed": "3G",
      "latency": "400ms",
      "loadingMessage": "on 3G connection"
    }
  },
  {
    "name": "Critical CSS",
    "path": "dist/critical.css",
    "limit": "5 kB",
    "webpack": false
  }
]

JavaScript Configuration File

Dynamic configuration with functions and environment variables.

.size-limit.js:

import { join } from 'node:path';

export default [
  {
    name: "Dynamic Bundle",
    path: process.env.NODE_ENV === 'production' 
      ? "dist/app.min.js" 
      : "dist/app.js",
    limit: process.env.SIZE_LIMIT || "100 kB",
    modifyWebpackConfig: (config) => {
      // Add custom webpack plugins
      config.plugins.push(new MyCustomPlugin());
      return config;
    }
  },
  {
    name: "Tree-shaking Test",
    path: "src/index.js",
    import: {
      "lodash": "{ debounce }",
      "./utils": "{ helper1, helper2 }"
    },
    limit: "15 kB"
  }
];

Path Configuration

File path specifications support various formats and patterns.

// Path formats
interface PathOptions {
  // Single file
  path: "dist/bundle.js";
  
  // Multiple files  
  path: ["dist/app.js", "dist/vendor.js"];
  
  // Glob patterns
  path: "dist/*.js";
  
  // Complex glob patterns
  path: ["dist/app-*.js", "!dist/app-test.js"];
  
  // Directory patterns
  path: "dist/**/*.js";
}

Path Examples:

{
  "size-limit": [
    {
      "name": "All JS files",
      "path": "dist/**/*.js",
      "limit": "500 kB"
    },
    {
      "name": "Specific files",
      "path": ["dist/main.js", "dist/polyfills.js"],
      "limit": "200 kB"
    },
    {
      "name": "Exclude test files",
      "path": ["src/**/*.js", "!src/**/*.test.js"],
      "limit": "300 kB"
    }
  ]
}

Limit Configuration

Size and time limits support various units and formats.

// Limit format examples
interface LimitOptions {
  // Size limits
  limit: "100 B";      // Bytes
  limit: "10 kB";      // Kilobytes  
  limit: "5 MB";       // Megabytes
  limit: "1.5 kB";     // Decimal values
  
  // Time limits
  limit: "500 ms";     // Milliseconds
  limit: "2 s";        // Seconds
  limit: "1.5 s";      // Decimal seconds
}

Limit Examples:

{
  "size-limit": [
    {
      "path": "dist/tiny-lib.js",
      "limit": "5 kB"
    },
    {
      "path": "dist/app.js", 
      "limit": "100 kB"
    },
    {
      "path": "dist/heavy-feature.js",
      "limit": "2 s",
      "time": {
        "networkSpeed": "slow 3G"
      }
    }
  ]
}

Import Testing Configuration

Tree-shaking and partial import testing configuration.

// Import testing formats
interface ImportOptions {
  // Single import
  import: "{ specificFunction }";
  
  // All exports
  import: "*";
  
  // Multiple files with specific imports
  import: {
    "library-name": "{ func1, func2 }",
    "./local-module": "{ helper }",
    "another-lib": "*"
  };
}

Import Examples:

{
  "size-limit": [
    {
      "name": "Lodash tree-shaking",
      "path": "src/index.js",
      "import": "{ debounce, throttle }",
      "limit": "10 kB"
    },
    {
      "name": "Full library import",
      "path": "src/heavy-usage.js", 
      "import": "*",
      "limit": "200 kB"
    },
    {
      "name": "Multi-library test",
      "path": "src/app.js",
      "import": {
        "react": "{ useState, useEffect }",
        "lodash": "{ map, filter }",
        "./utils": "*"
      },
      "limit": "150 kB"
    }
  ]
}

Environment-Specific Configuration

Configuration can adapt to different environments and build contexts.

// .size-limit.js with environment handling
const isDevelopment = process.env.NODE_ENV === 'development';
const isCI = process.env.CI === 'true';

export default [
  {
    name: "Main Bundle",
    path: isDevelopment ? "src/index.js" : "dist/bundle.js",
    limit: isDevelopment ? "200 kB" : "100 kB",
    webpack: !isDevelopment,
    running: !isCI, // Skip time measurement in CI
    time: isDevelopment ? undefined : {
      networkSpeed: "3G",
      latency: "400ms"
    }
  }
];

Validation and Error Handling

Size Limit validates configuration and provides helpful error messages.

// Configuration validation rules:
// - path is required and must be string or array of strings
// - limit must follow format: number + space + unit
// - entry must be string or array of strings  
// - Plugin-specific options validated against available plugins
// - Circular dependency detection
// - File existence validation

Common Configuration Errors:

// Invalid: missing path
{
  "size-limit": [
    {
      "limit": "10 kB"
    }
  ]
}

// Invalid: wrong limit format  
{
  "size-limit": [
    {
      "path": "dist/app.js",
      "limit": "10kb"  // Should be "10 kB"
    }
  ]
}

// Invalid: entry without webpack
{
  "size-limit": [
    {
      "path": "src/index.js",
      "entry": "custom-entry.js",
      "webpack": false
    }
  ]
}

Install with Tessl CLI