Tailwind 4 Upgrade tool incorrectly converts classes in "@layer components", into @utilities

[darylknight]

The upgrade tool from Tailwind 3 to 4 converts classes in my @layer components into @utilities.

Stripped down example:

@layer components {
	.btn {
		@apply inline-block rounded-md border-2 border-black px-10 py-2 hover:bg-black hover:text-white focus-visible:bg-black focus-visible:text-white focus-visible:outline-none;
	}

	/* * Prose /*
	/* Imitates Tailwind's Typography plugin without all the extra stuff */
	.prose {
	}
	.prose ul {
		@apply mb-10 list-disc pl-8 text-base lg:text-lg last:mb-0;
	}
	.prose ol {
		@apply mb-10 list-decimal pl-8 text-base lg:text-lg last:mb-0;
	}
	.prose li {
		@apply mb-2;
	}
	.prose hr {
		@apply mb-4 border border-neutral-400 last:mb-0;
	}
	.prose table td,
	.prose table th {
		@apply border border-neutral-300 p-2;
	}
	.prose table th {
		@apply bg-neutral-100;
	}
	.prose blockquote {
		@apply mb-5 border-l-4 pl-4 italic;
	}
}

Converted app.css:

@utility btn {
	@apply inline-block rounded-md border-2 border-black px-10 py-2 hover:bg-black hover:text-white focus-visible:bg-black focus-visible:text-white focus-visible:outline-hidden;
}

@utility prose {
	/* * Prose /*
	/* Imitates Tailwind's Typography plugin without all the extra stuff */
	& ul {
		@apply mb-10 list-disc pl-8 text-base last:mb-0 lg:text-lg;
	}
	& ol {
		@apply mb-10 list-decimal pl-8 text-base last:mb-0 lg:text-lg;
	}
	& li {
		@apply mb-2;
	}
	& hr {
		@apply mb-4 border border-neutral-400 last:mb-0;
	}
	& table td {
		@apply border border-neutral-300 p-2;
	}
	& table th {
		@apply border border-neutral-300 p-2;
	}
	& table th {
		@apply bg-neutral-100;
	}
	& blockquote {
		@apply mb-5 border-l-4 pl-4 italic;
	}
}

[philipp-spiess]

Hey! This is done on purpose because @layer components was used to register utilities in the components layer before and now with the v4 migration we moved all utilities into the same layer so a conversion to @utility seems expected. Are you seeing any issues with this or were you only surprised?

[darylknight]

Thanks for getting back to me so quickly :)

I guess I'm "surprised", because I've never used the utilities layer. As an example, I used the components layer because I need base styles for .btn which I can override in the HTML (which I think is how components are intended, reading the v3 documentation).

1. My understanding is that if the tool converts them to @utilities, then I won't be able to override those styles in the HTML without using the ! prefix
2. The upgrade documentation (https://tailwindcss.com/docs/upgrade-guide#adding-custom-utilities) says:

In v3, any custom classes you defined within @layer utilities would get picked up by Tailwind as a true utility class and would automatically work with variants like hover, focus, or lg.

This indicates (to me) that the upgrade tool should only be converting things that were defined in the @layer utilities in Tailwind 3. Maybe it's just confusingly worded as I don't understand what this means: "In v4 we are using native cascade layers and no longer hijacking the @layer at-rule, so we've introduced the @Utility API as a replacement:".

These aren't things that are using "a CSS feature you'd like to use in your project that Tailwind doesn't include utilities for out of the box" so as far as I can tell, they don't need to be converted to utilities.

[philipp-spiess]

1. My understanding is that if the tool converts them to https://github.com/utilities, then I won't be able to override those styles in the HTML without using the ! prefix

It should still be possible for you to overwrite the utility with other utilities OR with unlayered styles: https://play.tailwindcss.com/n5wSqWBGLs We do sort these utilities and those with lots of declarations and all of these have many declarations) should appear before the native utilities that are more specific.

2. The upgrade documentation (https://tailwindcss.com/docs/upgrade-guide#adding-custom-utilities) says

Ah, yeah, I see your confusion but @layer components worked similarly to @layer utilities before in that regard. The only difference was that components would always appear before utilities. I'll see if we can improve the upgrade guide for more clarity 👍

These aren't things that are using "a CSS feature you'd like to use in your project that Tailwind doesn't include utilities for out of the box" so as far as I can tell, they don't need to be converted to utilities.

This is actually a very good point. If you do not need your .btn and .prose to be used with @apply or with modifiers like hover:btn, It is probably not necessary to make these a Tailwind CSS specific thing in the first place. If all you want is to keep CSS classes that can be overwritten by your utilities, keeping @layer components is definitely what you want instead. Unfortunately, in V3 these components would become Tailwind utilities under the hood and the upgrade tool needs to be more accurate here to avoid breaking too many things. :(

It is however working as intended so I moved this from a GitHub issue to a discussion for now.

[darylknight]

That makes sense - thank you for taking the time to clarify this :) I'm going to manually change these back into components now, but I understand more about why it's like this. If you do get a chance to update the docs, I think that might make sense :) Feel free to close this unless it's useful for people to see