[heft-sass-plugin] Add preserveIcssExports option

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"
+}

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

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

heft-plugins/heft-sass-plugin/package.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/src/SassPlugin.ts

@@ -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/SassProcessor.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/schemas/heft-sass-plugin.schema.json

@@ -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."
     }
   }
 }