@apply doesn't work with @layer base and @layer components anymore in v4

[nemanjam]

Docs says in v4 base and components layers are still defined with @layer base and @layer components, also in v3 classes defined like that could be used with @apply. The problem is they fail in v4.

https://tailwindcss.com/docs/adding-custom-styles#adding-base-styles

Practically it means I am forced to define all base, components and utilities layers with @utility to be able to use those classes with @apply which of course would create a big mess.

I could define all layers with @utility and then set layers in @import statement but that also doesn't look too nice.

@import "tailwindcss/theme.css" layer(theme);
@import "tailwindcss/base.css" layer(base);
@import "tailwindcss/components.css" layer(components);
@import "tailwindcss/utilities.css" layer(utilities);

So at the end how to do this in v4? I already have a lot of code that uses custom classes with @apply defined in base and components layers and now in v4 they produce Cannot apply unknown utility class. On the other hand I dont want to define base and components as utilities.

I saw similar Github issues without obvious solution. If I use @reference I get @custom-variant cannot be nested. and @utility cannot be nested..

#16429

#13336

You can see my styles code here:

https://github.com/nemanjam/nemanjam.github.io/tree/feat/tailwind4-v2/src/styles

[wongjn]

In v4, Tailwind doesn't "hijack" the @layer at-rule anymore.

On the other hand I dont want to define base and components as utilities.

You'd need to use @utility to let Tailwind know about class names and thus be able to use them with @apply.

You can use @layer inside @utility to place them in the appropriate cascade layer, like:

@utility foo {
  @layer base {
    …
  }
}

Ideally, you'd use your templates to define the components, instead of writing any CSS. Adam Wathan (creator of Tailwind) does seem to advocate avoiding @apply:

• https://twitter.com/adamwathan/status/1226511611592085504
• https://twitter.com/adamwathan/status/1559250403547652097
• https://x.com/adamwathan/status/1890404835888910467

[nemanjam]

If I do it like that:

1. How to name that utility, does that name e.g. tags-utility affect anything and where is it used?
2. How to use defined class with @apply, I can still just use <h1 class="b-h1">text</h1> as before? No namespace with tags-utility?

@utility tags-utility {
  @layer base {

    .b-h1 {
      @apply text-3xl sm:text-4xl md:text-5xl;
      @apply font-bold;
      @apply mb-6 md:mb-8 lg:mb-10;
    }

    .b-h2 {
      @apply text-2xl md:text-3xl;
      @apply font-bold;
      @apply mt-12 mb-6 md:mt-14 md:mb-8;
    }

    // ... other classes

  }
}

[wongjn]

How to name that utility, does that name e.g. tags-utility affect anything and where is it used?

The must match of of these two regular expressions:

tailwindcss/packages/tailwindcss/src/utilities.ts

Lines 29 to 30 in 7005ad7

	const IS_VALID_STATIC_UTILITY_NAME = /^-?[a-z][a-zA-Z0-9/%._-]*$/
	const IS_VALID_FUNCTIONAL_UTILITY_NAME = /^-?[a-z][a-zA-Z0-9/%._-]*-\*$/

The name is the class name that you'd use.

How to use defined class with @apply, I can still just use <h1 class="b-h1">text</h1> as before? No namespace with tags-utility?

I'm not sure where this "namespace" concept has come from, but for b-h1, you'd do:

@utility b-h1 {
  @layer base {
    @apply text-3xl sm:text-4xl md:text-5xl;
    @apply font-bold;
    @apply mb-6 md:mb-8 lg:mb-10;
  }
}

Or better yet (following Adam's advice), refactor it into a component of some sort, like:

-<h1 class="b-h1">Hello World</h1>
+<BH1>Hello World</BH1>

<h1 class="font text-3xl sm:text-4xl md:text-5xl mb-6 md:mb-8 lg:mb-10 font-bold">
  <slot />
</h1>

[nemanjam]

Will I achieve the same effect just by using layer(base) in the @import statement? Without having to repeat @layer base for every class definition.

@import "tailwindcss/base.css" layer(base);

[nemanjam]

Can you please concisely explain the difference or point me to some links?

[wongjn]

What do you want to the know the difference between?

[nemanjam]

These two layer definitions.

// 1. layer defined like this
@import "tailwindcss/base.css" layer(base);


// 2. and layer defined like this
@utility b-h1 {
  @layer base {
    @apply text-3xl sm:text-4xl md:text-5xl;
    @apply font-bold;
    @apply mb-6 md:mb-8 lg:mb-10;
  }
}

[wongjn]

Those aren't layer definitions.

---

@import "tailwindcss/base.css" layer(base);

This places the CSS found in node_modules/tailwindcss/base.css into this CSS file, wrapping the CSS in a @layer base CSS cascade named layer (but it does not define the layer).

---

@utility b-h1 {
  @layer base {
    @apply text-3xl sm:text-4xl md:text-5xl;
    @apply font-bold;
    @apply mb-6 md:mb-8 lg:mb-10;
  }
}

This registers a class name b-h1 with Tailwind, with the content of:

<selector> {
  @layer base {
    @apply text-3xl sm:text-4xl md:text-5xl;
    @apply font-bold;
    @apply mb-6 md:mb-8 lg:mb-10;
  }
}

To be used later in @apply, in which case Tailwind generates the content into the @apply location. Or when Tailwind sees <optional valid variants>:b-h1 in a source files, in which case Tailwind will compile rules with the appropriate selector in the location designated by a @tailwind utilities; declaration.

[nemanjam]

Ok, thank you. Obviously this was a breaking change, base and components worked with apply in v3 and they dont in v4.

[dicash]

I was surprised to find out today that @apply doesn't work in @layer base.
We were doing

@layer components {
  .input {
    @apply ...;
  }
}

I thought that's natural expectation. We don't want to turn simple HTML elements into components.

[wongjn]

Seems to be working in this Tailwind Play which would suggest it could be something particular to your project.