Solving Tailwind’s “Unknown at rule @apply”

Originally posted in oh-no.ooo (Unknown at rule @apply… k thx bye!), my personal website.

Chances are you are using VSCode, and chances are you’re also using Tailwind in one of your projects. Chances are that at my first chances are… you went immediately nuh-uh and moved on (and if you’re a NeoVim user I can’t help you anyway, you’re already doomed and lost in the recommended plugins someone chose for you and you’re probably still figuring out half of them) but if I got your attention with the first two assumptions, then this post might be relevant for you!

One issue I’ve been having ever since using Tailwind with SCSS modules has been that VSCode goes absolutely ballistic marking every @apply as an unknown CSS rule, as the editor assumes it’s one at-rule from CSS. (If you are wondering what at-rules are, @import and @media might sound a bit more familiar :D)

@apply is a Tailwind directive that mimics in semantics a native CSS at-rule, and this one in the specific takes care of enabling Tailwind utility classes in a .scss file … which by now we already now — I know, we wouldn’t be reading this article otherwise — so jumping to the main thing, let me present you my favourite solution from the solutions list that this article from byby.dev proposes.

Open the .vscode folder in your project, create a tailwind_directives.json file and add the following lines. I took the liberty of expanding from the article, which was talking specifically about the @tailwind directive, and take it as a chance to put all the Tailwind specific directives I could find from Tailwind’s documentation:

{
    "version": 1.0,
    "atDirectives": [
        {
            "name": "@tailwind",
            "description": "Use the @tailwind directive to insert Tailwind's `base`, `components`, `utilities`, and `screens` styles into your CSS."
        },
        {
            "name": "@apply",
            "description": "Use @apply to inline any existing utility classes into your own custom CSS."
        },
        {
            "name": "@screen",
            "description": "The screen function allows you to create media queries that reference your breakpoints by name instead of duplicating their values in your own CSS. Apparently deprecated in favour of @media?!"
        },
        {
            "name": "@layer",
            "description": "Use the @layer directive to tell Tailwind which “bucket” a set of custom styles belong to. Valid layers are base, components, and utilities."
        },
        {
            "name": "@config",
            "description": "Use the @config directive to specify which config file Tailwind should use when compiling that CSS file. Do not put @config before your @import statements."
        }
    ]
}

Then, head to settings.json and add these two lines:

{
// ... other stuff
  "css.customData": [".vscode/tailwind_fix.json"],
  "scss.customData": [".vscode/tailwind_fix.json"]
}

And voilá! Done!

…
Now now, you might be tempted to follow the first solution proposed by the article, which simply tells VSCode to ignore every at-rule it cannot recognise:

{
// Warning: Sub-optimal approach
// Please follow the previous advice!
// ... other stuff
  "css.lint.unknownAtRules": "ignore"
  "scss.lint.unknownAtRules": "ignore"
}

But! What about typos? We all make them, and I wouldn’t trust myself writing things correctly any day :’D Better be more specific and let pass only the things we are aware of!

Sources and inspiration