8000 Improve error messages when `@apply` fails by RobinMalfait · Pull Request #18059 · tailwindlabs/tailwindcss · GitHub
[go: up one dir, main page]
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.

Sign up for GitHub

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

Jump to bottom
Merged
merged 11 commits into from
May 27, 2025
Merged

Improve error messages when @apply fails #18059

merged 11 commits into from
May 27, 2025

Conversation

RobinMalfait
Copy link
Member
@RobinMalfait RobinMalfait commented May 16, 2025 •
edited
Loading

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-white`. Are you using CSS modules or similar and missing `@reference`? https://tailwindcss.com/docs/functions-and-directives#reference-directive

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 utility class `bg-white` because it has been explicitly disabled: 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`?

Applying known utilities with unknown variants

If you have unknown variants, then we will list them as well if the base utility does compile correctly.

Given this input:

@import "tailwindcss";

.foo {
  @apply hocus:hover:pocus:bg-red-500;
}

The following error is thrown:

Cannot apply utility class `hocus:hover:pocus:bg-red-500` because the `hocus` and `pocus` variants do not exist.

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

[ci-all] There are some newlines here and there, let's verify that they work identically on all platforms.

@RobinMalfait RobinMalfait force-pushed the fix/improve-apply-error-message branch 2 times, most recently from e2af578 to e285dd8 Compare May 16, 2025 19:29
@RobinMalfait RobinMalfait force-pushed the fix/improve-apply-error-message branch from e285dd8 to f5ceae3 Compare May 26, 2025 13:13
@RobinMalfait RobinMalfait marked this pull request as ready for review May 26, 2025 14:09
@RobinMalfait RobinMalfait requested a review from a team as a code owner May 26, 2025 14:09
RobinMalfait
RobinMalfait commented May 26, 2025
View reviewed changes
thecrypticace
thecrypticace reviewed May 26, 2025
View reviewed changes
thecrypticace
thecrypticace reviewed May 26, 2025
View reviewed changes
thecrypticace
thecrypticace approved these changes May 26, 2025
View reviewed changes
Copy link
Contributor
@thecrypticace thecrypticace left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Left a note about the stylesheet name but I'm gonna go ahead and approve this. We can tweak those details later if need be.

@RobinMalfait RobinMalfait force-pushed the fix/improve-apply-error-message branch from 3b6f2c2 to 75bdb44 Compare May 26, 2025 14:31
philipp-spiess
philipp-spiess previously requested changes May 26, 2025
View reviewed changes
@RobinMalfait
rely on Theme to know when we are missing @reference or `@import …
3f69a5f 
…"tailwindcss"`

This is a better single source of truth because `Theme` will be filled
in with the necessary data.
@RobinMalfait
show unknown variants when using @apply
b578ca9
reinink
reinink previously requested changes May 27, 2025
View reviewed changes
Copy link
Member
@reinink reinink left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Some feedback — still needs to be reviewed by @adamwathan, so don't merge anything in yet.

RobinMalfait and others added 2 commits May 27, 2025 19:36
@RobinMalfait @reinink
Apply suggestions from code review
d1a6051 
Co-authored-by: Jonathan Reinink <jonathan@reinink.ca>
@RobinMalfait
adjust error messages
b47519f
@RobinMalfait RobinMalfait dismissed stale reviews from reinink and philipp-spiess May 27, 2025 18:18

Approved via Discord

@RobinMalfait RobinMalfait merged commit 4bfacb3 into main May 27, 2025
21 checks passed
@RobinMalfait RobinMalfait deleted the fix/improve-apply-error-message branch May 27, 2025 18:19
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Reviewers

@thecrypticace thecrypticace thecrypticace approved these changes

@philipp-spiess philipp-spiess philipp-spiess left review comments

@reinink reinink reinink left review comments

Assignees
No one assigned
Labels
None yet
Projects
None yet
Milestone
No milestone
Development

Successfully merging this pull request may close these issues.
4 participants
@RobinMalfait @philipp-spiess @thecrypticace @reinink
0