or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

index.mdsource-map-consumption.mdsource-map-generation.mdsource-node-building.md
tile.json

tessl/npm-source-map

Generates and consumes source maps for debugging tools that map minified code back to original source code

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

To install, run

npx @tessl/cli install tessl/npm-source-map@0.7.0

index.mddocs/

Source Map

Source Map is a comprehensive JavaScript library for generating and consuming source maps, which are essential debugging tools that map minified or compiled code back to original source code. It provides both high-level APIs for building source maps incrementally during code generation and low-level APIs for direct manipulation and consumption of source map data.

Package Information

  • Package Name: source-map
  • Package Type: npm
  • Language: JavaScript with TypeScript definitions
  • Installation: npm install source-map
  • Browser Support: Yes (with WASM initialization)
  • Node.js Support: >= 12

Core Imports

ES Modules:

import { SourceMapGenerator, SourceMapConsumer, SourceNode } from "source-map";

CommonJS:

const { SourceMapGenerator, SourceMapConsumer, SourceNode } = require("source-map");

Basic Usage

Consuming a Source Map

import { SourceMapConsumer } from "source-map";

const rawSourceMap = {
  version: 3,
  file: "min.js",
  names: ["bar", "baz", "n"],
  sources: ["one.js", "two.js"],
  sourceRoot: "http://example.com/www/js/",
  mappings: "CAAC,IAAI,IAAM,SAAUA,GAClB,OAAOC,IAAID;CCDb,IAAI,IAAM,SAAUGE,GAClB,OAAOA"
};

// Use the auto-cleanup wrapper (recommended)
const result = await SourceMapConsumer.with(rawSourceMap, null, consumer => {
  // Find original position for generated code
  const originalPos = consumer.originalPositionFor({
    line: 2,
    column: 28
  });
  // Returns: { source: 'http://example.com/www/js/two.js', line: 2, column: 10, name: 'n' }
  
  return originalPos;
});

Generating a Source Map

import { SourceMapGenerator } from "source-map";

const map = new SourceMapGenerator({
  file: "source-mapped.js"
});

map.addMapping({
  generated: { line: 10, column: 35 },
  source: "foo.js", 
  original: { line: 33, column: 2 },
  name: "christopher"
});

console.log(map.toString());
// Outputs complete source map JSON

Building with SourceNode

import { SourceNode } from "source-map";

const node = new SourceNode(1, 0, "math.js", [
  "function add(a, b) {\n",
  new SourceNode(2, 2, "math.js", "return a + b;\n"),
  "}"
]);

const result = node.toStringWithSourceMap({
  file: "compiled.js"
});

console.log(result.code);    // Generated JavaScript
console.log(result.map.toString()); // Source map JSON

Google Chrome DevTools Integration

Source maps support an optional x_google_ignoreList field for marking third-party sources:

const sourceMapWithIgnoreList = {
  version: 3,
  sources: ["app.js", "vendor.js", "node_modules/lib.js"],
  names: [],
  mappings: "...",
  x_google_ignoreList: [1, 2]  // Mark vendor.js and lib.js as third-party
};

Architecture

Source Map is built around three main components:

  • SourceMapGenerator: Creates source maps incrementally during code generation, ideal for build tools and transpilers
  • SourceMapConsumer: Reads and queries existing source maps, perfect for debuggers and development tools
  • SourceNode: High-level API for building source maps through code concatenation and manipulation

The library supports both regular source maps and indexed source maps for large applications, with WASM-accelerated performance for fast position lookups in browser environments.

Browser Initialization

When using in browsers, initialize WASM before creating consumers:

import { SourceMapConsumer } from "source-map";

// Required for browser usage
SourceMapConsumer.initialize({
  "lib/mappings.wasm": "https://unpkg.com/source-map@0.7.6/lib/mappings.wasm"
});

// Now safe to use SourceMapConsumer

Error Handling

Source map operations can fail for various reasons. Handle errors appropriately:

try {
  const consumer = await new SourceMapConsumer(rawSourceMap);
  // Use consumer safely
  consumer.destroy();
} catch (error) {
  if (error.message.includes("Unsupported version")) {
    console.error("Source map version not supported (only v3 supported)");
  } else if (error.message.includes("lib/mappings.wasm")) {
    console.error("WASM not initialized for browser usage");
  } else if (error.message.includes("Invalid mapping")) {
    console.error("Source map contains invalid mapping data");
  } else {
    console.error("Failed to parse source map:", error.message);
  }
}

Common error scenarios:

  • Unsupported version: Only version 3 source maps are supported
  • WASM not initialized: Browser usage requires SourceMapConsumer.initialize()
  • Invalid format: Malformed JSON or missing required fields
  • Source not found: Requested source file not present in source map
  • Invalid positions: Line/column values outside valid ranges

Performance Considerations

Source map operations can be expensive for large files. Consider these optimizations:

  • Use SourceMapConsumer.with() for automatic resource cleanup
  • Enable column spans only when needed (increases memory usage)
  • Cache consumers for frequently accessed source maps
  • Batch position lookups instead of many individual calls
  • Use WASM in browsers for faster parsing and position lookups
