or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

cli-interface.mdconfiguration.mderror-handling.mdindex.mdplugin-system.mdprogrammatic-api.md
tile.json

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.

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/size-limit@11.2.x

To install, run

npx @tessl/cli install tessl/npm-size-limit@11.2.0

index.mddocs/

Size Limit

Size Limit is a comprehensive performance budget tool for JavaScript applications and libraries that monitors bundle size and execution time. It provides both a CLI tool for CI integration and a programmatic API for custom workflows, with a modular plugin architecture supporting webpack, esbuild, and other bundlers.

Package Information

  • Package Name: size-limit
  • Package Type: npm
  • Language: JavaScript (Node.js)
  • Installation: npm install --save-dev size-limit (requires plugins for functionality)

Core Imports

import sizeLimit from "size-limit";
import { processImport, SizeLimitError } from "size-limit";

Note: Size Limit is an ES module only package. CommonJS require() is not supported.

Basic Usage

CLI Tool

# Install with preset for typical use cases
npm install --save-dev @size-limit/preset-small-lib

# Or install specific plugins
npm install --save-dev size-limit @size-limit/file @size-limit/webpack

# Run size check
size-limit

# Run with specific config
size-limit --config .size-limit.json

# Watch mode for development
size-limit --watch

# JSON output for CI
size-limit --json

Programmatic API

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

// Basic usage with plugins
const results = await sizeLimit(
  [filePlugin, webpackPlugin],
  ["dist/bundle.js"]
);

console.log(results); // [{ size: 12345 }]

// With configuration object
const results = await sizeLimit(
  [filePlugin, webpackPlugin],
  {
    checks: [
      {
        path: ["dist/bundle.js"],
        limit: "10 kB"
      }
    ]
  }
);

Architecture

Size Limit is built around several key components:

  • Core API: Main sizeLimit() function for programmatic usage
  • CLI Tool: Command-line interface with argument parsing and reporting
  • Plugin System: Modular architecture with plugins for different bundlers and measurements
  • Configuration System: Flexible config loading from package.json, files, or programmatic objects
  • Reporter System: Output formatting for console, JSON, and CI integration

Capabilities

Programmatic API

Core programmatic interface for integrating Size Limit into custom workflows and build systems.

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

Programmatic API

CLI Interface

Command-line tool for running Size Limit checks in development and CI environments.

# Basic commands
size-limit [options]

# Key options
--json          # Output results in JSON format
--silent        # Silent mode (no console output)
--watch         # Watch mode for file changes
--why           # Bundle analysis mode
--clean-dir     # Clean bundle directory before analysis

CLI Interface

Configuration System

Flexible configuration system supporting multiple formats and validation options.

// Configuration object structure
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;                    // Gzip compression
  webpack?: boolean;                 // Enable webpack bundling
  config?: string;                   // Custom bundler config path
  entry?: string | string[];         // Bundler entry points
  import?: string | Record<string, string>; // Tree-shaking tests
  ignore?: string[];                 // Exclude patterns
  running?: boolean;                 // Execution time measurement
  time?: TimeOptions;                // Time measurement options
  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
}

type SizeLimitConfig = Check[];

Configuration

Plugin System

Modular plugin architecture for different bundlers, measurements, and analysis tools.

// Plugin interface (for plugin developers)
interface Plugin {
  name: string;
  before?(config: object, check: Check): Promise<void>;
  step0?(config: object, check: Check): Promise<void>;
  // ... step1 through step100
  finally?(config: object, check: Check): Promise<void>;
  wait0?: string;  // Progress message
  // ... wait1 through wait100
}

Plugin System

Error Handling

Structured error handling with specific error types and helpful messages.

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

Error Handling

Types

// Main API types
interface TimeOptions {
  networkSpeed?: string;    // Default: "50 kB"
  latency: string;         // Network latency simulation
  loadingMessage?: string; // Default: "on slow 3G"
}

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