Add opt-in sourceMap option to emit .css.map files and sourceMappingURL comments alongside compiled CSS

common/changes/@rushstack/heft-sass-plugin/add-sourcemap-option_2026-05-19-00-00.json

@@ -0,0 +1,11 @@
+{
+  "changes": [
+    {
+      "comment": "Add opt-in sourceMap option to emit .css.map files and sourceMappingURL comments alongside compiled CSS",
+      "type": "minor",
+      "packageName": "@rushstack/heft-sass-plugin"
+    }
+  ],
+  "packageName": "@rushstack/heft-sass-plugin",
+  "email": "cmalonzo@microsoft.com"
+}

heft-plugins/heft-sass-plugin/src/SassPlugin.ts

@@ -31,6 +31,7 @@ export interface ISassConfigurationJson {
   excludeFiles?: string[];
   doNotTrimOriginalFileExtension?: boolean;
   preserveIcssExports?: boolean;
+  sourceMap?: boolean;
 }
 
 const SASS_CONFIGURATION_LOCATION: string = 'config/sass.json';
@@ -100,7 +101,8 @@ export default class SassPlugin implements IHeftPlugin {
           silenceDeprecations,
           excludeFiles,
           doNotTrimOriginalFileExtension,
-          preserveIcssExports
+          preserveIcssExports,
+          sourceMap
         } = sassConfigurationJson || {};
 
         function resolveFolder(folder: string): string {
@@ -129,6 +131,7 @@ export default class SassPlugin implements IHeftPlugin {
           silenceDeprecations,
           doNotTrimOriginalFileExtension,
           preserveIcssExports,
+          sourceMap,
           postProcessCssAsync: hooks.postProcessCss.isUsed()
             ? async (cssText: string) => hooks.postProcessCss.promise(cssText)
             : undefined

heft-plugins/heft-sass-plugin/src/SassProcessor.ts

@@ -130,6 +130,12 @@ export interface ISassProcessorOptions {
    */
   preserveIcssExports?: boolean;
 
+  /**
+   * If true, a .css.map source map file will be written next to each emitted .css, and a
+   * sourceMappingURL comment will be appended to the .css. Defaults to false.
+   */
+  sourceMap?: boolean;
+
   /**
    * A callback to further modify the raw CSS text after it has been generated. Only relevant if emitting CSS files.
    */
@@ -261,7 +267,8 @@ export class SassProcessor {
           load: loadAsync
         }
       ],
-      silenceDeprecations: deprecationsToSilence
+      silenceDeprecations: deprecationsToSilence,
+      ...(options.sourceMap && { sourceMap: true, sourceMapIncludeSources: true })
     };
   }
 
@@ -761,7 +768,8 @@ export class SassProcessor {
       exportAsDefault,
       doNotTrimOriginalFileExtension,
       postProcessCssAsync,
-      preserveIcssExports
+      preserveIcssExports,
+      sourceMap
     } = this._options;
 
     // Handle CSS modules
@@ -833,11 +841,34 @@ export class SassProcessor {
       }
 
       const cssPathFromJs: string = `./${cssFilename}`;
