@ampproject/remapping

What is @ampproject/remapping?

The @ampproject/remapping npm package is used for source map transformation. It allows developers to take existing source maps and remap them to create new source maps that reflect the combined transformations of multiple build steps. This is particularly useful when dealing with complex build processes involving multiple tools that each generate their own source maps.

What are @ampproject/remapping's main functionalities?

Remapping source maps

This feature allows you to remap source maps by providing the original source map and a chain of additional source maps. The package will then produce a new source map that reflects the composition of all provided source maps.

{"version":3,"file":"out.js","sources":["foo.js","bar.js"],"names":["src","maps","are","fun"],"mappings":"AAgBC,SAAQ,CAAEA"}

Other packages similar to @ampproject/remapping

source-map

The 'source-map' package provides functionalities for generating and consuming source maps. It allows for the manipulation of source maps which is similar to what @ampproject/remapping offers, but it is a more general-purpose library with a broader scope of source map operations.

combine-source-map

The 'combine-source-map' package is used for combining multiple source maps into a single source map. It is similar to @ampproject/remapping in that it deals with the transformation of source maps, but it focuses specifically on the combination aspect.

multi-stage-sourcemap

The 'multi-stage-sourcemap' package is designed to handle the case where multiple transformations are applied to code and each transformation has its own source map. It is similar to @ampproject/remapping in its purpose of remapping source maps through multiple stages.

README

@ampproject/remapping

Remap sequential sourcemaps through transformations to point at the original source code

Remapping allows you to take the sourcemaps generated through transforming your code and "remap" them to the original source locations. Think "my minified code, transformed with babel and bundled with webpack", all pointing to the correct location in your original source code.

With remapping, none of your source code transformations need to be aware of the input's sourcemap, they only need to generate an output sourcemap. This greatly simplifies building custom transformations (think a find-and-replace).

Installation

npm install @ampproject/remapping

Usage

function remapping(
  map: SourceMap | SourceMap[],
  loader: (file: string) => (SourceMap | null | undefined),
  options?: { excludeContent: boolean, decodedMappings: boolean }
): SourceMap;

remapping takes the final output sourcemap, and a loader function. For every source file pointer in the sourcemap, the loader will be called with the resolved path. If the path itself represents a transformed file (it has a sourcmap associated with it), then the loader should return that sourcemap. If not, the path will be treated as an original, untransformed source code.

// Babel transformed "helloworld.js" into "transformed.js"
const transformedMap = JSON.stringify({
  file: 'transformed.js',
  // 1st column of 2nd line of output file translates into the 1st source
  // file, line 3, column 2
  mappings: ';CAEE',
  sources: ['helloworld.js'],
  version: 3,
});

// Uglify minified "transformed.js" into "transformed.min.js"
const minifiedTransformedMap = JSON.stringify({
  file: 'transformed.min.js',
  // 0th column of 1st line of output file translates into the 1st source
  // file, line 2, column 1.
  mappings: 'AACC',
  names: [],
  sources: ['transformed.js'],
  version: 3,
});

const remapped = remapping(
  minifiedTransformedMap,
  (file) => {

    // The "transformed.js" file is an transformed file.
    if (file === 'transformed.js') {
      return transformedMap;
    }

    // Loader will be called to load transformedMap's source file pointers as well.
    console.assert(file === 'helloworld.js');
    return null;
  }
);

console.log(remapped);
// {
//   file: 'transpiled.min.js',
//   mappings: 'AAEE',
//   sources: ['helloworld.js'],
//   version: 3,
// };

In this example, loader will be called twice:

1. "transformed.js", the first source file pointer in the minifiedTransformedMap. We return the associated sourcemap for it (its a transformed file, after all) so that sourcemap locations can be traced through it into the source files it represents.
2. "helloworld.js", our original, unmodified source code. This file does not have a sourcemap, so we return null.

The remapped sourcemap now points from transformed.min.js into locations in helloworld.js. If you were to read the mappings, it says "0th column of the first line output line points to the 1st column of the 2nd line of the file helloworld.js".

Multiple transformations of a file

As a convenience, if you have multiple single-source transformations of a file, you may pass an array of sourcemap files in the order of most-recent transformation sourcemap first. So our above example could have been writen as:

const remapped = remapping(
  [minifiedTransformedMap, transformedMap],
  () => null
);

console.log(remapped);
// {
//   file: 'transpiled.min.js',
//   mappings: 'AAEE',
//   sources: ['helloworld.js'],
//   version: 3,
// };

Options

excludeContent

By default, excludeContent is false. Passing { excludeContent: true } will exclude the sourcesContent field from the returned sourcemap. This is mainly useful when you want to reduce the size out the sourcemap.

decodedMappings

By default, decodedMappings is false. Passing { decodedMappings: true } will leave the mappings field in a decoded state instead of encoding into a VLQ string.