@stackline/inline-source-map

Maintained inline-source-map-compatible generator for Node.js, TypeScript, CommonJS, ESM, and browser bundles.

Documentation | npm | Issues | Repository

Current package version: 1.0.4

Why this package?

A maintained, typed, inline-source-map-compatible generator for modern Node.js and browser build pipelines.

inline-source-map remains embedded in build tools and transpilers, but its published package still targets an old source-map generator and its upstream test workflow does not exercise modern Node.js releases.

This fork preserves the compact CommonJS API while adding:

• current source-map generation through [email protected];
• CommonJS, Node ESM, TypeScript, and browser-bundle verification;
• TypeScript declarations without changing the JavaScript call shape;
• null-prototype storage for source file names such as __proto__;
• UTF-8 base64 encoding in browsers with no global Buffer;
• reproducible package, compatibility, coverage, and install tests;
• preserved MIT attribution to the original project.

No runtime security advisory is claimed for the upstream package. This fork is about maintained compatibility, modern verification, and defensive defaults.

Trust and maintenance

• Every release is built from the public repository.
• CI validates runtime compatibility, types, package exports, and clean installs.
• Security reports use the private process in SECURITY.md.
• License and upstream attribution remain in LICENSE, NOTICE, and THIRD_PARTY_LICENSES.md.

Provenance

This is an independent maintained fork of Thorsten Lorenz's MIT-licensed inline-source-map. The original copyright and license text are preserved in LICENSE, with additional attribution in NOTICE.

Compatibility

| Item | Value | | --- | --- | | Package | @stackline/[email protected] | | Node.js runtime | >=12 | | CommonJS / primary entry | ./index.js | | Type declarations | ./index.d.ts |

Compatibility at a glance

| Item | Value | | :--- | :--- | | Package | @stackline/[email protected] | | API baseline | [email protected] | | Runtime | Node.js 12+, browser bundles | | Modules | Callable CommonJS with Node ESM default import | | Types | First-party TypeScript declarations | | Runtime dependencies | One maintained source-map generator |

The JavaScript runtime supports Node.js 12 and newer. Development tooling uses Node.js 20.19 or newer. See COMPATIBILITY_CONTRACT.md for the exact preserved behaviors and MIGRATION.md for alias installation.

Installation

Install under the public Stackline name:

npm install @stackline/inline-source-map

Or replace the original package without changing imports:

npm install inline-source-map@npm:@stackline/inline-source-map

Usage

Existing CommonJS remains unchanged:

const inlineSourceMap = require('inline-source-map');

Quick start

const inlineSourceMap = require('@stackline/inline-source-map');

const source = [
  'const answer = 42;',
  'console.log(answer);'
].join('\n');

const map = inlineSourceMap({ file: 'bundle.js' })
  .addGeneratedMappings('answer.js', source)
  .addSourceContent('answer.js', source);

const output = source + '\n' + map.inlineMappingUrl();

ESM

Node.js exposes the callable CommonJS export as the default import:

import inlineSourceMap from '@stackline/inline-source-map';

const map = inlineSourceMap().addGeneratedMappings('input.js', 'let x = 1;');

The package intentionally retains one CommonJS implementation instead of shipping divergent ESM and CommonJS code paths.

Features and Integrations

TypeScript

The package includes declarations for the callable export and Generator:

import inlineSourceMap = require('@stackline/inline-source-map');

const generator: inlineSourceMap.Generator = inlineSourceMap({
  file: 'bundle.js'
});

Browser bundles

Bundle the package with Browserify, esbuild, Rollup, Vite, or webpack. The package's browser field selects a prebuilt CommonJS entry that contains only the generator path and uses the browser's global URL. The base64 path uses Buffer when available and standard TextEncoder plus btoa in browsers. No browser global is installed by the package.

Security

Review inputs and the package-specific compatibility limits before processing untrusted data. Report suspected vulnerabilities as described in the security policy.

API Surface

API

inlineSourceMap(options?)

Creates a Generator. Supported options are file, sourceRoot, and charset. The default charset label is utf-8.

generator.addGeneratedMappings(sourceFile, source, offset?)

Adds an identity mapping for every source line. As in the original package, line and column offsets are applied to every generated mapping.

generator.addMappings(sourceFile, mappings, offset?)

Adds supplied generated/original positions. A mapping without original produces a generated-only source-map segment.

generator.addSourceContent(sourceFile, sourceContent)

Embeds source text. File names are stored in a null-prototype dictionary, so special JavaScript object names are handled as ordinary source names.

Output methods

• toJSON() returns the version 3 source-map object;
• toString() returns its compact JSON representation;
• base64Encode() returns the UTF-8 JSON as base64;
• inlineMappingUrl() returns the complete //# sourceMappingURL=... comment;
• gen() returns the underlying SourceMapGenerator.

_mappings() is retained for compatibility and returns a diagnostic snapshot. Code should prefer toJSON() because underscore-prefixed internals are not a stable extension point in the underlying source-map project.

Local Development

git clone https://github.com/alexandroit/stackline-inline-source-map.git
cd stackline-inline-source-map
npm ci
npm run test

Release tooling uses Node.js 24.20.0 and npm 11.19.0. The consumer runtime contract remains the one documented above.

Consumer Smoke Test

Run the repository's existing consumer/package check after installing development dependencies:

npm run test:install

Release Checklist

Release evidence

The release gate verifies:

• 14 focused regression tests;
• five differential compatibility scenarios against [email protected];
• 100% line, statement, and function coverage;
• Node.js 12, 14, 16, 18, 20, 22, and 24;
• TypeScript 3.9, 4.7, 4.9, 5.9, 6.0, and 7.0;
• CommonJS, ESM, browser, packed install, publint, and type export checks.

The interactive documentation playground runs the production browser bundle and exposes the generated Source Map v3 JSON.

Run npm run test and inspect the package contents before release. Publish a new version through the GitHub Actions publishing workflow, using the SHA-512 digest of the reviewed tarball. Verify the exact published version, tarball integrity, and npm provenance after the run.

License

MIT. See the license for the complete terms.

Original authorship and third-party attribution are preserved in NOTICE.

Credits and original authors

• Original project: inline-source-map.
• Alexandro Paixao Marques.
• Copyright 2013 Thorsten Lorenz.
• Copyright (c) 2026 Alexandro Paixao Marques and contributors.
• Stackline maintenance: Alexandro Paixao Marques and Stackline contributors.

Original copyright, license notices and contributor acknowledgements remain part of this distribution. Stackline maintenance does not replace authorship of the original work.

Community and Links

• Stackline website
• GitHub projects
• npm packages
• Reddit community — r/Stackline
• Maintainer LinkedIn

Use this repository's issue tracker for reproducible bugs and feature requests. Join r/Stackline for examples, usage questions and release discussions.