+
+      // When sourceMap is enabled, prepare the annotated CSS and map basename once —
+      // cssFilename is identical across all output folders.
+      const cssMapBasename: string | undefined =
+        sourceMap && result.sourceMap ? `${cssFilename}.map` : undefined;
+      const finalCss: string = cssMapBasename ? `${css}\n/*# sourceMappingURL=${cssMapBasename} */\n` : css;
+
       for (const cssOutputFolder of cssOutputFolders) {
         const { folder, shimModuleFormat } = cssOutputFolder;
 
         const cssFilePath: string = path.resolve(folder, relativeCssPath);
-        await FileSystem.writeFileAsync(cssFilePath, css, writeFileOptions);
+        await FileSystem.writeFileAsync(cssFilePath, finalCss, writeFileOptions);
+
+        if (cssMapBasename && result.sourceMap) {
+          const mapFilePath: string = `${cssFilePath}.map`;
+          const mapDir: string = path.dirname(cssFilePath);
+          // Rewrite heft: URL sources to paths relative to the map file's directory
+          // so that source-map-loader can resolve them back to the original .scss.
+          const rewrittenSources: string[] = result.sourceMap.sources.map((source) => {
+            const absoluteSourcePath: string = heftUrlToPath(source);
+            return Path.convertToSlashes(path.relative(mapDir, absoluteSourcePath));
+          });
+          await FileSystem.writeFileAsync(
+            mapFilePath,
+            JSON.stringify({ ...result.sourceMap, file: cssFilename, sources: rewrittenSources }),
+            writeFileOptions
+          );
+        }
 
         if (shimModuleFormat && !filename.endsWith('.css')) {
           const jsFilePath: string = path.resolve(folder, `${relativeFilePath}.js`);

heft-plugins/heft-sass-plugin/src/schemas/heft-sass-plugin.schema.json

@@ -116,6 +116,11 @@
     "preserveIcssExports": {
       "type": "boolean",
       "description": "If true, the ICSS `:export` block will be preserved in the emitted CSS output. This is necessary when the CSS is consumed by a webpack loader (e.g. css-loader's icssParser) that extracts `:export` values at bundle time to generate JavaScript exports. Defaults to false."
+    },
+
+    "sourceMap": {
+      "type": "boolean",
+      "description": "If true, a .css.map source map file will be written next to each emitted .css file, and a sourceMappingURL comment will be appended to the .css. Defaults to false."
     }
   }
 }

heft-plugins/heft-sass-plugin/src/test/SassProcessor.test.ts

@@ -33,6 +33,7 @@ type ICreateProcessorOptions = Partial<
     | 'postProcessCssAsync'
     | 'preserveIcssExports'
     | 'silenceDeprecations'
+    | 'sourceMap'
     | 'srcFolder'
   >
 >;
@@ -65,6 +66,40 @@ async function compileFixtureAsync(processor: SassProcessor, fixtureFilename: st
   await processor.compileFilesAsync(new Set([`${fixturesFolder}/${fixtureFilename}`]));
 }
 
+/**
+ * Replaces OS-/checkout-dependent fields in a source map JSON string with stable placeholders so
+ * the test can snapshot the result on any machine. Specifically, rewrites `sources[]` entries that
+ * point at the fixtures folder to a `fixtures/<name>` form, and normalizes `sourcesContent[]`
+ * line endings to LF.
+ */
+function normalizeSourceMapForSnapshot(json: string): string {
+  const map: {
+    sources?: string[];
+    sourcesContent?: string[];
+    [key: string]: unknown;
+  } = JSON.parse(json);
+
+  if (map.sources) {
+    map.sources = map.sources.map((source) => {
+      const normalized: string = Path.convertToSlashes(source);
+      // sources[] are stored as paths relative to the .css.map output file, so they include a
+      // checkout-specific prefix like "../../../user/rushstack/heft-plugins/...". Strip everything
+      // before the well-known "/fixtures/" segment to get a stable suffix.
+      const fixturesIndex: number = normalized.indexOf('/fixtures/');
+      if (fixturesIndex >= 0) {
+        return normalized.slice(fixturesIndex + 1);
+      }
+      const lastSlash: number = normalized.lastIndexOf('/');
+      return `fixtures/${lastSlash >= 0 ? normalized.slice(lastSlash + 1) : normalized}`;
+    });
+  }
+  if (map.sourcesContent) {
+    map.sourcesContent = map.sourcesContent.map((entry) => entry.replace(/\r\n/g, '\n'));
+  }
+
+  return JSON.stringify(map);
+}
+
 describe(SassProcessor.name, () => {
   let terminalProvider: StringBufferTerminalProvider;
   /** Files captured by the mocked FileSystem.writeFileAsync, keyed by absolute path. */
@@ -112,7 +147,14 @@ describe(SassProcessor.name, () => {
         NORMALIZED_PLATFORM_FAKE_OUTPUT_BASE_FOLDER,
         FAKE_OUTPUT_BASE_FOLDER
       );
-      writtenFiles.set(filePath, String(content));
+      let serialized: string = String(content);
+      // Source map contents include the absolute-relative path back to the source file and the
+      // verbatim source file bytes. Both vary by checkout location and OS line endings, which makes
+      // raw snapshots non-portable. Normalize them to stable forms before storing.
+      if (filePath.endsWith('.css.map')) {
+        serialized = normalizeSourceMapForSnapshot(serialized);
+      }
+      writtenFiles.set(filePath, serialized);
     });
   });
 
