[heft-sass-plugin] Add preserveIcssExports option (#5762)

* [heft-sass-plugin] Add preserveIcssExports option

Add a new `preserveIcssExports` option to `sass.json` that preserves the ICSS `:export` block in the emitted CSS output. When false (the default), `postcss-modules` strips `:export` from the CSS as before. When true, the CSS is left unchanged so that downstream webpack loaders (e.g. css-loader's icssParser) can extract the `:export` values at bundle time to generate JavaScript module exports.

* fixup! [heft-sass-plugin] Add preserveIcssExports option

* Add snapshot tests for SassProcessor

Tests cover CSS output (preserveIcssExports true/false), .d.ts generation, Sass-specific features (variables + nesting, @mixin, @extend + placeholders), and error reporting for invalid SCSS.

* Add snapshot tests for SassProcessor

Tests cover CSS output (preserveIcssExports true/false), .d.ts generation, Sass-specific features (variables + nesting, @mixin, @extend + placeholders), and error reporting for invalid SCSS.

* Add snapshot tests for SassProcessor

Tests cover CSS output (preserveIcssExports true/false), .d.ts generation,
Sass-specific features (variables + nesting, @mixin, @extend + placeholders),
JS shim generation (commonjs/esnext, module/global), multiple output folders,
postProcessCssAsync callback, exportAsDefault: false, and error reporting.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

---------

Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: iclanton

common/changes/@rushstack/heft-sass-plugin/heft-sass-plugin-preserve-icss-exports_2026-04-09-00-00.json

@@ -0,0 +1,10 @@
+{
+  "changes": [
+    {
+      "packageName": "@rushstack/heft-sass-plugin",
+      "comment": "Add `preserveIcssExports` option to keep the ICSS `:export` block in emitted CSS output, required when downstream webpack loaders (e.g. `css-loader` icssParser) need to extract `:export` values at bundle time.",
+      "type": "minor"
+    }
+  ],
+  "packageName": "@rushstack/heft-sass-plugin"
+}

common/config/subspaces/default/pnpm-lock.yaml

@@ -0,0 +1,3 @@
+{
+  "extends": "local-node-rig/profiles/default/config/jest.config.json"
+}

heft-plugins/heft-sass-plugin/config/jest.config.json

@@ -56,6 +56,7 @@
   "devDependencies": {
     "@microsoft/api-extractor": "workspace:*",
     "@rushstack/heft": "workspace:*",
+    "@rushstack/terminal": "workspace:*",
     "eslint": "~9.37.0",
     "local-node-rig": "workspace:*"
   },

heft-plugins/heft-sass-plugin/package.json

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

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

@@ -121,6 +121,15 @@ export interface ISassProcessorOptions {
    */
   doNotTrimOriginalFileExtension?: boolean;
 
+  /**
+   * 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.
+   */
+  preserveIcssExports?: boolean;
+
   /**
    * A callback to further modify the raw CSS text after it has been generated. Only relevant if emitting CSS files.
    */
@@ -751,7 +760,8 @@ export class SassProcessor {
       srcFolder,
       exportAsDefault,
       doNotTrimOriginalFileExtension,
-      postProcessCssAsync
+      postProcessCssAsync,
+      preserveIcssExports
     } = this._options;
 
     // Handle CSS modules
@@ -769,7 +779,14 @@ export class SassProcessor {
       const postCssResult: postcss.Result = await postcss
         .default([postCssModules])
         .process(css, { from: sourceFilePath });
-      css = postCssResult.css;
+
+      if (!preserveIcssExports) {
+        // Default behavior: use the transformed CSS output, which has the :export block stripped.
+        css = postCssResult.css;
+      }
+      // If preserveIcssExports is true, we discard the transformed CSS and keep the original so
+      // that the :export block remains in the output for downstream webpack loaders (e.g.
+      // css-loader's icssParser) that extract :export values at bundle time.
     }
 
     if (postProcessCssAsync) {

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

@@ -111,6 +111,11 @@
     "doNotTrimOriginalFileExtension": {
       "type": "boolean",
       "description": "If true, the original file extension will not be trimmed when generating the output CSS file. The generated CSS file will retain its original extension. For example, \"styles.scss\" will generate \"styles.scss.css\" instead of \"styles.css\"."
+    },
+
+    "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."
     }
   }
 }