144 lines
5.6 KiB
Markdown
144 lines
5.6 KiB
Markdown
# Adjust Source-map Loader
|
|
|
|
[](http://github.com/bholloway/adjust-sourcemap-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
|
|
|
|
``` javascript
|
|
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:
|
|
|
|
``` javascript
|
|
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.
|
|
|
|
```javascript
|
|
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](https://webpack.github.io/docs/using-loaders.html#query-parameters) or by using [programmatic parameters](https://webpack.github.io/docs/how-to-write-a-loader.html#programmable-objects-as-query-option). Programmatic means the following in your `webpack.config`.
|
|
|
|
```javascript
|
|
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:
|
|
|
|
```javascript
|
|
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`.
|
|
|