@accelint/postcss-tailwind-css-modules

A PostCSS plugin that wraps Tailwind CSS group/ and peer/ classes in :global() pseudo-class to fix compatibility issues with CSS Modules.

Overview

This plugin uses postcss-selector-parser to wrap specific class nodes in a :global() pseudo-class, solving issues with Tailwind's parent state utilities when used with CSS Modules.

Problem

Tailwind has utilities for styling based on parent state and styling based on sibling state. However, these utility classes rely on global classes. Without this plugin, CSS Modules hashes these classes, breaking Tailwind's parent/sibling state functionality.

Transformation Examples

Before and After

Without this plugin:

With this plugin:

Installation

pnpm add -D @accelint/postcss-tailwind-css-modules

Or with npm:

npm install --save-dev @accelint/postcss-tailwind-css-modules

Usage

Turbo and Webpack

Add this plugin to your PostCSS config. It must come after the Tailwind PostCSS plugin.

// postcss.config.js
export default {
  plugins: {
    '@tailwindcss/postcss': {},
    '@accelint/postcss-tailwind-css-modules': {},
  },
};

Vite

Continue to use the Tailwind Vite plugin in your vite.config.js.

Your postcss.config.js file only needs this plugin, as Tailwind's PostCSS processing is included in their Vite plugin.

// postcss.config.js
export default {
  plugins: {
    '@accelint/postcss-tailwind-css-modules': {},
  },
};

[!NOTE] The array syntax for PostCSS plugin configuration does not work with Vite. Using plugins: ['@accelint/postcss-tailwind-css-modules'] will cause errors. Use the object syntax shown above.

How It Works

The plugin:

1. Only processes files ending in .module.css
2. Finds all Tailwind group/ and peer/ classes in your CSS selectors
3. Wraps them in :global() pseudo-class to prevent CSS Modules from hashing them
4. Ensures each rule is transformed only once using symbol-based tracking

Input:

.group/sidebar {
  /* styles */
}

.peer/checked {
  /* styles */
}

Output:

:global(.group/sidebar) {
  /* styles */
}

:global(.peer/checked) {
  /* styles */
}

Supported Classes

The plugin wraps the following Tailwind parent state classes:

• group/ classes
• peer/ classes

Requirements

• Node.js >= 22
• pnpm >= 10
• PostCSS ^8.5.6
• postcss-selector-parser ^7.1.1

License

Apache-2.0