Bundle Analysis

Core functionality for analyzing JavaScript bundles through source maps, supporting multiple input formats and providing detailed size breakdowns.

Capabilities

Main Analysis Function

Analyzes bundle(s) and returns comprehensive exploration results with file size breakdowns.

/**
 * Analyze bundle(s) and return exploration results
 * @param bundlesAndFileTokens - Bundle input (file paths, globs, Bundle objects, or arrays)
 * @param options - Configuration options for analysis
 * @returns Promise resolving to analysis results
 */
function explore(
  bundlesAndFileTokens: BundlesAndFileTokens,
  options?: ExploreOptions
): Promise<ExploreResult>;

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

Usage Examples:

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

// Single file analysis
const result = await explore("dist/bundle.js");

// Multiple files using glob
const result = await explore("dist/*.js");

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

// Multiple bundles mixed formats
const result = await explore([
  "dist/main.js",
  { code: "dist/chunk.js", map: "dist/chunk.js.map" },
  "dist/vendor.*"
]);

// Using Buffer data
const codeBuffer = fs.readFileSync("bundle.js");
const result = await explore({ code: codeBuffer });

Bundle Processing

The main explore function handles all bundle processing internally, including:

• Converting file tokens and glob patterns to Bundle objects
• Processing multiple input formats (file paths, Buffer data, Bundle objects)
• Analyzing each bundle individually
• Collecting and formatting results

All bundle processing logic is encapsulated within the explore function and does not expose separate utility functions for external use.

Input Types

Bundle Interface

interface Bundle {
  /** JavaScript code as file path or Buffer */
  code: File;
  /** Optional source map as file path or Buffer */
  map?: File;
  /** Optional coverage ranges for heat map visualization */
  coverageRanges?: ColumnsRange[][];
}

type File = string | Buffer;

interface ColumnsRange {
  /** First column index (inclusive) */
  start: number;
  /** Last column index (inclusive) */
  end: number;
}

Input Patterns

Source Map Explorer supports flexible input patterns:

• File paths: "dist/bundle.js" - Looks for inline source map or bundle.js.map
• Glob patterns: "dist/*.js" - Processes all matching files
• Bundle objects: { code: "path.js", map: "path.js.map" } - Explicit source map
• Buffer data: { code: fs.readFileSync("bundle.js") } - In-memory analysis
• Mixed arrays: Arrays combining any of the above formats

Source Map Detection

The analysis engine automatically detects source maps through multiple methods:

1. Inline source maps: Embedded as data URLs in sourceMappingURL comments
2. External source maps: Referenced via sourceMappingURL comments pointing to .map files
3. Conventional naming: Automatically looks for filename.js.map when analyzing filename.js
4. Explicit specification: Use Bundle objects with explicit map property

Examples:

// Inline source map (automatically detected)
const result = await explore("bundle-with-inline-map.js");

// External source map (automatically found)
const result = await explore("bundle.js"); // Looks for bundle.js.map

// Explicit source map
const result = await explore({
  code: "bundle.js",
  map: "custom-map-name.map"
});

// No source map comment, but map file exists
const result = await explore({
  code: "no-comment.js",
  map: "no-comment.js.map"
});

Analysis Process

The bundle analysis follows these steps:

1. Input Processing: Convert file tokens and globs to Bundle objects
2. Source Map Loading: Detect and load source maps (inline or external)
3. Size Calculation: Calculate byte contributions for each original source file
4. Coverage Integration: Apply Chrome DevTools coverage data if provided
5. Path Processing: Clean and normalize file paths according to options
6. Result Compilation: Generate structured results with error handling

Performance Considerations

• Gzip Analysis: Setting gzip: true calculates compressed sizes but disables unmapped byte calculation
• Large Bundles: Bundle analysis scales with source map complexity, not just file size
• Memory Usage: Buffer inputs keep data in memory; use file paths for large bundles when possible
• Parallel Processing: Multiple bundles are analyzed concurrently for better performance