feat(v4): support CSS directives

README.md

@@ -63,6 +63,22 @@ export default {
 
 This will be auto-loaded by Rsbuild and applied by `rsbuild-plugin-tailwindcss`.
 
+### CSS directives (`@apply`, `@variant`, etc.)
+
+This plugin automatically wires the official `@tailwindcss/postcss`
+plugin into Rsbuild's PostCSS pipeline, so Tailwind CSS
+directives like `@apply`, `@variant`, `@utility`, and `@custom-variant` work out of the box without extra
+configuration.
+
+```css
+/* src/styles.css */
+@import "tailwindcss/utilities" layer(utilities);
+
+.btn {
+  @apply px-4 py-2 rounded bg-blue text-white;
+}
+```
+
 ### Custom theme with `@theme`
 
 Tailwind CSS v4 also lets you define design tokens using the `@theme` directive in a CSS file.

package.json

@@ -33,16 +33,17 @@
   "dependencies": {
     "@alloc/quick-lru": "^5.2.0",
     "@tailwindcss/node": "^4.2.1",
-    "@tailwindcss/oxide": "^4.2.1"
+    "@tailwindcss/oxide": "^4.2.1",
+    "@tailwindcss/postcss": "^4.2.1"
   },
   "devDependencies": {
     "@biomejs/biome": "^1.9.4",
     "@playwright/test": "^1.58.2",
     "@rsbuild/core": "2.0.0-beta.4",
     "@rsdoctor/rspack-plugin": "^1.5.2",
     "@rslib/core": "^0.19.5",
-    "@tailwindcss/postcss": "^4.2.1",
     "@types/node": "^22.19.11",
+    "postcss": "^8.5.6",
     "simple-git-hooks": "^2.13.1",
     "tailwindcss": "^4.2.1",
     "typescript": "^5.9.3"

src/index.ts

@@ -5,6 +5,7 @@ import { pathToFileURL } from 'node:url';
 import type { RsbuildPlugin } from '@rsbuild/core';
 import { cleanupCache } from './compiler.js';
 import type { TailwindCSSLoaderOptions } from './loader.js';
+import { tailwindPostCSSPlugins } from './postcss.js';
 
 const VIRTUAL_UTILITIES_ID = '/virtual-tailwindcss/utilities.css';
 const VIRTUAL_GLOBAL_ID = '/virtual-tailwindcss/global.css';
@@ -123,7 +124,10 @@ export const pluginTailwindCSS = (
   setup(api) {
     const require = createRequire(import.meta.url);
     const config = options?.config ?? 'tailwind.config.js';
-    const theme = options?.theme ?? require.resolve('tailwindcss/theme');
+    let theme = options?.theme ?? require.resolve('tailwindcss/theme');
+    if (!path.isAbsolute(theme)) {
+      theme = path.resolve(api.context.rootPath, theme);
+    }
     const preflight = require.resolve('tailwindcss/preflight');
     const utilities = require.resolve('tailwindcss/utilities');
 
@@ -142,6 +146,11 @@ export const pluginTailwindCSS = (
           source: {
             preEntry: [pathToFileURL(VIRTUAL_GLOBAL_ID).toString()],
           },
+          tools: {
+            postcss(_, { addPlugins }) {
+              addPlugins(tailwindPostCSSPlugins({ theme }), { order: 'pre' });
+            },
+          },
         },
         config,
       );

src/postcss.ts

@@ -0,0 +1,36 @@
+import tailwindcss from '@tailwindcss/postcss';
+import type { AcceptedPlugin, Plugin, PluginCreator } from 'postcss';
+
+export interface TailwindCSSPostCSSOptions {
+  theme: string;
+}
+
+const injectTailwindThemePlugin: PluginCreator<TailwindCSSPostCSSOptions> = (
+  options?: TailwindCSSPostCSSOptions,
+): Plugin => {
+  const themePath = options?.theme.replace(/\\/g, '/');
+
+  return {
+    postcssPlugin: 'rsbuild-inject-tailwind-theme',
+
+    Once(root, { AtRule }) {
+      if (!themePath) {
+        return;
+      }
+      root.prepend(
+        new AtRule({
+          name: 'import',
+          params: JSON.stringify(themePath),
+        }),
+      );
+    },
+  };
+};
+
+injectTailwindThemePlugin.postcss = true;
+
+export function tailwindPostCSSPlugins(
+  options: TailwindCSSPostCSSOptions,
+): AcceptedPlugin[] {
+  return [injectTailwindThemePlugin(options), tailwindcss()];
+}

test/css-directives/index.test.ts

@@ -0,0 +1,56 @@
+import { dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { expect, test } from '@playwright/test';
+import { createRsbuild } from '@rsbuild/core';
+
+import { pluginTailwindCSS } from '../../src';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+test('supports CSS directives (@apply, @utility, @variant, @custom-variant)', async ({
+  page,
+}) => {
+  const rsbuild = await createRsbuild({
+    cwd: __dirname,
+    rsbuildConfig: {
+      plugins: [pluginTailwindCSS()],
+    },
+  });
+
+  const { close } = await rsbuild.build();
+  const { server, urls } = await rsbuild.preview();
+
+  try {
+    await page.goto(urls[0]);
+
+    // @apply turns the `.btn` utility into real CSS.
+    await expect(page.locator('#apply-test')).toHaveCSS('display', 'flex');
+
+    // @utility registers custom utilities that can be used from HTML.
+    await expect(page.locator('#utility-test')).toHaveCSS(
+      'outline-style',
+      'solid',
+    );
+
+    // @custom-variant + Tailwind utilities (theme-midnight:bg-black).
+    await expect(page.locator('#custom-variant-utility')).toHaveCSS(
+      'background-color',
+      'rgb(0, 0, 0)',
+    );
+
+    // @variant used with a custom variant defined via @custom-variant.
+    await expect(page.locator('#custom-variant-css')).toHaveCSS(
+      'color',
+      'rgb(0, 0, 255)',
+    );
+
+    // @variant hover used inside custom CSS.
+    const card = page.locator('#variant-test');
+    await card.hover();
+    await expect(card).toHaveCSS('background-color', 'rgb(0, 0, 0)');
+  } finally {
+    await server.close();
+    await close();
+  }
+});

test/css-directives/src/app.css

@@ -0,0 +1,34 @@
+@import "tailwindcss/utilities.css" layer(utilities);
+
+@custom-variant theme-midnight {
+  &:where([data-theme="midnight"] *) {
+    @slot;
+  }
+}
+
+@utility debug-border {
+  outline-width: 3px;
+  outline-style: solid;
+}
+
+.btn {
+  @apply flex;
+}
+
+.card {
+  background-color: white;
+  width: 120px;
+  height: 60px;
+
+  @variant hover {
+    background-color: black;
+  }
+}
+
+.link {
+  color: red;
+
+  @variant theme-midnight {
+    color: blue;
+  }
+}

test/css-directives/src/index.js

@@ -0,0 +1,31 @@
+import './app.css';
+
+const root = document.getElementById('root');
+
+// Enable our custom `theme-midnight` variant.
+document.documentElement.setAttribute('data-theme', 'midnight');
+
+const applyElement = document.createElement('div');
+applyElement.id = 'apply-test';
+applyElement.className = 'btn';
+root.appendChild(applyElement);
+
+const utilityElement = document.createElement('div');
+utilityElement.id = 'utility-test';
+utilityElement.className = 'debug-border';
+root.appendChild(utilityElement);
+
+const customVariantUtilityElement = document.createElement('div');
+customVariantUtilityElement.id = 'custom-variant-utility';
+customVariantUtilityElement.className = 'theme-midnight:bg-black';
+root.appendChild(customVariantUtilityElement);
+
+const customVariantCssElement = document.createElement('div');
+customVariantCssElement.id = 'custom-variant-css';
+customVariantCssElement.className = 'link';
+root.appendChild(customVariantCssElement);
+
+const variantElement = document.createElement('div');
+variantElement.id = 'variant-test';
+variantElement.className = 'card';
+root.appendChild(variantElement);

test/functions/config/functions-theme.css

@@ -1,15 +1,5 @@
-@import "tailwindcss/theme" layer(theme);
+@import "tailwindcss/theme";
 
 @theme {
   --color-functions-alpha: #ff0000;
 }
-
-@layer components {
-  .alpha-text {
-    color: --alpha(var(--color-functions-alpha) / 50%);
-  }
-
-  .spacing-box {
-    margin-top: --spacing(4);
-  }
-}

test/functions/src/components.css

@@ -0,0 +1,9 @@
+@layer components {
+  .alpha-text {
+    color: --alpha(var(--color-functions-alpha) / 50%);
+  }
+
+  .spacing-box {
+    margin-top: --spacing(4);
+  }
+}

test/functions/src/index.js

@@ -1,3 +1,5 @@
+import './components.css';
+
 const root = document.getElementById('root');
 
 const alphaElement = document.createElement('div');