or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

analysis-results.mdbundle-analysis.mdconfiguration.mderror-handling.mdindex.md
tile.json

tessl/npm-source-map-explorer

Analyze and debug space usage through source maps

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/source-map-explorer@2.5.x

To install, run

npx @tessl/cli install tessl/npm-source-map-explorer@2.5.0

index.mddocs/

Source Map Explorer

Source Map Explorer is a TypeScript library and command-line tool for analyzing JavaScript bundle size and composition through source maps. It creates interactive treemap visualizations that help developers understand which files and dependencies contribute most to their minified bundle size, enabling effective debugging of code bloat and optimization opportunities.

Package Information

  • Package Name: source-map-explorer
  • Package Type: npm
  • Language: TypeScript
  • Installation: npm install source-map-explorer
  • CLI Installation: npm install -g source-map-explorer

Core Imports

import { explore } from "source-map-explorer";
// or
import explore from "source-map-explorer";

For CommonJS:

const { explore } = require("source-map-explorer");
// or
const explore = require("source-map-explorer").default;

Basic Usage

import { explore } from "source-map-explorer";

// Analyze a single bundle
const result = await explore("dist/bundle.js");

// Analyze bundle with explicit source map
const result = await explore({
  code: "dist/bundle.js",
  map: "dist/bundle.js.map"
});

// Analyze with options
const result = await explore("dist/bundle.js", {
  output: { format: "json" },
  onlyMapped: true
});

console.log(result.bundles[0].files);
// {
//   "src/main.js": { size: 2543 },
//   "node_modules/lodash/index.js": { size: 15234 },
//   "[unmapped]": { size: 156 }
// }

Architecture

Source Map Explorer is built around several key components:

  • Core Analysis Engine: Parses source maps and calculates file size contributions
  • Bundle Processing: Handles multiple input formats (files, globs, buffers) and source map detection
  • Output Formatters: Generates HTML treemaps, JSON data, and TSV reports
  • CLI Interface: Command-line tool with extensive options for automation and CI/CD integration
  • Coverage Integration: Chrome DevTools coverage support for heat map visualizations
  • Error Handling: Comprehensive error reporting for source map issues and validation

Capabilities

Bundle Analysis

Core functionality for analyzing JavaScript bundles through source maps. Supports single files, glob patterns, and programmatic buffer inputs.

function explore(
  bundlesAndFileTokens: BundlesAndFileTokens,
  options?: ExploreOptions
): Promise<ExploreResult>;

type BundlesAndFileTokens = (Bundle | string)[] | Bundle | string;

interface Bundle {
  code: File;
  map?: File;
  coverageRanges?: ColumnsRange[][];
}

type File = string | Buffer;

Bundle Analysis

Configuration Options

Comprehensive configuration system for customizing analysis behavior, output formats, and visualization options.

interface ExploreOptions {
  onlyMapped?: boolean;
  excludeSourceMapComment?: boolean;
  output?: {
    format: 'json' | 'tsv' | 'html';
    filename?: string;
  };
  noRoot?: boolean;
  noBorderChecks?: boolean;
  replaceMap?: Record<string, string>;
  coverage?: string;
  gzip?: boolean;
  sort?: boolean;
}

Configuration Options

Analysis Results

Structured data format for bundle analysis results, including file size breakdowns, error handling, and formatted output.

interface ExploreResult {
  bundles: ExploreBundleResult[];
  output?: string;
  errors: ExploreErrorResult[];
}

interface ExploreBundleResult {
  bundleName: string;
  files: Record<string, FileData>;
  mappedBytes: number;
  unmappedBytes?: number;
  eolBytes: number;
  sourceMapCommentBytes: number;
  totalBytes: number;
}

Analysis Results

Error Handling

Comprehensive error system with specific error codes for different failure scenarios and validation issues.

class AppError extends Error {
  code?: ErrorCode;
  cause?: Error;
}

type ErrorCode = 
  | 'NoBundles'
  | 'NoSourceMap'
  | 'OneSourceSourceMap'
  | 'UnmappedBytes'
  | 'InvalidMappingLine'
  | 'InvalidMappingColumn'
  | 'CannotSaveFile'
  | 'CannotCreateTempFile'
  | 'CannotOpenTempFile'
  | 'CannotOpenCoverageFile'
  | 'NoCoverageMatches';

Error Handling

Constants

// Special file keys used in analysis results
const UNMAPPED_KEY = "[unmapped]";
const SOURCE_MAP_COMMENT_KEY = "[sourceMappingURL]";
const NO_SOURCE_KEY = "[no source]";
const EOL_KEY = "[EOLs]";

Command Line Interface

The package provides both source-map-explorer and sme commands for command-line usage:

# Basic usage
source-map-explorer bundle.js

# Multiple bundles
source-map-explorer dist/*.js

# Output formats
source-map-explorer bundle.js --json result.json
source-map-explorer bundle.js --html result.html
source-map-explorer bundle.js --tsv result.tsv

# Options
source-map-explorer bundle.js --only-mapped --gzip --sort

The CLI supports all programmatic options through command-line flags and provides the same analysis capabilities as the programmatic API.