sls-bundle-analyser

CLI tool for analysing Lambda bundle sizes in Serverless Framework projects. It parses serverless*.yml files to discover handler entry points, bundles them with esbuild, and reports on size changes between branches.

To get started, run npx @tomnieuwland/sls-bundle-analyser sizes in the root of your project.

Commands

sls-bundle-analyser compare

Compares bundle sizes between the current branch and a base branch. Builds a dependency graph to determine which functions are affected by code changes, then reports size deltas.

The baseline is the merge-base (the point where the current branch diverged from the base branch), not the current tip of the base branch. This measures only the effect of this branch's own changes when merged, so it stays accurate even when the base branch moves ahead and touches the same files. In CI, fetch full history (e.g. actions/checkout with fetch-depth: 0) so the merge-base is reachable — otherwise the command fails with a clear error rather than reporting misleading deltas.

| Flag | Description | | ---------------------- | ------------------------------------------------------------------------------- | | --base <branch> | Base branch to compare against, using its merge-base with the current branch (default: from config or main) | | --all | Analyze all functions, not just those affected by changes | | --verbose | Show per-module breakdown for each function | | --json | Output raw JSON instead of a text table | | --threshold <bytes> | Only show functions with delta above this threshold | | --fail-above <bytes> | Exit with code 1 if any function grew more than this many bytes (useful for CI) | | --include-zero-delta | Include functions whose total bundle size did not change |

sls-bundle-analyser sizes

Bundles all discovered functions and reports their sizes. No branch comparison — just a snapshot of current bundle sizes.

| Flag | Description | | ---------------- | ----------------------------------------------------- | | --json | Output raw JSON | | --sort <field> | Sort order: size (default, largest first) or name |

sls-bundle-analyser visualize <entry-point>

Generates an interactive treemap (or sunburst/network diagram) for a single handler's bundle and opens it in the browser.

| Flag | Description | | ------------------- | ---------------------------------------------------------------------------- | | --template <type> | Visualization type: treemap, sunburst, or network (default: treemap) | | --no-third-party | Exclude node_modules from the visualization | | --no-open | Generate the file without opening it in the browser | | --top <n> | Show only the N largest modules | | --output <path> | Write HTML to this path instead of opening in the browser | | --diff | Generate side-by-side visualizations comparing current branch against the base merge-base | | --base <branch> | Base branch for --diff, compared at its merge-base (default: from config or main) |

sls-bundle-analyser shared-modules

Analyses which node_modules packages are bundled across multiple Lambda functions, helping identify candidates for a shared layer.

| Flag | Description | | ----------- | ------------------------------------------- | | --json | Output raw JSON instead of a text table | | --top <n> | Show only the top N modules (default: 20) |

Configuration

Configuration is loaded from the service directory (the directory you run the tool from). The tool checks two locations in order:

1. .bundle-analyser.json — a standalone config file in the service directory
2. package.json — a "bundle-analyser" key at the top level

If neither is found, defaults are used. All fields are optional.

{
  "exclude": ["serverless.local-*.yml"],
  "base": "main",
  "esbuild": {}
}

Fields

| Field | Type | Default | Description | | --------- | ---------- | ---------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | exclude | string[] | ["serverless.local-*.yml"] | Glob patterns for serverless*.yml files to skip. Useful for ignoring local dev overrides. | | base | string | "main" | Default base branch for the compare and visualize --diff commands. Can be overridden per-invocation with --base. | | esbuild | object | {} | esbuild BuildOptions overrides merged on top of the built-in defaults (bundle, minify, platform: "node", target: "node20", cjs). |

Example in package.json

{
  "name": "my-service",
  "bundle-analyser": {
    "base": "develop",
    "exclude": ["serverless.local-*.yml", "serverless.test.yml"],
    "esbuild": {
      "external": ["aws-sdk"]
    }
  }
}

Examples

# Compare affected functions against main
sls-bundle-analyser compare

# Compare all functions against a specific branch
sls-bundle-analyser compare --all --base feature-branch

# CI gate: fail if any function grew by more than 50KB
sls-bundle-analyser compare --all --fail-above 51200

# JSON output for scripting
sls-bundle-analyser compare --all --json

# Report all bundle sizes (no comparison)
sls-bundle-analyser sizes

# Bundle sizes sorted alphabetically, as JSON
sls-bundle-analyser sizes --sort name --json

# Visualize a single handler
sls-bundle-analyser visualize src/handlers/someHandler.ts

# Visualize only first-party code, top 10 modules, save to file
sls-bundle-analyser visualize src/handlers/someHandler.ts --no-third-party --top 10 --output report.html

# Side-by-side diff visualization against main
sls-bundle-analyser visualize src/handlers/someHandler.ts --diff

# Find most widely shared node_modules packages
sls-bundle-analyser shared-modules --top 10