CSS Modules Composition Extractor

A PostCSS plugin that transforms CSS Modules composes declarations into :import() rules, with support for nested rules.

Overview

When CSS contains composes: className from "file.css" declarations, this plugin extracts them into separate :import() rules at the top of the CSS, replacing the original class names with unique identifiers. The plugin must correctly handle nested CSS rules by tracking parent-child relationships.

Capabilities

Transform simple compositions

• It transforms a basic composition from an external file into an import rule @test

Handle nested rules

• It processes nested rules with compositions, maintaining separate import contexts @test
• It handles multiple nested levels with different composition sources @test

Implementation

@generates

The plugin processes composes declarations by:

1. Parsing the composition source (file path or global)
2. Generating unique identifiers for imported class names
3. Creating :import() rules for external files
4. Replacing composed class names with the generated identifiers
5. Tracking parent rules to maintain correct import scoping for nested selectors

API

/**
 * Creates a PostCSS plugin that extracts CSS Modules compositions
 *
 * @returns {object} A PostCSS plugin compatible with PostCSS 8.x
 */
function extractCompositions() {
  // Returns PostCSS plugin object
}

module.exports = extractCompositions;

Dependencies { .dependencies }

postcss-modules-extract-imports { .dependency }

A PostCSS plugin for transforming CSS Modules composes declarations into import rules.