@@ -690,4 +732,52 @@ describe(SassProcessor.name, () => {
       expect(logger.errors.length).toBeGreaterThan(0);
     });
   });
+
+  describe('sourceMap option', () => {
+    it('emits .css.map and sourceMappingURL comment when sourceMap is true', async () => {
+      const { processor } = createProcessor(terminalProvider, { sourceMap: true });
+      await compileFixtureAsync(processor, 'classes-and-exports.module.scss');
+
+      const mapPaths: string[] = getAllWrittenPathsMatching('.css.map');
+      expect(mapPaths).toHaveLength(1);
+
+      const css: string = getCssOutput('classes-and-exports.module.scss');
+      expect(css).toMatch(/\/\*# sourceMappingURL=classes-and-exports\.module\.css\.map \*\//);
+
+      const mapJson: string = getWrittenFile('classes-and-exports.module.css.map');
+      const parsedMap: {
+        version: number;
+        mappings: string;
+        sources: string[];
+      } = JSON.parse(mapJson);
+      expect(parsedMap.version).toBe(3);
+      expect(parsedMap.mappings).toBeTruthy();
+      expect(parsedMap.sources).toHaveLength(1);
+      expect(parsedMap.sources[0]).toMatch(/classes-and-exports\.module\.scss$/);
+    });
+
+    it('does not emit .css.map or sourceMappingURL comment by default', async () => {
+      const { processor } = createProcessor(terminalProvider);
+      await compileFixtureAsync(processor, 'classes-and-exports.module.scss');
+
+      expect(getAllWrittenPathsMatching('.css.map')).toHaveLength(0);
+      expect(getCssOutput('classes-and-exports.module.scss')).not.toContain('sourceMappingURL');
+    });
+
+    it('uses the correct map filename when doNotTrimOriginalFileExtension is true', async () => {
+      const { processor } = createProcessor(terminalProvider, {
+        sourceMap: true,
+        doNotTrimOriginalFileExtension: true
+      });
+      await compileFixtureAsync(processor, 'classes-and-exports.module.scss');
+
+      // With doNotTrimOriginalFileExtension the CSS file is foo.scss.css, so the map is foo.scss.css.map
+      const mapPaths: string[] = getAllWrittenPathsMatching('.css.map');
+      expect(mapPaths).toHaveLength(1);
+      expect(mapPaths[0]).toMatch(/classes-and-exports\.module\.scss\.css\.map$/);
+
+      const css: string = getWrittenFile('classes-and-exports.module.scss.css');
+      expect(css).toMatch(/\/\*# sourceMappingURL=classes-and-exports\.module\.scss\.css\.map \*\//);
+    });
+  });
 });

heft-plugins/heft-sass-plugin/src/test/__snapshots__/SassProcessor.test.ts.snap

