[v4] Cannot apply unknown utility class X without @reference directive

[bcorcoran]

What version of Tailwind CSS are you using?

v4.0.0

What build tool (or framework if it abstracts the build tool) are you using?

Vite 5.4.14

Describe your issue

In the upgrade guide for v4, the following is stated:

In v4, stylesheets that are bundled separately from your main CSS file (e.g. CSS modules files, <style> blocks in Vue, Svelte, or Astro, etc.) do not have access to theme variables, custom utilities, and custom variants defined in other files.

This makes it seem like you wouldn't have to use the @reference directive to include all util classes included out of the box with tailwindcss. That doesn't seem to be the case, as I had the following code:

<style>
.ui-multiselect-option em {
  @apply font-bold underline text-brand-blue-800;
}
.text-white .ui-multiselect-option em {
  @apply font-bold underline text-brand-blue-100;
}
</style>

The following error was thrown:

Cannot apply unknown utility class: font-bold

The issue is fixed by including the appropriate @reference directive. I would have expected to get an error on the text-brand-blue-* classes which were actually custom. Not sure if this is a bug or documentation issue, so reporting it as a bug.

[wongjn]

See #15778 (comment)

[bugproof]

I think @reference is problematic in projects where you have styles spread across multiple folders. You waste time looking for correct relative path to your css file.

@reference "../../../../styles/main.css";

This makes using @apply a nightmare in such files. I think it's easier to port it to use CSS vars and this way you can avoid using @reference

https://tailwindcss.com/docs/upgrade-guide#using-apply-with-vue-svelte-or-css-modules
https://tailwindcss.com/docs/compatibility#css-modules

[philipp-spiess]

Going to close this one. @wongjn linked to the right place 👍

[bcorcoran]

I think @reference is problematic in projects where you have styles spread across multiple folders. You waste time looking for correct relative path to your css file.

@reference "../../../../styles/main.css";

This makes using @apply a nightmare in such files. I think it's easier to port it to use CSS vars and this way you can avoid using @reference

https://tailwindcss.com/docs/upgrade-guide#using-apply-with-vue-svelte-or-css-modules https://tailwindcss.com/docs/compatibility#css-modules

If you're using vite, just set up resolve.alias and reference your chosen dir with whatever symbol. for example, in my project:

resolve: {
    alias: {
      '@': resolve(__dirname, './resources/js')
    },
  }