mozilla / mozilla/source-map

allow wasm to be bundled

Open
#527 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
JavaScript
Stars
3.7k
Forks
370
PR merge metrics
No merged PRs in 30d

Description

Support bundlers (esbuild, webpack) without requiring internal module swaps for WASM loading

Problem

When bundling source-map with esbuild (platform: node), the WASM loading breaks in production because:

  1. read-wasm.js uses path.join(__dirname, "mappings.wasm") — but after bundling, __dirname points to the output directory, not node_modules/source-map/lib/
  2. initialize() is a no-op in the Node version (read-wasm.js), so there's no way to provide the WASM from the consumer side without swapping to read-wasm-browser.js via a bundler resolve plugin
  3. The "browser" field in package.json maps read-wasm.jsread-wasm-browser.js, but esbuild with platform: node (correctly) ignores browser fields

This forces users to either:

  • Copy mappings.wasm to their output directory with the exact filename (fragile, undocumented contract)
  • Use a resolve plugin to swap read-wasm.jsread-wasm-browser.js and manually call initialize() (depends on internal file paths)

Proposal

Make initialize() work regardless of platform — if the user provides WASM via initialize(), use it; otherwise fall back to the fs.readFile(__dirname) approach. This is essentially making the Node read-wasm.js behave like:

let initialized = null;

module.exports = function readWasm() {
  if (initialized) return Promise.resolve(initialized);
  // existing fs.readFile fallback
  return new Promise((resolve, reject) => {
    const wasmPath = path.join(__dirname, "mappings.wasm");
    fs.readFile(wasmPath, null, (error, data) => {
      if (error) reject(error);
      else resolve(data.buffer);
    });
  });
};

module.exports.initialize = function (input) {
  initialized = input;
};

This way bundler users can call SourceMapConsumer.initialize({"lib/mappings.wasm": wasmBuffer}) on Node without needing to swap modules.

Alternatives considered

  • Exporting mappings.wasm via package.json "exports" so bundlers can resolve it cleanly
  • Shipping a pre-built JS fallback (like source-map-js does — no WASM at all)

Environment

  • source-map 0.7.6
  • esbuild 0.28.x, platform: node, format: esm
  • Node.js 24.x
  • Deploying to Docker (only dist/ is copied — no node_modules)

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start with read-wasm.js, read-wasm-browser.js, package.json, and the SourceMapConsumer.initialize entry point to understand the current Node fallback and browser mapping. Verify that a bundled Node consumer can provide the WASM through initialize without swapping modules, while the existing mappings.wasm fallback still works when no input is provided.

Written by the indexing model from the issue text.

Assessment

Tech stack
javascript, node.js, wasm
Domain
build-system, tooling
Issue type
Feature
Difficulty
4/5
Estimated time
3-5 days
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
55/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.