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

Programmatic API

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

The Size Limit programmatic API provides functions for integrating performance budget checks into custom workflows, build systems, and automated testing.

Capabilities

Main API Function

The core function for running Size Limit programmatically with plugins and configuration.

/**
 * Run Size Limit and return measurement results
 * @param plugins - Array of Size Limit plugins (e.g., @size-limit/webpack, @size-limit/file)
 * @param files - File paths array or configuration object
 * @returns Promise resolving to array of measurement results
 */
function sizeLimit(
  plugins: Function[],
  files: string[] | object
): Promise<SizeLimitResult[]>;

interface SizeLimitResult {
  size?: number;      // Bundle size in bytes
  time?: number;      // Total execution time in ms
  runTime?: number;   // JavaScript execution time in ms
  loadTime?: number;  // Loading time including network in ms
}

Usage Examples:

import sizeLimit from "size-limit";
import filePlugin from "@size-limit/file";
import webpackPlugin from "@size-limit/webpack";
import timePlugin from "@size-limit/time";

// Basic file size measurement
const results = await sizeLimit([filePlugin], ["dist/bundle.js"]);
console.log(results); // [{ size: 12345 }]

// With bundling and time measurement
const results = await sizeLimit(
  [webpackPlugin, timePlugin, filePlugin],
  ["src/index.js"]
);
console.log(results);
// [{ size: 12345, time: 1500, runTime: 250, loadTime: 1250 }]

// Multiple files
const results = await sizeLimit(
  [filePlugin],
  ["dist/main.js", "dist/vendor.js"]
);
console.log(results);
// [{ size: 8000 }, { size: 4345 }]

Configuration Object Format

When passing a configuration object instead of a simple file array:

// Configuration object structure
interface SizeLimitConfig {
  checks: Check[];
}

interface Check {
  path: string | string[];           // File paths (required)
  limit?: string;                    // Size/time limit
  name?: string;                     // Check name
  brotli?: boolean;                  // Brotli compression (default: true)
  gzip?: boolean;                    // Use Gzip instead of Brotli
  webpack?: boolean;                 // Enable webpack bundling
  config?: string;                   // Path to custom bundler config
  entry?: string | string[];         // Bundler entry points
  import?: string | Record<string, string>; // Tree-shaking import tests
  ignore?: string[];                 // Files/dependencies to exclude
  running?: boolean;                 // Enable execution time measurement
  time?: TimeOptions;                // Time measurement configuration
  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
  module?: boolean;                  // Module-related option
  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")
}

Usage Examples:

// Advanced configuration
const results = await sizeLimit(
  [webpackPlugin, timePlugin, filePlugin],
  {
    checks: [
      {
        path: ["src/app.js"],
        limit: "100 kB",
        name: "Main Bundle",
        webpack: true,
        time: {
          networkSpeed: "3G",
          latency: "400ms",
          loadingMessage: "on 3G connection"
        }
      },
      {
        path: ["src/worker.js"],
        limit: "50 kB",
        name: "Web Worker",
        brotli: false,
        gzip: true
      }
    ]
  }
);

Import Processing Utility

Utility function for handling import statements in tree-shaking analysis.

/**
 * Process import configuration and create temporary entry files
 * @param check - Check configuration object with import property
 * @param output - Output directory for generated entry files
 * @returns Promise that resolves when processing is complete
 */
async function processImport(check: Check, output: string): Promise<void>;

Usage Examples:

import { processImport } from "size-limit";

// Tree-shaking test configuration
const check = {
  path: ["src/index.js"],
  import: {
    "my-library": "{ specificFunction }",
    "another-lib": "*"
  }
};

// Process imports and generate entry files
await processImport(check, "./temp-output");
// Creates entry files testing specific imports

Error Handling

Size Limit provides structured error handling for configuration and runtime issues.

class SizeLimitError extends Error {
  constructor(type: string, ...args: any[]);
  name: "SizeLimitError";
  example?: string;  // Configuration example for setup errors
}

Common Error Types:

import { SizeLimitError } from "size-limit";

try {
  const results = await sizeLimit([filePlugin], []);
} catch (error) {
  if (error instanceof SizeLimitError) {
    console.error(`Size Limit Error: ${error.message}`);
    if (error.example) {
      console.log("Example configuration:", error.example);
    }
  }
}

Plugin Integration

The programmatic API requires plugins to be explicitly provided:

Available Official Plugins:

@size-limit/file - Basic file size measurement
@size-limit/webpack - Webpack bundling and analysis
@size-limit/esbuild - ESBuild bundling
@size-limit/time - Execution time measurement in browser
@size-limit/webpack-css - CSS support for webpack
@size-limit/webpack-why - Bundle analysis and visualization
@size-limit/esbuild-why - ESBuild bundle analysis

Plugin Loading Example:

import sizeLimit from "size-limit";

// Dynamic plugin loading
const plugins = [];
if (needsBundling) {
  const webpackPlugin = await import("@size-limit/webpack");
  plugins.push(webpackPlugin.default);
}
if (needsTiming) {
  const timePlugin = await import("@size-limit/time");
  plugins.push(timePlugin.default);
}

// Always include file plugin for size measurement
const filePlugin = await import("@size-limit/file");
plugins.push(filePlugin.default);

const results = await sizeLimit(plugins, files);

Install with Tessl CLI