`@apply`Broken in Tailwind CSS v4.0 – No Clear Fix or Docs!

[JaquesBotha]

Tailwind CSS v4.0 @apply Bug Report

Introduction

I'm in the process of upgrading a large project, actually, five Blazor projects that all conjoin into one via components and different backends. Our focus with this project is to deliver an optimal UI experience to the end-user, which is why we use TypeScript, C#, and of course, our favorite, Tailwind CSS. Btw, huge fans!

Now, with that said, we have certain native components where we cannot add CSS classes to the component itself, making @apply an essential part of our workflow. However, after upgrading to Tailwind CSS v4.0, @apply is no longer working as expected, and there seems to be little guidance on how to transition projects that rely on it. This bug report aims to outline the issue clearly and request either a fix or detailed documentation on what exactly we need to do to overcome this.

What version of Tailwind CSS are you using?

v4.0.0

What build tool (or framework if it abstracts the build tool) are you using?

Webpack 5.97.1

What version of Node.js are you using?

v20.11.1

What version of npm are you using?

v10.7.0

What IDE are you using?

Rider IDE

What operating system are you using?

macOS

Reproduction URL

There's an active discussion on this issue where many developers are experiencing the same problem but no one has officially reported it yet. Rather than debating, I’d rather get a solution, so here’s the link to the discussion: #13336 (comment)(https://github.com/yourusername/tailwind-v4-apply-issue)

Describe your issue

After upgrading to Tailwind CSS v4.0, I encountered the following issues:

1. @apply Directive Not Functioning

• The @apply directive, previously used extensively in our CSS for class composition, no longer functions as expected.

• Example:

  .quickgrid thead th {
      @apply tw-bg-slate-100 dark:tw-bg-slate-800/70 tw-py-4;
  }

  • This results in build errors indicating unknown utility classes such as:

  Error: Cannot apply unknown utility class: tw-transform
  Error: Cannot apply unknown utility class: tw-table-auto
  

2. Lack of Clear Documentation for @apply Usage in v4.0

• The v4.0 documentation does not provide explicit guidance on how to use the @apply directive in non-Vue projects.
• One part of the documentation states that @apply should still work, but this is only relevant for Vue projects.
• Another section in the documentation (CSS Modules Compatibility) suggests using CSS variables instead:

  background: var(--color-blue-500);

  • This is not an ideal solution because it significantly increases the workload, especially in large projects where @apply is heavily used.

3. Backward Compatibility with tailwind.config.js

• The tailwind.config.js file appears to be deprecated or its usage has changed in v4.0 without clear documentation.
• Projects relying on configurations such as prefix: 'tw-' are experiencing issues with styles not applying correctly.

4. @apply is Necessary for Native Blazor QuickGrid Components

• In my case, I use @apply with Native Blazor QuickGrid components, where there is no alternative way to apply Tailwind classes.
• The current documentation does not provide any solutions for frameworks outside of Vue.

Expected Outcome

• A fix for @apply so that it functions as expected in Tailwind CSS v4.0.
• Clear documentation outlining the necessary steps to transition existing projects that rely on @apply.
• An explicit guide on how tailwind.config.js should be updated for v4.0.

---

Thank you for your attention to this issue!

[lightify97]

@JaquesBotha having the same issue. It's a really frustrating experience.

[lightify97]

@adamwathan

[JaquesBotha]

Right on! Its like the 4.0 shift was rushed. Too many major changes without proper testing

[lightify97]

@JaquesBotha I think going back to V3 is the best choice here.

[adamwathan]

We missed the prefix changes in the upgrade guide, will make a note to add that. The automated upgrade tool should handle those changes for you though if you haven't tried it.

The main difference is prefixes look like variants now and always go at the beginning:

  .quickgrid thead th {
-     @apply tw-bg-slate-100 dark:tw-bg-slate-800/70 tw-py-4;
+     @apply tw:bg-slate-100 tw:dark:bg-slate-800/70 tw:py-4;
  }

Here's the general documentation for the prefix option:

https://tailwindcss.com/docs/styling-with-utility-classes#using-the-prefix-option

I'm not sure how Native Blazor QuickGrid components work but if the CSS for each component is bundled individually the way CSS modules/Svelte/Vue/Astro style blocks are, you may also need to use the @reference option to make sure your theme variables are imported in the right scope:

https://tailwindcss.com/docs/functions-and-directives#reference-directive

Quick search makes me suspect this may be the case because of this CSS isolation functionality, which implies every stylesheet is processed independently with no knowledge of any other stylesheets.

