@applyBroken 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.

[kostekd]

Having the exact same issue right now.

[kostekd]

A workaround, which feels like cheating, is adding a reference to the CSS file with the Tailwind configuration

@reference './../../../globals.css';

The drawback is that you have to reference it in every single file, which is too cumbersome.

[DavidUntama]

Now wint te 4th version of tailwind you don't use @apply inside stryle tag of a component, it must be used in globall.css or another external css, thanks to vite

[lightify97]

@adamwathan

[JaquesBotha]

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

[bakikucukcakiroglu]

Absolutely! I tried to do a quick switch but the whole project is broken. Of course, there should be workarounds but too much effort and I don't have time.

[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.

[bennycode]

@adamwathan the latest version of the upgrade tool (@tailwindcss/upgrade) is broken so it doesn't handle those changes: #17768

[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.

[OliverRC]

I was facing a similar Cannot apply unknown utility class issue and the root cause was because the css I was brining over was relying on custom colour names but I had not defined the css variables in the @theme directive.

[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

[emercab]

It worked for me!

[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.

[shniubobo]

In my case, adding a semicolon solves the problem:

@reference "../style.css";

[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.

[isaacmattern]

I'm having the exact same experience as you - completely unable to get any @apply rules working outside of my main global css fie. What a headache. I expect better from such a widely-used package.

[diegoesolorzano2]

having the same problem, even
.type-h1 {
@apply font-bold;
}

is giving me an error

[matiasvallejosdev]

Adding this @config "../tailwind.config.ts"; into globals.css works.

Is this in the documentation or why happen this?

[philipp-spiess]

Yeah that's the API for loading JS based config files:

• https://tailwindcss.com/docs/functions-and-directives#config-directive
• https://tailwindcss.com/docs/upgrade-guide#using-a-javascript-config-file

[demiro]

I hate it I hate it I hate it!

It's been since Jan, giddily and excited that I am trying to upgrade to v4... constantly failing!

I cannot get over the fact that normal @apply does not work in vue and scss, unless I put @reference there... And even with that, there are a LOT of limitations with some code completion, hmr not always working with styles, etc, etc... such a pain...

I tried various hacks that would deal with @reference in vue files automatically, mediocre success.
This for example, hacky "fix" in vite

 css: {
    preprocessorOptions: {
      scss: {
        additionalData: `
          @use "@/tailwind.css" as *;
        `,
      },
    },
  },

handles that for me, but still I discovered, that for some reason, built-in animations don't work. For example @apply animate-pulse; or similar... (unless I manually put @reference there in specific component at the top of style block - using vue btw)

This is such a fail and disregard from tailwind devs that I am starting to think it is intentional to deter from using @apply...

And to me - this is so backward! I hate endless inline classes, so unreadable. and I hate mixing (coupling) css styling concerns with the template...

I want my css code to be easily readable, nested and completely decoupled from the markup (which is semantic).

I love TailwindCSS, all the color science, the utility aspect of it, short-hands - BRILLIANT.... but forcing using inline functional classes down our throats is a complete smack to our faces!

Edited note: This was written in the heat of the moment out of yet another frustrating sessions. I don't hate it, I promise. Actually I love it and I am so grateful it exists, makes my life soooo much better, even if there are couple of frustrating days here and there ;)

[mavyfaby]

Just use v3 for now

[gregg-cbs]

Dont worry we all feel your frustration. We see the value in v4 and some of its improvements but to use it in an existing v3 project or in a v3 way is a no go. Give it time and let the smart people who work on these things get it there.

Tailwind is used by a lot of ecosystems unfortunately, so its tough to for them to get it right. I dont think they realised how many people are using @apply and to remove it for a micro optimization was a bad call. They should not police people on how they want to compose css. If i want to use @apply and it works for me, let me use it, dont police me.

Save your sanity as we have done and stick with v3.

[nielsNocore]

We also gave it a try. update our 5 blazor project to tailwind 5.0.
Used the @reference. changed the config.js to @theme ect. but failed to get the @apply working in the blazor project css bundle.

[matikotyla]

It really is extremely sad that such a big issue has been around since January and still there is no proper solution. I've been trying to migrate my Next js project to Tailwind v4, and I still can't use @apply in my css / scss modules.

[M1CK431]

as inspriration to solve it: #16429 (comment)

[LuckyArdhika]

It really is extremely sad that such a big issue has been around since January and still there is no proper solution. I've been trying to migrate my Next js project to Tailwind v4, and I still can't use @apply in my css / scss modules.

Its deprecated, @apply didnt available more

[naivefun]

Even with @reference @apply works, it creates a css dependency tree, which will cause the whole app reload when you make any changes. The HMR will simply try to reload from main.css which is usually imported at App.tsx. It's horrible.

[LuckyArdhika]

Mann, debugging some minutes tough my code was wrong🗿

[TeemuKoivisto]

Well, while having to sprinkle @reference everywhere is definitely going to suck at least people should configure path aliases as described here #17127

So add to your package.json eg.

  "imports": {
    "#app.pcss": "./src/app.pcss"
  },

and you can reference the main stylesheet with @reference "#app.pcss";

[M1CK431]

That plugin can do it for you: https://github.com/M1CK431/vite-plugin-vue-tailwind-auto-reference/

[HCenggel]

Then use v3

[selvamk-js]

My custom class inside components is not working correctly. I am getting this error: Cannot apply unknown utility class. The whole V3 to V4 upgrade broke the application. It becomes a frustrating experience. Still trying to make the app work.

[rozsazoltan]

• How do I use tailwindcss @apply directive inside a svelte component <style>
• Using @apply with Vue, Svelte, or CSS modules

[4sllan]

vite: {
        plugins: [
            tailwindcss(),
            {
                name: 'inject-tailwind-reference',
                enforce: 'pre',
                transform(code, id) {
                    if (!id.endsWith('.vue')) return

                    const transformedCode = code.replace(
                        /<style([^>]*)>/g,
                        (match) => `
                        ${match}\n@reference "tailwindcss";
                         @reference "~/assets/css/app.css";
                        `
                    )

                    return {
                        code: transformedCode,
                        map: null, 
                    }
                },
            }
        ],
    },

[M1CK431]

I already published a package for that (and it handle more use case): https://github.com/M1CK431/vite-plugin-vue-tailwind-auto-reference/

[NikitaIT]

disclaimer: I'm still on v3 on prod. So, maybe I'm too green to see how to fix it.

This works for @apply:

/* jsimported_component.css or <style> */
@reference "#global.css";

// package.json
  "imports": {
    "#global.css": "./src/styles/global.css"
  }

But previously css was scanned for @layer components and etc.

Now if we do:

/* jsimported_component.css or <style> */
@reference "#global.css";

@theme {
  --color-my-component-color: blue;
}

@utility lalala-utility {
 color: white;
}

.lalala {
 color: white;
 @apply bg-white;
}

It would compile to:

.lalala {
 color: white;
 background-color: white;
}

[vanditpatel22]

transform -translate-x-1/2 is not working in tailwind v4 ?

[RobinMalfait]

It does work https://play.tailwindcss.com/s7j2OznKpS

[doutatsu]

Dropping in here to keep track of this - until @apply can be used as is again, it does seem like upgrading to v4 is impossible (or rather, I don't want to be using these @reference workarounds, which feels so hacky and annoying. It's truly a shame

[yuruyu6]

Maybe someone will find this useful.

I also encountered this problem after manually upgrading to version 4 in my Svelte repo.
However, I reverted to the last commit, ran npx @tailwindcss/upgrade, and everything worked fine.

[User00015]

I was just bit by this issue after upgrading to 4.0 as well, so throw my ticket in with the rest of "Hey, what?"

I'm fine with losing @apply, but there doesn't seem to be any clear documentation or indication of what's happening and why it's failing. Whatever approach you do end up taking, the communication about this change is actually deeply impactful and doesn't seem to have propagated to the users. The only reason I noticed the issue was due to errors being thrown due to the v4 changes in my build log.

As far as defending @apply: sometimes I like to write these strings of TW classes because I intend to re-use them pretty regularly, especially if I want to establish styling standards. For example, if I always want certain text to appear with a certain font, size, color, line-height, etc..., I don't want to repeat X atomic styles, I just want to use ".text-paper" and easily introduce a certain text style, using @apply to build the actual effect. Saves a lot of my developers time and keeps things distinct, compared to a dev mixing up line-heights or getting the font wrong, or just flipping class names around so two components read differently but look the same.

It's useful in the right cases, and there should be some documentation on how it should work, what you plan to do with it, and how we can migrate off it in the instance you want to remove it in favor of optimizations.

[RobinMalfait]

@apply still works and is not going away. But you just need to point to your CSS file from your <style> blocks. We documented that here: https://tailwindcss.com/docs/upgrade-guide#using-apply-with-vue-svelte-or-css-modules

You can think of it this way, let's imagine you use a JavaScript function from a different file:

myFunctionFromAnotherFile()

Then that's going to throw an error because whatever tool is processing that file won't know about that function. So to solve it, you reference the file:

+ import { myFunctionFromAnotherFile } from "./other"

  myFunctionFromAnotherFile()

And that is the only thing you have to do as well:

  <template>
    <h1>Hello world!</h1>
  </template>
  <style>
+   @reference "../../app.css";

    h1 {
      @apply text-2xl font-bold text-red-500;
    }
  </style>

[vzakharov]

That actually would be great — the only catch is that it still does not work (at least not for me). I’ve since left that project so can’t double check, but back there I “just” redefined everything I wanted to apply as scss mixins. Maybe for the better sighs

[User00015]

I think I see the issue now. To be clear, Tailwind is amazing and a lot of us greatly appreciate the time and energy you spend maintaining the project. With that said, the reason I ran into this issue is because the general documentation doesn't list this as a requirement for my particular environment, and because it previously worked fine, didn't occur to me to be necessary. Here's what I mean:

In the current documentation, @apply appears to work as it did in v3, and below it @reference says this

If you want to use @apply or @variant in the <style> block of a Vue or Svelte component, or within CSS modules

I am not using Vue or Svelte or CSS modules, I am using Angular. The way the documentation is worded, @apply works out of the box as expected from v3, and only those use cases need to modify their behaviors to use @apply in v4. From my understanding, Angular uses native import syntax, so the documentation implies this step isn't necessary for Angular going from v3 to v4.

I think an update to the reference documentation to make this more clear would help out.

[M1CK431]

As I previously suggested, in JS we have tools to "auto-import" commonly used things (unplugin-auto-import is a great example of this). We can also use window as a global, shared context.

So, IMHO, the missing piece here is a way to globally manage which CSS file(s) should be (auto) referenced in specific <style> blocks. That's why I developed and published a Vite plugin for Vue users that provides exactly this feature: https://github.com/M1CK431/vite-plugin-vue-tailwind-auto-reference

Notice that it has a lot of options to customize it's behavior and might be working for other frameworks too. Anyway, it's code could be a good starting point if you want to adapt it for your use case.
Would you like to give it a try?

[Padi2312]

@RobinMalfait I really like the way TailwindCSS is working but lets be honest.
This can't be the solution ... who wants to import @reference "../../app.css" in every style tag for just using @apply ?
It gets even worse if you have a deeply nested project structure like it's getting to ../../../../../../../../../../../app.css