Question
Does Dart Sass require explicit --embed-sources to include source content in source maps?
Neel Sage
0 reputation · 06 Jul 2025, 19:49 UTC
136.9K views
Loading…
0 reputation · 06 Jul 2025, 19:49 UTC
Goal: Determine whether the default source‑map behavior in Dart Sass (≥1.23) provides a reliable way to back up and verify recovered Sass source after CSS compilation.
Constraint: With the default configuration the embedSources flag is false, so generated .css.map files reference external .scss files rather than embedding their content. Verification therefore depends on the build pipeline preserving the original source files and serving them from locations that match the paths recorded in the map.
Uncertainty: If the original Sass files are moved, renamed, or omitted after compilation, the source map may point to missing or incorrect locations, breaking the ability to inspect the original Sass in browser devtools. Enabling embedSources solves this by inlining the source as base64, but it increases map size and may affect network performance.
Questions: Does relying on external source references still allow accurate verification when the original .scss files remain alongside the map? What risks arise if the build process does not guarantee the preservation or correct location of those source files? How does the trade‑off between map size and source‑availability influence the decision to enable embedSources in production debugging workflows?
With Dart Sass ≥1.23 the default embedSources flag is false. That means a generated .css.map contains only file paths to the original .scss files; the source text is not inlined. To embed the source you must explicitly enable it with --embed-sources or embedSources:true in a config file.
When embedSources is off, browsers will try to fetch the referenced .scss files during debugging. If those files remain in the same relative locations, the source appears correctly in devtools. If the files are moved, renamed, or omitted, the map points to a missing resource and the original Sass can no longer be inspected.
sassdart-sass input.scss output.css and open output.css.map in a text editor. You should see a sources array with file paths and no sourcesContent section.dart-sass input.scss output.css --embed-sources (or set embedSources:true in sass.json). The map will now contain a sourcesContent array with base64‑encoded source text.embedSources is off and the original files exist at the recorded paths, you’ll see the Sass code. If the files are missing, the devtools will display a “source not found” error.--embed-sources.scss files are not stored in a public or easily accessible location.If you are comfortable with the build process preserving the Sass files and can tolerate the extra map size, you can keep the default embedSources=false. Otherwise, enable the flag to lock in source availability.
To fine‑tune the recommendation, it would help to know where the original .scss files are stored relative to the generated .css.map in your deployment environment.
Use comments to ask for clarification. Post a solution as an answer.
34,775 reputation · 07 Jul 2025, 06:53 UTC
To expand on the reliability of external references, it is important to consider the sourceRoot property in the generated .css.map. When --embed-sources is disabled, Dart Sass uses this field to define the base URL or path from which the sources array is resolved.
If your build pipeline moves the compiled CSS to a /dist folder but keeps the Sass files in a /src folder, the browser may fail to resolve the paths unless sourceRoot is correctly configured to point back to the source directory. Without sourcesContent, any mismatch between the deployment directory structure and the paths recorded in the map will result in 404 errors in the browser devtools, effectively breaking the link to the original Sass.
For those avoiding embedded sources in production, verifying the sourceRoot value in the JSON map is a critical step to ensure the browser can actually locate the external .scss files.