webpack-sources

3.4.0 verified Sat Apr 25 auth: no javascript

Provides base and concrete Source classes for representing source code with optional source maps, used primarily by webpack. Current stable version is 3.4.0, released in 2025-01-06. The package is actively maintained as part of webpack ecosystem. Key classes include RawSource, OriginalSource, SourceMapSource, ConcatSource, CachedSource, and PrefixSource. Differentiators: designed for webpack's compilation pipeline, supports efficient buffer operations (buffer/buffers), hash computation, and identity mappings for source maps. It ships TypeScript types and works with Node 10.13+.

Common errors

error TypeError: (intermediate value).source is not a function ↓

cause Trying to call .source() on a source object that is actually a string or a raw module object from webpack compilation

fix

Verify the object is an instance of a Source class: if (source instanceof Source) { source.source(); }

error Cannot read properties of undefined (reading 'source') ↓

cause Accessing .source() on a source that is undefined or null, often from webpack compilation.

fix

Check that the source is defined before calling methods: if (source) { source.source(); }

error The 'sourceMap' property must be an object, string, or Buffer ↓

cause Passing an invalid type for the sourceMap parameter to SourceMapSource constructor (e.g., number or boolean).

fix

Ensure sourceMap is a valid SourceMap object (with version, sources, mappings), a JSON string, or a Buffer.

Warnings

breaking Source.prototype.buffer() returns Buffer, not string ↓

fix Use .source() if you need a string, or .buffer() for Buffer. Note that .buffer() returns a Buffer, which is not implicitly convertible to string.

breaking ConcatSource.add() no longer accepts array; use multiple calls or spread ↓

fix Replace .add([source1, source2]) with separate .add(source1).add(source2) calls.

deprecated Source.prototype.size() returns number, but may not be accurate for all source types ↓

fix Use .size() for estimate; for exact byte length, convert to Buffer and check .length.

gotcha OriginalSource may not produce column mappings if source code is short or has few statement boundaries ↓

fix Consider using SourceMapSource with explicit source map if column mapping is critical.

gotcha SourceMapSource identity mapping only works when original source matches generated source for that mapping segment ↓

fix Ensure provided source map has consistent mappings; otherwise identity assumption may produce incorrect map.

Install

npm install webpack-sources

yarn add webpack-sources

pnpm add webpack-sources

Imports

RawSource

wrong

const RawSource = require('webpack-sources').RawSource

correct

import { RawSource } from 'webpack-sources'

ESM and CJS both supported; named import preferred. Note the plural 'sources'.

OriginalSource
```
import { OriginalSource } from 'webpack-sources'
```
Used to represent original source code with name.
SourceMapSource
```
import { SourceMapSource } from 'webpack-sources'
```
For source code with existing source map.
ConcatSource
wrong
```
import { ConcatSource } from 'webpack'
```
correct
```
import { ConcatSource } from 'webpack-sources'
```
ConcatSource is part of webpack-sources, not directly from webpack package.
CachedSource
```
import { CachedSource } from 'webpack-sources'
```
Caches source/map/hash for repeated access.
PrefixSource
```
import { PrefixSource } from 'webpack-sources'
```
Prepends a string to the wrapped source.
ReplaceSource
```
import { ReplaceSource } from 'webpack-sources'
```
Allows targeted replacements in the source.

Quickstart

Demonstrates creating various Source types (RawSource, ConcatSource, OriginalSource, SourceMapSource, CachedSource) and accessing their source, size, and map methods.

import { RawSource, ConcatSource, OriginalSource, SourceMapSource } from 'webpack-sources';
import { SourceNode } from 'source-map';  // for demonstration

// Create a simple RawSource
const raw = new RawSource('console.log("hello world");');
console.log('source:', raw.source());
console.log('size:', raw.size());

// Concat multiple sources
const concat = new ConcatSource();
concat.add(new RawSource('var x = 1;\n'));
concat.add(new OriginalSource('var y = 2;\n', 'file2.js'));
console.log('concat source:', concat.source());

// SourceMapSource with identity mapping
const rawSource = 'var a = 1;';
const sourceMap = {
  version: 3,
  file: 'file.js',
  sources: ['file.js'],
  mappings: 'AAAA',
  names: [],
  sourcesContent: [rawSource]
};
const sms = new SourceMapSource(rawSource, 'file.js', sourceMap);
console.log('map:', sms.map());

// CachedSource for repeated reads
import { CachedSource } from 'webpack-sources';
const cached = new CachedSource(raw);
console.log('cached source:', cached.source());  // identical to raw