@@ -1272,6 +1272,96 @@ export default styles;",
 }
 `;
 
+exports[`SassProcessor sourceMap option does not emit .css.map or sourceMappingURL comment by default: terminal-output 1`] = `
+Array [
+  "[verbose] Checking for changes to 1 files...[n]",
+  "[    log] Compiling 1 files...[n]",
+]
+`;
+
+exports[`SassProcessor sourceMap option does not emit .css.map or sourceMappingURL comment by default: written-files 1`] = `
+Map {
+  "/fake/output/dts/classes-and-exports.module.scss.d.ts" => "declare interface IStyles {
+  themeColor: string;
+  spacing: string;
+  root: string;
+  highlighted: string;
+}
+declare const styles: IStyles;
+export default styles;",
+  "/fake/output/css/classes-and-exports.module.css" => ".root {
+  color: red;
+  font-size: 14px;
+}
+
+.highlighted {
+  background-color: yellow;
+}",
+}
+`;
+
+exports[`SassProcessor sourceMap option emits .css.map and sourceMappingURL comment when sourceMap is true: terminal-output 1`] = `
+Array [
+  "[verbose] Checking for changes to 1 files...[n]",
+  "[    log] Compiling 1 files...[n]",
+]
+`;
+
+exports[`SassProcessor sourceMap option emits .css.map and sourceMappingURL comment when sourceMap is true: written-files 1`] = `
+Map {
+  "/fake/output/dts/classes-and-exports.module.scss.d.ts" => "declare interface IStyles {
+  themeColor: string;
+  spacing: string;
+  root: string;
+  highlighted: string;
+}
+declare const styles: IStyles;
+export default styles;",
+  "/fake/output/css/classes-and-exports.module.css" => ".root {
+  color: red;
+  font-size: 14px;
+}
+
+.highlighted {
+  background-color: yellow;
+}
+/*# sourceMappingURL=classes-and-exports.module.css.map */
+",
+  "/fake/output/css/classes-and-exports.module.css.map" => "{\\"version\\":3,\\"sourceRoot\\":\\"\\",\\"sources\\":[\\"fixtures/classes-and-exports.module.scss\\"],\\"names\\":[],\\"mappings\\":\\"AACA;EACE;EACA;;;AAGF;EACE;;;AAGF;EACE;EACA\\",\\"sourcesContent\\":[\\"// A CSS module that exports both class names and ICSS :export values.\\\\n.root {\\\\n  color: red;\\\\n  font-size: 14px;\\\\n}\\\\n\\\\n.highlighted {\\\\n  background-color: yellow;\\\\n}\\\\n\\\\n:export {\\\\n  themeColor: blue;\\\\n  spacing: 8px;\\\\n}\\\\n\\"],\\"file\\":\\"classes-and-exports.module.css\\"}",
+}
+`;
+
+exports[`SassProcessor sourceMap option uses the correct map filename when doNotTrimOriginalFileExtension is true: terminal-output 1`] = `
+Array [
+  "[verbose] Checking for changes to 1 files...[n]",
+  "[    log] Compiling 1 files...[n]",
+]
+`;
+
+exports[`SassProcessor sourceMap option uses the correct map filename when doNotTrimOriginalFileExtension is true: written-files 1`] = `
+Map {
+  "/fake/output/dts/classes-and-exports.module.scss.d.ts" => "declare interface IStyles {
+  themeColor: string;
+  spacing: string;
+  root: string;
+  highlighted: string;
+}
+declare const styles: IStyles;
+export default styles;",
+  "/fake/output/css/classes-and-exports.module.scss.css" => ".root {
+  color: red;
+  font-size: 14px;
+}
+
+.highlighted {
+  background-color: yellow;
+}
+/*# sourceMappingURL=classes-and-exports.module.scss.css.map */
+",
+  "/fake/output/css/classes-and-exports.module.scss.css.map" => "{\\"version\\":3,\\"sourceRoot\\":\\"\\",\\"sources\\":[\\"fixtures/classes-and-exports.module.scss\\"],\\"names\\":[],\\"mappings\\":\\"AACA;EACE;EACA;;;AAGF;EACE;;;AAGF;EACE;EACA\\",\\"sourcesContent\\":[\\"// A CSS module that exports both class names and ICSS :export values.\\\\n.root {\\\\n  color: red;\\\\n  font-size: 14px;\\\\n}\\\\n\\\\n.highlighted {\\\\n  background-color: yellow;\\\\n}\\\\n\\\\n:export {\\\\n  themeColor: blue;\\\\n  spacing: 8px;\\\\n}\\\\n\\"],\\"file\\":\\"classes-and-exports.module.scss.css\\"}",
+}
+`;
+
 exports[`SassProcessor use-with-partial.module.scss (@use with local partial) generates .d.ts with class names from a file using @use: terminal-output 1`] = `
 Array [
   "[verbose] Checking for changes to 1 files...[n]",