How to make @utility + @apply compatible with prefix() in Tailwind v4?

[zecka]

I'm trying to build a CSS design system package with Tailwind v4. The idea is to expose utilities, similar to what DaisyUI does.

For example, I want to define a btn utility like this:

@utility btn {  
  @layer utilities.components.base {  
    @apply bg-amber-500;  
  }  
}  

The package would be published as @acme/css and consumed like this:

@import "tailwindcss";  
@import "@acme/css";  

This works fine without a prefix.

---

Problem

When a consumer wants to use Tailwind’s prefix() feature, things break.
For example:

@import "tailwindcss" prefix(tw);  
@import "@acme/css";  

Expected usage:

<button class="tw:btn">button</button>  

But instead I get this error:

Cannot apply unprefixed utility class bg-amber-500. Did you mean tw:bg-amber-500?

---

Question

What is the recommended way to define utilities in a package (using @utility + @apply) so they remain compatible with projects that use prefix()?

• Should I avoid @apply in this case?
• Is there a way for @utility definitions to automatically adapt to the consumer’s prefix?

Reproduction playground

Here is a reproduction playground
https://play.tailwindcss.com/rHFsQxQtVj?file=css

[rozsazoltan]

Answer for "What is the recommended way [...]"

I know this isn't the answer you were looking for, but I'd like to point out that the use of @apply is generally recommended to be avoided:

Confession: The apply feature in Tailwind basically only exists to trick people who are put off by long lists of classes into trying the framework.

You should almost never use it 😬

Reuse your utility-littered HTML instead.

Source: @adamwathan, #2, #3

If I do it this way, then there’s no error:

• https://play.tailwindcss.com/mzKSaxGSFu?file=css

@import "tailwindcss" prefix(tw);

@utility btn {
  background-color: var(--tw-color-amber-500);
}

<button class="tw:btn">example</button>

In this case, you need to call all utilities with the prefix, and the variables also get the prefix.

How to handle your "cannot apply unprefixed utility class" message

Cannot apply unprefixed utility class bg-amber-500. Did you mean tw:bg-amber-500?

If you really insist on using @apply, then you must also apply the tw: prefix there, since that's how you distinguish your project's bg-amber-500 from TailwindCSS's own bg-amber-500:

• https://play.tailwindcss.com/3Cdjlf1R26?file=css

@import "tailwindcss" prefix(tw);

@utility btn {
  @apply tw:bg-amber-500;
}

<button class="tw:btn">example</button>

[rozsazoltan]

And if you don't have a particular reason for it, the prefix only complicates your life. If it's not necessary, I wouldn't use it. Instead, you can introduce multiple layers where you insert your own CSS at the appropriate level.

[zecka]

Thanks, I understand that avoiding @apply is a valid recommendation.

But that doesn’t really solve my issue: I want the consuming project to decide the prefix().
If I hardcode tw: (via @apply tw:bg-amber-500 or var(--tw-color-amber-500)), then the library forces a prefix and removes that flexibility.

What I need is a way for @utility definitions in a library to stay prefix-agnostic so they automatically adapt to whatever prefix the consumer project chooses. Is that possible?

Note that daisyui allow this behaviour via

@plugin "daisyui" {
 prefix: foo
}

[rozsazoltan]

TailwindCSS requires you to manually add the prefix. If you don't want to (or can't) do this, you could possibly inject a plugin that runs before the TailwindCSS engine, interprets the @apply lines, and inserts the appropriate prefix for you.

I assume DaisyUI has written such a plugin for itself in the background using the property.

• https://github.com/saadeghi/daisyui/blob/e6dc09251487007c173cde0aad2a3fd88fefeb3f/packages/daisyui/functions/addPrefix.js#L156-L162 (a plugin for this feature)
• https://github.com/saadeghi/daisyui/blob/e6dc09251487007c173cde0aad2a3fd88fefeb3f/packages/daisyui/functions/addPrefix.test.js#L123-L142 (just highlighted some tests)

So if you want to do the same thing as DaisyUI, you need a plugin that always runs before the TailwindCSS engine, for example via PostCSS.