CSS Module Import Transformer

Build a PostCSS plugin that transforms CSS Module composition syntax into import rules.

Background

CSS Modules allow developers to compose styles from other files using the composes keyword. Your task is to build a plugin that processes these composition declarations and transforms them into explicit import rules.

Requirements

Transform External Compositions

The plugin must process CSS rules containing composes declarations that reference external files. When it encounters a composition like:

.button {
  composes: base from "./styles/base.css";
  color: blue;
}

It should transform it into:

:import("./styles/base.css") {
  i__imported_base_0: base;
}
.button {
  composes: i__imported_base_0;
  color: blue;
}

Multiple Class Compositions

The plugin must handle compositions that import multiple classes from the same file:

.alert {
  composes: icon message from "./components/notification.css";
}

Should become:

:import("./components/notification.css") {
  i__imported_icon_0: icon;
  i__imported_message_1: message;
}
.alert {
  composes: i__imported_icon_0 i__imported_message_1;
}

Import Deduplication

When the same class is imported multiple times from the same file, the plugin must reuse the same generated identifier:

.primary {
  composes: button from "./base.css";
}
.secondary {
  composes: button from "./base.css";
}

Should produce a single import:

:import("./base.css") {
  i__imported_button_0: button;
}
.primary {
  composes: i__imported_button_0;
}
.secondary {
  composes: i__imported_button_0;
}

Unique Identifier Generation

The plugin must generate unique identifiers for each imported class to prevent naming conflicts. The identifier format should be:

• Start with a prefix (e.g., i__imported_)
• Include a sanitized version of the class name
• End with a unique numeric index

Test Cases

• Given a CSS file with composes: button from "./styles.css", the plugin produces an :import() rule and replaces the class name with a generated identifier. @test

• Given multiple compositions from the same file in different rules, the plugin produces a single :import() rule with all unique class mappings. @test

• Given a composition with multiple classes like composes: foo bar from "./lib.css", the plugin generates separate identifiers for each class. @test

Implementation

@generates

API

/**
 * PostCSS plugin that transforms CSS Module composes declarations
 * into explicit import rules.
 *
 * @returns {Object} PostCSS plugin instance
 */
module.exports = function() {
  return {
    postcssPlugin: 'css-module-import-transformer',
    Once(root, postcss) {
      // Implementation here
    }
  };
};

module.exports.postcss = true;

Dependencies { .dependencies }

postcss-modules-extract-imports { .dependency }

Provides CSS Modules import extraction and transformation capabilities.

@satisfied-by