proposal/source-map-include-sources.md
(Issue)
This section is non-normative.
Historically, Sass has provided a boolean sourceMapIncludeSources option to
embed the contents of source files into source maps generated by Sass. However,
there were a number of oddities and inconsistencies in this option:
In order to provide a convenient user experience, files loaded via custom
importer without an explict sourceMapUrl would always have a data: URL in
the sources field in the source map. This exposes the source contents even
if the sourceMapIncludesources option is set to false. On the other hand,
the source contents are embedded twice in sources field as the data: URL
and the sourcesContent field data if the option is set to true.
The use of data: URLs instead of the canonical URLs has led to difficulties
of identifying the name of these source files when navigating through the
source map.
This proposal addresses both of the issues above:
sourceMapIncludeSources now accepts new values for refined control and
consistency.
Custom importers use their canonical URLs as sourceMapUrls if they don't
define a URL explicitly.
Options.sourceMapIncludeSourcessourceMapIncludeSources?: 'auto' | 'never' | 'always';
If the value is 'auto' (the default), source contents are included in the
source map's sourcesContent only for stylesheets without explictly defined
sourceMapUrls.
If the value is 'never', no stylesheets' contents are included in the source
map's sourcesContent.
If the value is 'always', source contents are included in the source map's
sourcesContent for all stylesheets.
ImporterReplace the bullet point in the Importer specification that begins with "If
result.sourceMapUrl is defined..." with:
If the implementation generates a source map:
If result.sourceMapUrl is defined, the implementation must use this URL in
the source map to refer to source spans in result.contents.
Otherwise, the implementation must use url in the source map to refer to
source spans in result.contents.
The deprecation process will be divided into two phases:
This phase adds no breaking changes. Its purpose is to notify users of the upcoming changes to behavior and give them a chance to move towards future-proof options.
Phase 1 continues to allow passing boolean values to sourceMapIncludeSources,
and produces a deprecation warning named source-map-include-sources-boolean.
Options.sourceMapIncludeSourcessourceMapIncludeSources?: 'auto' | 'never' | 'always' | boolean;
Boolean values are mapped to the specified string values as follows:
false => 'never'true => 'always'All other changes are implemented as specified.
Phase 2 implements the full changes described above. Passing boolean value will throw an error. It will be released as a breaking change in next Dart Sass major version.