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 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`.