tailwind-reference-injector

A PostCSS plugin that automatically injects @reference directives in CSS modules for Tailwind CSS v4.

Why?

In Tailwind CSS v4, when using @apply, @variant, @custom-variant, @plugin, or @config inside CSS modules or Vue/Svelte <style> blocks, you need to add @reference to make theme variables, custom utilities, and custom variants available.

This plugin automates that process by detecting files that need it and injecting @reference automatically.

Installation

npm install tailwind-reference-injector --save-dev
# or
yarn add tailwind-reference-injector -D
# or
pnpm add tailwind-reference-injector -D

Usage

With PostCSS config

// postcss.config.cjs
module.exports = {
  plugins: {
    'tailwind-reference-injector': {},
    '@tailwindcss/postcss': {},
  },
}

With subpath imports (recommended)

First, set up a subpath import in your package.json:

{
  "imports": {
    "#global-styles": "./src/styles/globals.css"
  }
}

Then configure the plugin:

// postcss.config.cjs
module.exports = {
  plugins: {
    'tailwind-reference-injector': {
      reference: '"#global-styles"',
    },
    '@tailwindcss/postcss': {},
  },
}

With relative path to globals.css

// postcss.config.cjs
const path = require('path')

module.exports = {
  plugins: {
    'tailwind-reference-injector': {
      globalsCssPath: path.join(__dirname, 'src/styles/globals.css'),
    },
    '@tailwindcss/postcss': {},
  },
}

Using default Tailwind (no customizations)

If you're only using the default Tailwind theme with no customizations:

// postcss.config.cjs
module.exports = {
  plugins: {
    'tailwind-reference-injector': {
      reference: '"tailwindcss"',
    },
    '@tailwindcss/postcss': {},
  },
}

Options

| Option | Type | Default | Description | | ---------------- | -------- | -------------------- | --------------------------------------------------------------------------------------------------------------------------------------- | | reference | string | '"#global-styles"' | The reference import path. Use subpath imports like "#global-styles" or "tailwindcss" for default theme. | | globalsCssPath | string | null | Absolute path to your globals.css file. The plugin will calculate relative paths for each CSS module. Used when reference is not set. |

How it works

1. Detects .module.css files during PostCSS processing
2. Checks if the file uses Tailwind directives that require context:
   • @apply
   • @variant
   • @custom-variant
   • @plugin
   • @config
3. If needed and not already present, injects @reference at the top of the file
4. Respects @charset declarations (keeps them first if present)

Example

Input (Button.module.css):

.button {
  @apply bg-blue-500 text-white px-4 py-2 rounded;
}

Output (after processing):

@reference "#global-styles";

.button {
  @apply bg-blue-500 text-white px-4 py-2 rounded;
}

Requirements

• Node.js >= 18.0.0
• PostCSS >= 8.0.0
• Tailwind CSS v4

License

MIT