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

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: https://github.com/tailwindlabs/tailwindcss/discussions/13336#discussioncomment-12046971(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!

About this issue

  • Original URL
  • State: closed
  • Created 2 years ago
  • Reactions: 12
  • Comments: 25 (7 by maintainers)

Most upvoted comments

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

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

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!

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

Hey Adam,

I appreciate your patience on this. I’ve gone through the entire upgrade process step by step and documented everything, including the errors encountered. Below is a structured breakdown of what I did and the results.


Upgrade Process:

  1. Attempted Automated Upgrade:
    • Ran npx @tailwindcss/upgrade@next.
    • Received a bunch of errors that don’t make sense, and the documentation does not explain them.

Image

  1. Performed Manual Upgrade:

    • Installed the latest versions using:
      npm install tailwindcss@latest postcss@latest autoprefixer@latest
      
    • Verified that Tailwind updated to v4 in package.json.
  2. Updated postcss.config.js as per documentation:

    • Modified the config file as required:

Image

  1. Updated Tailwind CSS Files:
    • Adjusted tailwind.css, including setting the new prefix (tw- to tw:):

Image

  • Question: Why was the prefix changed? This makes it harder to read. Can we modify this behavior?
  • Included @config to reference the existing Tailwind configuration:

Image

  1. Confirmed Import of Tailwind Styles in index.ts:
    • The index.ts file explicitly imports tailwind.css:

Image

Clarification: Webpack bundles everything here—this is likely where confusion arose earlier. Apologies for not making that clear before.

  1. Ran Webpack Build (webpack --mode development) and Encountered Errors:
    • Received errors related to @apply failing:

Image

  • If I remove all instances of @apply, Tailwind v4 and Webpack work fine.
  • The issue is specific to @apply—even when placed in a separate CSS file, the error persists.

Key Findings:

  • @apply never works in Tailwind v4 with this setup.
  • Removing @apply entirely allows everything else to work fine.
  • This suggests @apply is fundamentally broken in this environment.
  • Normal Tailwind utility classes work as expected, but @apply is consistently rejected.

Next Steps:

I believe this provides enough detail to investigate further. Given that:

  1. Webpack is properly bundling the CSS into a single output.
  2. Normal Tailwind utility classes work fine.
  3. @apply is completely unusable.

This strongly suggests an issue with Tailwind v4’s handling of @apply, not a scoping issue on my end.

Let me know what additional information you need to proceed.

AND again thanks your time appreciate the efforts!

@JaquesBotha A reproduction using Blazor would be more helpful since that’s the issue you are facing. It’s not clear to me if you’d tried using @reference as we’ve suggested either, and I haven’t gotten a response on how it doesn’t resolve your issue. Again @reference is a real feature of the framework that you are expected to use when referencing theme variables defined in separate CSS entry points.