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
@applydirective, 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
@applydirective in non-Vue projects. - One part of the documentation states that
@applyshould 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
@applyis heavily used.
- This is not an ideal solution because it significantly increases the workload, especially in large projects where
3. Backward Compatibility with tailwind.config.js
- The
tailwind.config.jsfile 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
@applywith 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
@applyso 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.jsshould 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)
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
@applyand Blazor CompatibilityHey 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.
@applyfrom working. In fact,@applyhas worked flawlessly in previous versions of Tailwind, making this a regression rather than a Blazor-specific issue.Why
@referenceIsn’t a Solution HereI’ve already tried using
@referenceas suggested, but it does not resolve the issue. If Blazor Server worked like Vue, I would expect:@applyentirely.Neither of these behaviors are happening. Instead,
@applyis failing even in cases where the styles should be globally accessible.What I Need from Tailwind
Rather than focusing on workarounds (like
@referenceor changing the prefix), I need a clear explanation of why@applyis breaking even in non-scoped, globally processed CSS.@applyin a global CSS setup?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
@applyis 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:
npx @tailwindcss/upgrade@next.Performed Manual Upgrade:
package.json.Updated
postcss.config.jsas per documentation:tailwind.css, including setting the new prefix (tw-totw:):@configto reference the existing Tailwind configuration:index.ts:index.tsfile explicitly importstailwind.css:webpack --mode development) and Encountered Errors:@applyfailing:@apply, Tailwind v4 and Webpack work fine.@apply—even when placed in a separate CSS file, the error persists.Key Findings:
@applynever works in Tailwind v4 with this setup.@applyentirely allows everything else to work fine.@applyis fundamentally broken in this environment.@applyis consistently rejected.Next Steps:
I believe this provides enough detail to investigate further. Given that:
@applyis 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
@referenceas we’ve suggested either, and I haven’t gotten a response on how it doesn’t resolve your issue. Again@referenceis a real feature of the framework that you are expected to use when referencing theme variables defined in separate CSS entry points.@adamwathan