source: trip-planner-front/node_modules/adjust-sourcemap-loader/readme.md@ 6fe77af

Last change on this file since 6fe77af was 6a3a178, checked in by Ema <ema_spirova@…>, 3 years ago

initial commit

  • Property mode set to 100644
File size: 5.6 KB
Line 
1# Adjust Source-map Loader
2
3[![NPM](https://nodei.co/npm/adjust-sourcemap-loader.png)](http://github.com/bholloway/adjust-sourcemap-loader)
4
5Webpack loader that adjusts source maps.
6
7Use as a **loader** to debug source-maps or to adjust source-maps between other loaders.
8
9Use as a **module filename template** to ensure the final source-map are to your liking.
10
11## Usage : Loader
12
13``` javascript
14require('adjust-sourcemap?format=absolute!babel?sourceMap');
15```
16
17### Source maps required
18
19Note that **source maps** must be enabled on any preceding loader. In the above example we use `babel?sourceMap`.
20
21### Apply via webpack config
22
23It is preferable to adjust your `webpack.config` so to avoid having to prefix every `require()` statement:
24
25``` javascript
26module.exports = {
27 module: {
28 loaders: [
29 {
30 test : /\.js/,
31 loaders: ['adjust-sourcemap?format=absolute', 'babel?sourceMap']
32 }
33 ]
34 }
35};
36```
37
38## Usage : Module filename template
39
40Specifying 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**.
41
42There 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`.
43
44In the following example we ensure project-relative source-map sources are output.
45
46```javascript
47var templateFn = require('adjust-sourcemap-loader')
48 .moduleFilenameTemplate({
49 format: 'projectRelative'
50 });
51
52module.exports = {
53 output: {
54 ...
55 devtoolModuleFilenameTemplate : templateFn,
56 devtoolFallbackModuleFilenameTemplate: templateFn
57 }
58};
59```
60
61## Options
62
63As 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`.
64
65```javascript
66module.exports = {
67 adjustSourcemapLoader: {
68 ...
69 }
70}
71```
72
73Where `...` is a hash of any of the following options.
74
75* **`debug`** : `boolean|RegExp` May be used alone (boolean) or with a `RegExp` to match the resource(s) you are interested in debugging.
76
77* **`fail`** : `boolean` Implies an **Error** if a source-map source cannot be decoded.
78
79* **`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.
80
81* **`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.
82
83* **`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.
84
85Note that **query** parameters take precedence over **programmatic** parameters.
86
87### Changing the format
88
89Built-in codecs that may be specified as a `format` include:
90
91* `absolute`
92* `outputRelative`
93* `projectRelative`
94* `webpackProtocol`
95* `sourceRelative` (works for loader only, **not** Module filename template)
96
97### Specifying codecs
98
99There 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.
100
101The existing codecs may be found in `/codec`, or on the loader itself:
102
103```javascript
104var inBuiltCodecs = require('adjust-sourcemap-loader').codecs,
105 myCodecs = [
106 {
107 name : 'foo',
108 decode: function(uri) {...},
109 encode: function(absolute) {...},
110 root : function() {...}
111 },
112 ...
113 ];
114
115module.exports = {
116 adjustSourcemapLoader: {
117 codecs: inBuiltCodecs.concat(myCodecs)
118 }
119}
120```
121
122The 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.
123
124### Abstract codecs
125
126A codec that detects generated code and cannot `decode()` a URI to an absolute file path.
127
128Instead of implementing `encode()` or `root()` it should instead specify `abstract:true`. Its `decode()` function then may return `boolean` where it detects such generated sources.
129
130For 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.
131
132## How it works
133
134The loader will receive a source map as its second parameter, so long as the preceding loader was using source-maps.
135
136The exception is the **css-loader** where the source-map is in the content, which is **not currently supported** .
137
138The 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.
139
140If 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`.
141
142If a codec does not specify **codec.encode()** or **codec.root()** then it may **not** be used as the `format`.
143
Note: See TracBrowser for help on using the repository browser.