Size Limit

Performance budget tool for JavaScript. Measures the real minified and gzipped bundle size of your library or app, blocks CI when limits are exceeded, and posts an automated size delta comment on every pull request via the GitHub bot.

What is Size Limit?

Size Limit is an open-source tool created by Andrey Sitnik (the author of PostCSS and Nano ID) that brings performance budgets to JavaScript projects. It integrates into your build pipeline, measures each output file's real compressed size, and fails the process if any file exceeds its configured limit. This turns bundle size from a metric you check occasionally into a hard constraint enforced on every commit.

Unlike tools that just report file size on disk, Size Limit runs your output through a bundler, applies tree shaking, minifies the result, and compresses it — matching what a browser actually downloads. It also estimates JavaScript execution time on a slow 3G connection, surfacing the full performance cost of shipping more code.

Key Features

• Real bundle size measurement — runs bundler + minifier + gzip/brotli, not raw file size on disk
• Size budgets — define limits per output file in package.json or .size-limit.json; process fails when exceeded
• CI blocking — non-zero exit code on limit violation blocks merges in any CI pipeline
• Bundler integrations — presets for Webpack, Rollup, esbuild, and Vite; pick the bundler that matches your stack
• Execution time reporting — estimates JS parse and execution time impact on slow hardware
• Multiple entry points — measure core, full bundle, and framework bindings separately with individual limits
• Named export measurement — use the import field to measure the cost of importing just one function after tree shaking
• GitHub PR bot — the Size Limit Action posts a size delta table comment on every pull request automatically

Installation

# Install Size Limit and a preset for your bundler
npm add -D size-limit @size-limit/preset-small-lib

# Other common presets:
# @size-limit/preset-app          — for web apps (uses esbuild)
# @size-limit/preset-big-lib      — for larger libraries
# @size-limit/preset-small-lib    — for small libraries (no peer deps)

# Run Size Limit
npx size-limit

# Run with JSON output (useful for CI comparisons)
npx size-limit --json

Setting Up Size Budgets

Add a size-limit array to package.json with a path and limit per output file. Run npx size-limit after your build step.

// package.json — add a size-limit config section and a script
{
  "name": "my-ui-library",
  "version": "1.0.0",
  "scripts": {
    "build": "tsup src/index.ts",
    "size": "npm run build && size-limit",
    "analyze": "npm run build && size-limit --why"
  },
  "size-limit": [
    {
      "path": "dist/index.js",
      "limit": "10 kB"
    },
    {
      "path": "dist/index.esm.js",
      "limit": "10 kB"
    }
  ]
}

// Running: npm run size
//
// Package size: dist/index.js
//
//   Size limit:  10 kB
//   Size:         8.1 kB with all dependencies, minified and gzipped
//
//   Time limit:   50 ms
//   Time:         32 ms   on slow 3G
//
// Package size: dist/index.esm.js
//
//   Size limit:  10 kB
//   Size:         7.9 kB with all dependencies, minified and gzipped

Multiple Entry Points

Libraries with separate entry points can define individual limits for each. The import field lets you measure the tree-shaken cost of importing only a specific named export.

// size-limit config for a library with multiple entry points
// .size-limit.json
[
  {
    "name": "Core module",
    "path": "dist/core.js",
    "limit": "5 kB",
    "import": "{ createStore }"
  },
  {
    "name": "Full bundle",
    "path": "dist/index.js",
    "limit": "20 kB"
  },
  {
    "name": "React bindings",
    "path": "dist/react.js",
    "limit": "3 kB",
    "import": "{ useStore }",
    "peerDependencies": false
  }
]

// The "import" field measures the size of just that named export
// after tree shaking — useful for libraries that allow partial imports.

CI Integration and GitHub PR Bot

The Size Limit GitHub Action automatically builds both the base branch and the PR branch, compares sizes, and posts a comment table showing the delta for each entry point. No manual steps needed from developers — size changes are visible in every PR review.

# .github/workflows/size-limit.yml
# Uses the Size Limit Action to post a comment on every PR
# showing the bundle size delta (before vs after your changes).

name: Size Limit Check

on:
  pull_request:

jobs:
  size:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: npm
      - run: npm ci

      - name: Size Limit Report
        uses: andresz1/size-limit-action@v1
        with:
          github_token: secrets.GITHUB_TOKEN
          # The action builds your project, compares sizes to the base
          # branch, and posts a comment table like:
          #
          # | Path           | Size    | Change  | Limit  |
          # |----------------|---------|---------|--------|
          # | dist/index.js  | 8.1 kB  | +0.2 kB | 10 kB  | OK
          # | dist/react.js  | 2.8 kB  | -0.1 kB |  3 kB  | OK

Analyzing What's Inside

When Size Limit reports a size you do not expect, use --why to open an interactive bundle analyzer treemap showing which modules contribute most to the final size.

# Use --why to open a bundle analyzer and see what is inside
npm run build && npx size-limit --why

# Size Limit integrates with:
# - Webpack Bundle Analyzer (if using Webpack preset)
# - esbuild Bundle Analyzer (if using esbuild preset)
#
# This shows a treemap of every module contributing to the final bundle,
# helping you identify large dependencies worth replacing or lazy-loading.
#
# Common findings:
#   - date-fns pulling in all locales instead of just one
#   - lodash imported as a full bundle instead of individual methods
#   - a polyfill included unnecessarily for a modern target
#   - duplicate packages at different versions (e.g. two copies of React)

Size Limit vs Bundlephobia vs bundlesize

Pros and Cons