Skip to content

Improve error messages when @apply fails #18059

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
wants to merge 4 commits into
base: main
Choose a base branch
from

Conversation

RobinMalfait
Copy link
Member

@RobinMalfait RobinMalfait commented May 16, 2025

This PR improves error messages when @apply fails. Right now it gives you a generic error message that you cannot apply a certain utility.

.foo {
  @apply bg-red-500;
}

Would result in:

Cannot apply unknown utility class: bg-red-500

However, there are some situations where we can give you more context about what's happening.

Missing @import "tailwindcss" or @reference

If you are in a Vue file for example, and you have the following code:

<template>
  <div class="foo"></div>
</template>

<style>
.foo {
  @apply bg-red-500;
}
</style>

Then this will now result in:

Cannot apply unknown utility class: `bg-red-500`.
It looks like you are missing a `@reference "app.css"` or `@import "tailwindcss";`

We do this by checking if we found a @tailwind utilities or @reference. If not, we throw this more specific error.

Explicitly excluded classes via @source not inline('…')

Or via the legacy blocklist from a JS config.

If you then have the following file:

@import "tailwindcss";

@source not inline('bg-white');

.foo {
  @apply bg-white;
}

Then this will now result in:

Cannot apply `bg-white`, it seems like the utility was explicitly excluded and cannot be applied.

More info: https://tailwindcss.com/docs/detecting-classes-in-source-files#explicitly-excluding-classes

We do this by checking if the class was marked as invalid.

Applying unprefixed class in prefix mode

If you have the prefix option configured, but you are applying a non-prefixed class, then we will show the following error:

Given this input:

@import "tailwindcss" prefix(tw);

.foo {
  @apply underline;
}

The following error is thrown:

Cannot apply unprefixed utility class: `underline`, did you mean `tw:underline`?

Test plan

  1. Everything behaves the same, but the error messages give more details.
  2. Updated tests with new error messages
  3. Added new unit tests to verify the various scenarios
  4. Added a Vue specific integration test with a <style>…</style> block using @apply

@RobinMalfait RobinMalfait force-pushed the fix/improve-apply-error-message branch from bb45673 to e2af578 Compare May 16, 2025 18:59
@RobinMalfait RobinMalfait force-pushed the fix/improve-apply-error-message branch from e2af578 to e285dd8 Compare May 16, 2025 19:29
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

1 participant