[TGlide]

its also happening with me, without prefixes. Using Svelte

[JaquesBotha]

Response to Tailwind Developer on @apply and Blazor Compatibility

Hey there,

Thanks for the response! I appreciate the clarification on the prefix changes, and I see how that aligns with the new variant structure. That said, the prefix change is really just a small part of the bigger issue I'm facing with Tailwind v4.0 in a Blazor Server environment.

Blazor Is Not Vue (Or Other Scoped CSS Environments)

I noticed in your response that you referenced Blazor QuickGrid's CSS isolation as being similar to how Vue, Svelte, and Astro process styles. However, this assumption isn't entirely accurate for Blazor Server (which is what I'm using) in conjunction with Webpack, TypeScript, and PostCSS.

• In Blazor Server, we do not have component-scoped styles the way Vue, Svelte, or Astro do.
• CSS files are bundled traditionally via Webpack/PostCSS, meaning every Tailwind utility class should be accessible globally unless something is actively blocking them.
• There’s no automatic "style scoping" in Blazor Server that would prevent @apply from working. In fact, @apply has worked flawlessly in previous versions of Tailwind, making this a regression rather than a Blazor-specific issue.

Why @reference Isn’t a Solution Here

I’ve already tried using @reference as suggested, but it does not resolve the issue. If Blazor Server worked like Vue, I would expect:

1. Tailwind to correctly apply styles within each scoped CSS file.
2. A missing reference to cause an explicit error, rather than breaking @apply entirely.

Neither of these behaviors are happening. Instead, @apply is failing even in cases where the styles should be globally accessible.

What I Need from Tailwind

Rather than focusing on workarounds (like @reference or changing the prefix), I need a clear explanation of why @apply is breaking even in non-scoped, globally processed CSS.

• Is this an intentional limitation in Tailwind v4.0, or an unintended side effect?
• If this is an intended change, what is the exact migration path for users who rely on @apply in a global CSS setup?
• If this is a bug, what information do you need to reproduce and resolve it?

Again, I really appreciate the work the Tailwind team is doing. I just want to make sure that this upgrade doesn’t break workflows that were previously supported—especially in frameworks like Blazor Server where @apply is an essential tool.

Looking forward to your insights!

[adamwathan]

@JaquesBotha If the CSS is truly one global stylesheet (all of the stylesheets from your components are concatenated into a single stylesheet before being passed to Tailwind for processing) then everything should work exactly as it did before.

The key thing to understand is for things like @apply bg-red-500 to work, --color-red-500 needs to be defined as a theme variable. In v3 and earlier, the tailwind.config.js file was an assumed convention, and even though scoped styles were all processed independently in v3 as well, we could automatically pick up that config file for each independently processed stylesheet by convention alone.

In v4 with configuration moving to CSS, we can't make assumptions about what your CSS file is called or where it lives, so if you have custom configuration in one CSS file that you need available in another CSS file, you need to explicitly import it using @reference, just like you how you import functions in other programming languages.

So the issue isn't to do with "scoping" it's just whether the CSS is actually processed together as one big stylesheet, or if each stylesheet is being processed one by one without the rules from the other stylesheets being present.

Imagine you have these two stylesheets:

/* one.css */
@import "tailwindcss";

@theme {
  --color-potato: #d2a062;
}

/* two.css */
.foo {
  @apply bg-potato;
}

If these files are conceptually processed independently, sort of like this:

npx @tailwindcss/cli -i one.css -o one.dist.css
npx @tailwindcss/cli -i two.css -o two.dist.css

...you'll get an error when compiling two.css because --color-potato does not exist. It's as if the files are on totally separate computers, there is nothing linking them if they are compiled separately.

This however of course will work fine:

/* everything.css */
@import "tailwindcss";

@theme {
  --color-potato: #d2a062;
}

.foo {
  @apply bg-potato;
}

npx @tailwindcss/cli -i everything.css -o everything.dist.css

...because now --color-potato is defined since it's all one build.

Imagine you had one project that had a client.css file for the client and an admin.css for your internal backed, and both of them defined a custom --color-primary:

/* client.css */
@import "tailwindcss";

@theme {
  --color-primary: blue;
}


/* admin.css */
@import "tailwindcss";

@theme {
  --color-primary: red;
}

Now you have some other component CSS file like this:

/* foo.css */
.foo {
  @apply bg-primary;
}

Is that supposed to be blue or red? It's impossible to know because the color isn't defined and we have no way of making any assumption about what it should be. We could in v3 because of the global tailwind.config.js file, but again in v4 there's no concept of a magic autodetected primary CSS file to automatically use as the context for every other CSS file in the project.

But you're saying that the CSS is global and they aren't processed independently, so what do you mean exactly when you say "@apply is breaking"? Is there an error message? What does the error say?

If you can provide a reproduction we can boot up a Windows environment and take a look. It might be a bug if the CSS truly is all concatenated together and processed as one stylesheet but the fact that @apply isn't working really makes me think Blazor is processing each stylesheet independently.

[codepilotsf]

In Rails, with v4, we get a stylesheets/application.css and a tailwind/application.css. All @apply directives in my stylesheets/application.css are silently ignored. They just don't do anything. Using @apply in my tailwind/application.css works as expected.

[mohamad68]

I have dozens of Vue components with @apply in the <style> tags. I tried adding @import and @reference, but it's still not working. It should either restore @apply support without needing any extra imports or automatically upgrade and handle @apply to make it work again.

[adamwathan]

I have dozens of Vue components with @apply in the <style> tags. I tried adding @import and @reference, but it's still not working. It should either restore @apply support without needing any extra imports or automatically upgrade and handle @apply to make it work again.

@mohamad68 Can you please provide a reproduction? Here's a Vue + v4 project where it is working as expected:

https://github.com/adamwathan/vue-v4-apply

[neonelemental]

@adamwathan That's actually broken, but it's a subtle difference to what you've got here that produces the issue. I'm not sure exactly what the issue is, but if you render a component with the @reference and @apply rather than doing it in App.vue, you'll see that @apply is not working in the component context.

To reproduce the error in your example app, I made the following changes:

// in App.vue

<script setup>
import TestComponent from './components/TestComponent.vue'
</script>

<template>
  <div>
    <TestComponent/>
  </div>
</template>

// in components/TestComponent.vue

<template>
    <h1 class="test">
        Test
    </h1>
</template>

<style scoped>
@reference '../style.css'

.test {
    @apply text-red-500 text-4xl;
}

// or this, which didn't work for me either...

h1 {
   @apply text-red-500 text-4xl;
}
</style>

The result is that the text in the h1 is neither large nor red as I specified in the @apply statement.

[neonelemental]

@adamwathan Hmm, I toyed around with this and it's kind of flakey. I played around some more with this and got the applies to work copy-pasting your example applies. I'm not really sure what's going on there, but I can confirm I have seen this both not work and work.

I don't know if there's something going on with vite, but when I pulled this down and added the above code, it did not work. At some point I moved some files around and copy-pasted code, and it started working and I was unable to reproduce what I was originally seeing (small, black text instead of 4xl red text)

[neonelemental]

I'm not 100% sure what the intended behavior is for @apply, I'm just started using tailwind on a personal project and have only ever used tailwind 4. Here's what I am observing. If I comment out the applies in App.vue and add the component for TestComponent, it will render the basic black text. Once I uncomment the App.vue references, all the sudden things start working again, but then I cannot change colors.

My advice would be to take 2 components and add @reference and @apply and start making changes:

1. Try changing one to blue, one to red
2. Try changing one to using a class definition and one to using an element definition
3. Comment things out and uncomment things.

I can't get it to behave consistently at all, and it definitely feels like <style scoped> is not working, because to me it seems like they're interfering with each other, which you would not really expect.

[loukamb]

I can also attest that my website (using Astro) has broken in a re-deployment that installed the latest minor version of Tailwind (worked fine on 4.0.3, has problems on latest). Despite no code changes on my end, variables in non-root stylesheets such as var(--text-3xl) simply ceased to exist after the minor update, even though I inserted a @reference statement at the top of said stylesheets to make sure that statements such as @apply text-3xl would receive styling. This pretty much broke my entire blog layout, as well as the layout of two other sites I am also maintaining.

I find it quite impressive that a project as large as Tailwind wasn't able to catch a significant regression in a minor version update (as stated above, it worked fine on 4.0.3, but broke on latest). I am not alone in finding the Tailwind 4.0 "improvements" to be more providing of frustration than anything else, even after consulting the documentation and following the upgrade process correctly. Apparently, my patience in upgrading correctly has been punished with 4.0 minor updates randomly breaking my website if I dare re-deploy.

For now, I will mitigate these problems by pinning my dependencies to 3.0 for each of the projects mentioned above. I would consider re-categorizing 4.0 as a beta (again) until it becomes appropriate for production use.