| 1 | # PostCSS and Source Maps
|
| 2 |
|
| 3 | PostCSS has great [source maps] support. It can read and interpret maps
|
| 4 | from previous transformation steps, autodetect the format that you expect,
|
| 5 | and output both external and inline maps.
|
| 6 |
|
| 7 | To ensure that you generate an accurate source map, you must indicate the input
|
| 8 | and output CSS file paths — using the options `from` and `to`, respectively.
|
| 9 |
|
| 10 | To generate a new source map with the default options, simply set `map: true`.
|
| 11 | This will generate an inline source map that contains the source content.
|
| 12 | If you don’t want the map inlined, you can set `map.inline: false`.
|
| 13 |
|
| 14 | ```js
|
| 15 | processor
|
| 16 | .process(css, {
|
| 17 | from: 'app.sass.css',
|
| 18 | to: 'app.css',
|
| 19 | map: { inline: false }
|
| 20 | })
|
| 21 | .then(result => {
|
| 22 | result.map //=> '{ "version":3,
|
| 23 | // "file":"app.css",
|
| 24 | // "sources":["app.sass"],
|
| 25 | // "mappings":"AAAA,KAAI" }'
|
| 26 | })
|
| 27 | ```
|
| 28 |
|
| 29 | If PostCSS finds source maps from a previous transformation,
|
| 30 | it will automatically update that source map with the same options.
|
| 31 |
|
| 32 | ## Options
|
| 33 |
|
| 34 | If you want more control over source map generation, you can define the `map`
|
| 35 | option as an object with the following parameters:
|
| 36 |
|
| 37 | * `inline` boolean: indicates that the source map should be embedded
|
| 38 | in the output CSS as a Base64-encoded comment. By default, it is `true`.
|
| 39 | But if all previous maps are external, not inline, PostCSS will not embed
|
| 40 | the map even if you do not set this option.
|
| 41 |
|
| 42 | If you have an inline source map, the `result.map` property will be empty,
|
| 43 | as the source map will be contained within the text of `result.css`.
|
| 44 |
|
| 45 | * `prev` string, object, boolean or function: source map content from
|
| 46 | a previous processing step (for example, Sass compilation).
|
| 47 | PostCSS will try to read the previous source map automatically
|
| 48 | (based on comments within the source CSS), but you can use this option
|
| 49 | to identify it manually. If desired, you can omit the previous map
|
| 50 | with `prev: false`.
|
| 51 |
|
| 52 | * `sourcesContent` boolean: indicates that PostCSS should set the origin
|
| 53 | content (for example, Sass source) of the source map. By default,
|
| 54 | it is `true`. But if all previous maps do not contain sources content,
|
| 55 | PostCSS will also leave it out even if you do not set this option.
|
| 56 |
|
| 57 | * `annotation` boolean or string: indicates that PostCSS should add annotation
|
| 58 | comments to the CSS. By default, PostCSS will always add a comment with a path
|
| 59 | to the source map. PostCSS will not add annotations to CSS files that
|
| 60 | do not contain any comments.
|
| 61 |
|
| 62 | By default, PostCSS presumes that you want to save the source map as
|
| 63 | `opts.to + '.map'` and will use this path in the annotation comment.
|
| 64 | A different path can be set by providing a string value for `annotation`.
|
| 65 |
|
| 66 | If you have set `inline: true`, annotation cannot be disabled.
|
| 67 |
|
| 68 | * `from` string: by default, PostCSS will set the `sources` property of the map
|
| 69 | to the value of the `from` option. If you want to override this behaviour, you
|
| 70 | can use `map.from` to explicitly set the source map's `sources` property.
|
| 71 | Path should be absolute or relative from generated file
|
| 72 | (`to` option in `process()` method).
|
| 73 |
|
| 74 | [source maps]: http://www.html5rocks.com/en/tutorials/developertools/sourcemaps/
|