Issues with @apply Directive and Prefix Configuration in Tailwind CSS v4

[JaquesBotha]

Issues with @apply Directive and Prefix Configuration in Tailwind CSS v4

Problem Summary

I've recently upgraded to Tailwind CSS v4 and encountered the following issues:

1. @apply Directive in Custom CSS

In previous versions, I've used the @apply directive within my custom CSS files to incorporate utility classes. After upgrading to v4, this approach results in errors indicating that utility classes cannot be found. For example:

Error: Cannot apply unknown utility class: tw-transform

This suggests that the @apply directive is not functioning as it did in earlier versions. If there's a new recommended approach or if @apply has been deprecated or modified, it would be beneficial to have clear documentation on this transition.

I am using this approach because in this specific Blazor project, the only way to modify/alter QuickGrid native component is through CSS. I rarely use custom CSS, but in this instance, I have no choice.

Example: Scoped Styling for QuickGrid

/* Scoped Styling For QuickGrid */
.quickgrid {
	@apply tw-table-auto
    tw-w-full;
}
/* Table Header */
.quickgrid thead th {
	@apply tw-bg-slate-100
    dark:tw-bg-slate-800/70
    tw-py-4;
}

.quickgrid th:first-child {
	@apply tw-rounded-s-lg;
}

2. Prefix Configuration

To prevent class name conflicts, I utilized the prefix feature by importing Tailwind with a prefix:

@import "tailwindcss" prefix(tw);

While this successfully adds the prefix to utility classes, it appears that the Preflight base styles are still applied without the prefix. This leads to unintended styling issues in projects where a prefix is essential to avoid conflicts. Additionally, the documentation on configuring prefixes in v4 seems sparse, making it challenging to implement this feature effectively.

---

Blazor & TailwindCSS Configuration Issues

Blazor projects, when combined with Webpack and TailwindCSS, can encounter compatibility issues. Specifically:

1. TailwindCSS configuration inside CSS files: Since TailwindCSS v4 moves towards a CSS-first approach, integrating tailwind.config.js inside Webpack-managed stylesheets can introduce unexpected behavior.
2. CSS Scoping Limitations: Blazor components, such as QuickGrid, often require custom styles that cannot be modified through traditional utility classes. This makes @apply a crucial feature in these projects.
3. Solution Proposal:
   • Provide official guidance on Tailwind usage within Webpack-driven Blazor projects.
   • Offer alternative approaches for handling scoped styles when @apply is restricted.
   • Ensure proper prefixing applies to Preflight styles in modularized applications.

---

Suggestions

1. Documentation Enhancements

Provide detailed guidance on the usage (or deprecation) of the @apply directive in v4, especially concerning its application in custom CSS files.

2. Prefix Consistency

Ensure that when a prefix is specified, it uniformly applies to all generated classes, including those from Preflight, or offer a clear method to disable Preflight when using prefixes.

3. Clear Migration Guide

A clear and explicit migration guide for users relying on @apply in their custom CSS files would help avoid unnecessary confusion during the upgrade process.

---

I believe addressing these concerns will greatly assist developers in transitioning to and effectively utilizing Tailwind CSS v4.

Thank you for your attention to these matters!