// Good: Batch operations within consumer lifecycle
const results = await SourceMapConsumer.with(sourceMap, null, (consumer) => {
  return sourcePositions.map(pos => consumer.originalPositionFor(pos));
});

// Avoid: Creating multiple consumers for the same map
// This creates unnecessary overhead

Capabilities

Source Map Generation

Create source maps incrementally during code generation with full control over mappings and source content.

class SourceMapGenerator {
  constructor(args?: StartOfSourceMap);
  static fromSourceMap(sourceMapConsumer: SourceMapConsumer): SourceMapGenerator;
  addMapping(mapping: Mapping): void;
  setSourceContent(sourceFile: string, sourceContent: string): void;
  applySourceMap(
    sourceMapConsumer: SourceMapConsumer,
    sourceFile?: string,
    sourceMapPath?: string
  ): void;
  toString(): string;
  toJSON(): RawSourceMap;
}

interface StartOfSourceMap {
  file?: string;
  sourceRoot?: string;
  skipValidation?: boolean;
}

interface Mapping {
  generated: Position;
  original: Position;
  source: string;
  name?: string;
}

Source Map Generation

Source Map Consumption

Read and query existing source maps with bidirectional position mapping and source content access.

interface SourceMapConsumerConstructor {
  new (
    rawSourceMap: RawSourceMap | RawIndexMap | string,
    sourceMapUrl?: SourceMapUrl
  ): Promise<BasicSourceMapConsumer | IndexedSourceMapConsumer>;
  
  // Static constants
  readonly GENERATED_ORDER: 1;
  readonly ORIGINAL_ORDER: 2;
  readonly GREATEST_LOWER_BOUND: 1;
  readonly LEAST_UPPER_BOUND: 2;
  
  initialize(mappings: SourceMappings): void;
  fromSourceMap(
    sourceMap: SourceMapGenerator,
    sourceMapUrl?: SourceMapUrl
  ): Promise<BasicSourceMapConsumer>;
  with<T>(
    rawSourceMap: RawSourceMap | RawIndexMap | string,
    sourceMapUrl: SourceMapUrl | null | undefined,
    callback: (consumer: BasicSourceMapConsumer | IndexedSourceMapConsumer) => Promise<T> | T
  ): Promise<T>;
}

interface SourceMapConsumer {
  computeColumnSpans(): void;
  originalPositionFor(
    generatedPosition: Position & { bias?: number }
  ): NullableMappedPosition;
  generatedPositionFor(
    originalPosition: MappedPosition & { bias?: number }
  ): NullablePosition;
  allGeneratedPositionsFor(
    originalPosition: MappedPosition
  ): NullablePosition[];
  hasContentsOfAllSources(): boolean;
  sourceContentFor(source: string, returnNullOnMissing?: boolean): string | null;
  eachMapping(
    callback: (mapping: MappingItem) => void,
    context?: any,
    order?: number
  ): void;
  destroy(): void;
}

Source Map Consumption

Source Node Building

Build source maps through code concatenation and manipulation with a high-level fluent API.

class SourceNode {
  constructor(
    line?: number | null,
    column?: number | null,
    source?: string | null,
    chunks?: Array<string | SourceNode> | SourceNode | string,
    name?: string
  );
  
  static fromStringWithSourceMap(
    code: string,
    sourceMapConsumer: SourceMapConsumer,
    relativePath?: string
  ): SourceNode;
  
  add(chunk: Array<string | SourceNode> | SourceNode | string): SourceNode;
  prepend(chunk: Array<string | SourceNode> | SourceNode | string): SourceNode;
  setSourceContent(sourceFile: string, sourceContent: string): void;
  walk(fn: (chunk: string, mapping: MappedPosition) => void): void;
  walkSourceContents(fn: (file: string, content: string) => void): void;
  join(sep: string): SourceNode;
  replaceRight(pattern: string, replacement: string): SourceNode;
  toString(): string;
  toStringWithSourceMap(startOfSourceMap?: StartOfSourceMap): CodeWithSourceMap;
}

Source Node Building

Core Types

type SourceMapUrl = string;

interface Position {
  line: number;
  column: number;
}

interface NullablePosition {
  line: number | null;
  column: number | null;
  lastColumn: number | null;
}

interface MappedPosition {
  source: string;
  line: number;
  column: number;
  name?: string;
}

interface NullableMappedPosition {
  source: string | null;
  line: number | null;
  column: number | null;
  name: string | null;
}

interface RawSourceMap {
  version: number;
  sources: string[];
  names: string[];
  sourceRoot?: string;
  sourcesContent?: string[];
  mappings: string;
  file: string;
  x_google_ignoreList?: number[];
}

interface RawIndexMap extends StartOfSourceMap {
  version: number;
  sections: RawSection[];
}

interface RawSection {
  offset: Position;
  map: RawSourceMap;
}

interface MappingItem {
  source: string;
  generatedLine: number;
  generatedColumn: number;
  lastGeneratedColumn: number | null;
  originalLine: number;
  originalColumn: number;
  name: string;
}

interface CodeWithSourceMap {
  code: string;
  map: SourceMapGenerator;
}

interface SourceMappings {
  "lib/mappings.wasm": SourceMapUrl | ArrayBuffer;
}