How to use @apply in Tailwind v4?

Question

Since Tailwind v4 update, all @apply directives have ceased to function.

The docs provide a workaround with @reference but the posted example is vague.

I tried this but it doesn't work:

<style lang="postcss">
// @reference './../../assets/styles/scss/main.scss'; // workaround (incorrect)
@reference "tailwindcss"; // should be sufficient

header {
  @apply bg-neutral-0; // used to work in Tailwind v3
}
(...)
</style>

When I inspect the Header in the browser, it doesn't have assigned any background color.

Edit. I was missing @tailwindcss/vite but some utility classes still don't work. I.e. @apply block works, but @apply bg-neutral-0 doesn't. It throws an error:

19:26:13 [vite] (client) hmr update /src/components/Header.vue?vue&type=style&index=1&lang.postcss (x2)  
Error: Cannot apply unknown utility class `bg-neutral-0`. Are you using CSS modules or similar and missing `@reference`? https://tailwindcss.com/docs/functions-and-directives#reference-directive

Answer 1

In fact, the primary recommendation from the creator of TailwindCSS is not to use @apply. Instead, use native CSS and achieve the required color codes or values through variables. The main goal of TailwindCSS is to provide styling through inline classes. I only mentioned this because if you don't force local formatting on the header, and instead simply apply bg-neutral-0 to the header element, it will work without issues.

Now, let's deal with @apply. If you use @reference "tailwindcss";, you only have access to the default values, not the ones you defined yourself. To access your own values, such as --color-neutral-0, you need to reference your main CSS file, just like you did in the first line, and this has to be done with a relative reference.

• Sass and TailwindCSS v4 don't work together, but can be used separately - How to use with CSS modules (*.module.css and <style>), @reference, @apply

./assets/styles/scss/main.scss

$primary: #42b883;

body {
  background: $primary;
}

./assets/styles/css/tailwind.css

@import "tailwindcss";

@theme {
  --color-neutral-0: #111;
}

You need to include styles.scss and tailwind.css as separate files in the project. They must not interact with each other or be nested into one another.

./assets/main.ts

import "./styles/scss/main.scss";
import "./styles/css/tailwind.css";

Header.vue

<style lang="postcss">
@reference "./../../assets/styles/css/tailwind.css";

header {
  @apply bg-neutral-0;
}
</style>

I fully agree with Wongjn's explanations. If you set it up so that you can reference a CSS file, since TailwindCSS does not officially support Sass, Less, or Stylus preprocessors, the relative reference will solve your problem. However, instead of using a relative reference, I would create a reference to tailwind.css in package.json and use that in @reference. This way, the result will be much cleaner.

• Use Vite aliases with TailwindCSS @reference directive

package.json

// package.json
{
  "imports": {
    "#tailwind.css": "./assets/styles/css/tailwind.css"
  },
} 

Header.vue

<style lang="postcss">
@reference "#tailwind.css";

header {
  @apply bg-neutral-0;
}
</style>

Answer 2

The file that you point to @reference must be a CSS file, not a SCSS file. This CSS file should contain @import "tailwindcss"; or similar. The @reference processing is done entirely through Tailwind and it does not understand any other preprocessor syntaxes.

As per the documentation:

Tailwind CSS v4.0 is a full-featured CSS build tool designed for a specific workflow, and is not designed to be used with CSS preprocessors like Sass, Less, or Stylus.

Think of Tailwind CSS itself as your preprocessor — you shouldn't use Tailwind with Sass for the same reason you wouldn't use Sass with Stylus.

As a workaround, you can try having your Tailwind-related CSS in its own CSS file:

@import "tailwindcss";

@theme {
  …
}

And @import/@use that into your main.scss file:

@import "./path/to/subfile.css";

Then, you can do:

<style lang="postcss">
@reference './../../assets/styles/scss/path/to/subfile.css';

header {
  @apply bg-neutral-0;
}
(...)
</style>

Though as mentioned, this is not guaranteed to work as Tailwind does not support usage with Sass.

It is worth mentioning, Adam Wathan (creator of Tailwind) does seem to advocate avoiding @apply:

• https://twitter.com/adamwathan/status/1226511611592085504
• https://twitter.com/adamwathan/status/1559250403547652097
• https://x.com/adamwathan/status/1890406016291938701

Instead, you should look at using Tailwind class names directly:

<header class="bg-neutral-0">
  …
</header>

If your project fully encompasses this paradigm, you may find you write little CSS yourself. Thus you would not need Sass at all, simplifying the project setup.