Adjust Source-map Loader

Webpack loader that adjusts source maps.

Use as a loader to debug source-maps or to adjust source-maps between other loaders.

Use as a module filename template to ensure the final source-map are to your liking.

Usage : Loader

require('adjust-sourcemap?format=absolute!babel?sourceMap');

Source maps required

Note that source maps must be enabled on any preceding loader. In the above example we use babel?sourceMap.

Apply via webpack config

It is preferable to adjust your webpack.config so to avoid having to prefix every require() statement:

module.exports = {
  module: {
    loaders: [
      {
        test   : /\.js/,
        loaders: ['adjust-sourcemap?format=absolute', 'babel?sourceMap']
      }
    ]
  }
};

Usage : Module filename template

Specifying a certain format as the final step in a loader chain will not influence the final source format that Webpack will output. Instead the format is determined by the module filename template.

There are limitations to the filename templating that Webpack provides. This package may also operate as a custom template function that will convert output source-map sources to the desired format.

In the following example we ensure project-relative source-map sources are output.

var templateFn = require('adjust-sourcemap-loader')
  .moduleFilenameTemplate({
    format: 'projectRelative'
  });

module.exports = {
  output: {
    ...
    devtoolModuleFilenameTemplate        : templateFn,
    devtoolFallbackModuleFilenameTemplate: templateFn
  }
};

Options

As a loader, options may be set using query parameters or by using programmatic parameters. Programmatic means the following in your webpack.config.

module.exports = {
   adjustSourcemapLoader: {
      ...
   }
}

Where ... is a hash of any of the following options.

• debug : boolean|RegExp May be used alone (boolean) or with a RegExp to match the resource(s) you are interested in debugging.

• fail : boolean Implies an Error if a source-map source cannot be decoded.

• format : string Optional output format for source-map sources. Must be the camel-case name of one of the available codecs. Omitting the format will result in no change and the outgoing source-map will match the incomming one.

• root : boolean A boolean flag that indices that a sourceRoot path sould be included in the output map. This is contingent on a format being specified.

• codecs : Array.<{name:string, decode:function, encode:function, root:function}> Optional Array of codecs. There are a number of built-in codecs available. If you specify you own codecs you will loose those that are built-in. However you can include them from the codec/ directory.

Note that query parameters take precedence over programmatic parameters.

Changing the format

Built-in codecs that may be specified as a format include:

• absolute
• outputRelative
• projectRelative
• webpackProtocol
• sourceRelative (works for loader only, not Module filename template)

Specifying codecs

There are additional built-in codecs that do not support encoding. These are still necessary to decode source-map sources. If you specify your own options.codecs then you should also include the built-in codecs. Otherwise you will find that some sources cannot be decoded.

The existing codecs may be found in /codec, or on the loader itself:

var inBuiltCodecs = require('adjust-sourcemap-loader').codecs,
    myCodecs      = [
      {
        name  : 'foo',
        decode: function(uri) {...},
        encode: function(absolute) {...},
        root  : function() {...}
      },
      ...
    ];

module.exports = {
   adjustSourcemapLoader: {
      codecs: inBuiltCodecs.concat(myCodecs)
   }
}

The codec order is important. Those that come first have precedence. Any codec that detects a distinct URI should be foremost so that illegal paths are not encountered by successive codecs.

Abstract codecs

A codec that detects generated code and cannot decode() a URI to an absolute file path.

Instead of implementing encode() or root() it should instead specify abstract:true. Its decode() function then may return boolean where it detects such generated sources.

For example, a built-in abstract codec will match the Webpack bootstrap code and ensure that its illegal source uri is not encountered by later coders.

How it works

The loader will receive a source map as its second parameter, so long as the preceding loader was using source-maps.

The exception is the css-loader where the source-map is in the content, which is not currently supported .

The source-map sources are parsed by applying codec.decode() functions until one of them returns an absolute path to a file that exists. The exception is abstract codecs, where the source with remain unchanged.

If a format is specified then the source-map sources are recreated by applying the codec.encode() function for the stated format and (where the root option is specified) the codec.root() function will set the source-map sourceRoot.

If a codec does not specify codec.encode() or codec.root() then it may not be used as the format.