"Cannot apply unknown utility class"

[alexschcom]

I've been trying to upgrade this Astro template to Tailwind v4 for the last two hours.

I'm following all the steps listed in Astro's docs:

1. npm install
2. npx astro add tailwind
3. npm uninstall @astrojs/tailwind
4. remove @astrojs/tailwind integration from astro.config.mjs
5. git add .; git commit -m "prep to upgrade to Tailwind v4"
6. npx @tailwindcss/upgrade

Here's the full terminal history for reference

~/Desktop/marmo main                                                                                       06:22:43 PM
❯ npm install                                          
npm warn deprecated inflight@1.0.6: This module is not supported, and leaks memory. Do not use it. Check out lru-cache if you want a good and tested way to coalesce async requests by a key value, which is much more comprehensive and powerful.
npm warn deprecated @humanwhocodes/config-array@0.13.0: Use @eslint/config-array instead
npm warn deprecated rimraf@3.0.2: Rimraf versions prior to v4 are no longer supported
npm warn deprecated glob@7.2.3: Glob versions prior to v9 are no longer supported
npm warn deprecated @humanwhocodes/object-schema@2.0.3: Use @eslint/object-schema instead
npm warn deprecated eslint@8.57.1: This version is no longer supported. Please see https://eslint.org/version-support for other options.
added 813 packages, and audited 814 packages in 36s
367 packages are looking for funding

run npm fund for details
found 0 vulnerabilities

·························································································································································

~/Desktop/marmo main ?1                                                                                                                   37s 06:23:25 PM

❯ npx astro add tailwind

✔ Resolving packages...
Astro will run the following command:

If you skip this step, you can always run it yourself later
╭──────────────────────────────────────────────────────╮

│ npm i @tailwindcss/vite@^4.1.13 tailwindcss@^4.1.13  │

╰──────────────────────────────────────────────────────╯
✔ Continue? … yes

✔ Installing dependencies...
Astro will make the following changes to your config file:
╭ astro.config.mjs ────────────────────────────────╮

│ import { defineConfig } from "astro/config";     │

│ import mdx from "@astrojs/mdx";                  │

│ import sitemap from "@astrojs/sitemap";          │

│ import tailwind from "@astrojs/tailwind";        │

│                                                  │

│ import tailwindcss from "@tailwindcss/vite";     │

│                                                  │

│ export default defineConfig({                    │

│   site: "https://astro-nano-demo.vercel.app",    │

│   integrations: [mdx(), sitemap(), tailwind()],  │

│                                                  │

│   vite: {                                        │

│     plugins: [tailwindcss()],                    │

│   },                                             │

│ });                                              │

╰──────────────────────────────────────────────────╯
✔ Continue? … yes
success  Added the following integration to your project:

tailwind

action required  You must import your Tailwind stylesheet, e.g. in a shared layout:
╭ src/layouts/Layout.astro ──────╮

│ ---                            │

│ import '../styles/global.css'  │

│ ---                            │

╰────────────────────────────────╯
·························································································································································

~/Desktop/marmo main !2 ?1                                                                                                                 8s 06:26:00 PM

❯ npm uninstall @astrojs/tailwind

npm warn ERESOLVE overriding peer dependency

npm warn While resolving: @astrojs/tailwind@5.1.5

npm warn Found: tailwindcss@4.1.13

npm warn node_modules/tailwindcss

npm warn   tailwindcss@"4.1.13" from @tailwindcss/node@4.1.13

npm warn   node_modules/@tailwindcss/node

npm warn     @tailwindcss/node@"4.1.13" from @tailwindcss/vite@4.1.13

npm warn     node_modules/@tailwindcss/vite

npm warn   3 more (@tailwindcss/typography, @tailwindcss/vite, the root project)

npm warn

npm warn Could not resolve dependency:

npm warn peer tailwindcss@"^3.0.24" from @astrojs/tailwind@5.1.5

npm warn node_modules/@astrojs/tailwind

npm warn

npm warn Conflicting peer dependency: tailwindcss@3.4.17

npm warn node_modules/tailwindcss

npm warn   peer tailwindcss@"^3.0.24" from @astrojs/tailwind@5.1.5

npm warn   node_modules/@astrojs/tailwind
removed 13 packages, and audited 786 packages in 879ms
358 packages are looking for funding

run npm fund for details
found 0 vulnerabilities

·························································································································································

~/Desktop/marmo main !2 ?1                                                                                                                    06:26:33 PM

❯ npx @tailwindcss/upgrade

≈ tailwindcss v4.1.13
│ Git directory is not clean. Please stash or commit your changes before migrating.
│ You may use the --force flag to silence this warning and perform the migration.
·························································································································································

~/Desktop/marmo main !2 ?1                                                                                                                    06:27:21 PM

❯ git add .; git commit -m "prep to upgrade to Tailwind v4"

[main 052aeb5] prep to upgrade to Tailwind v4

3 files changed, 11086 insertions(+), 5 deletions(-)

create mode 100644 package-lock.json

·························································································································································

~/Desktop/marmo main ⇡1                                                                                                                       06:28:13 PM

❯ npx @tailwindcss/upgrade

≈ tailwindcss v4.1.13
│ Searching for CSS files in the current directory and its subdirectories…
│ Migrating stylesheets…
│ ↳ Cannot apply unknown utility class font-sans. Are you using CSS modules or similar and missing @reference?

│   https://tailwindcss.com/docs/functions-and-directives#reference-directive in ./src/styles/global.css
│ ↳ Migrated stylesheet: ./src/styles/global.css
│ Updating dependencies…
│ ↳ Updated package: tailwindcss
│ ↳ Updated package: @tailwindcss/vite
│ Migrating templates…
Error: Cannot apply unknown utility class font-sans. Are you using CSS modules or similar and missing @reference? https://tailwindcss.com/docs/functions-and-directives#reference-directive

at onInvalidCandidate (file:///Users/alex/.npm/_npx/234afcd4ab2f5775/node_modules/tailwindcss/dist/chunk-U5SIPDGO.mjs:18:1332)

at pe (file:///Users/alex/.npm/_npx/234afcd4ab2f5775/node_modules/tailwindcss/dist/chunk-U5SIPDGO.mjs:13:29888)

at file:///Users/alex/.npm/_npx/234afcd4ab2f5775/node_modules/tailwindcss/dist/chunk-U5SIPDGO.mjs:18:373

at D (file:///Users/alex/.npm/_npx/234afcd4ab2f5775/node_modules/tailwindcss/dist/chunk-U5SIPDGO.mjs:3:1656)

at Oe (file:///Users/alex/.npm/_npx/234afcd4ab2f5775/node_modules/tailwindcss/dist/chunk-U5SIPDGO.mjs:18:172)

at ti (file:///Users/alex/.npm/_npx/234afcd4ab2f5775/node_modules/tailwindcss/dist/chunk-U5SIPDGO.mjs:35:780)

at process.processTicksAndRejections (node:internal/process/task_queues:105:5)

at async mn (file:///Users/alex/.npm/_npx/234afcd4ab2f5775/node_modules/tailwindcss/dist/chunk-U5SIPDGO.mjs:35:1123)

at async Sa (file:///Users/alex/.npm/_npx/234afcd4ab2f5775/node_modules/@tailwindcss/node/dist/index.mjs:10:3358)

at async Ps (file:///Users/alex/.npm/_npx/234afcd4ab2f5775/node_modules/@tailwindcss/upgrade/dist/index.mjs:255:12962)

·························································································································································

~/Desktop/marmo main ⇡1 !1                                                                                                                12s 06:28:28 PM

❯ 

The error is

Error: Cannot apply unknown utility class `font-sans`. Are you using CSS modules or similar and missing `@reference`? https://tailwindcss.com/docs/functions-and-directives#reference-directive

I'm not using modules, though, as you can see. It's just one global.css stylesheet that's imported in the Head.astro component. Also, how is font-sans an unknown utility class?

[wongjn]

The npx astro add tailwind step installs Tailwind v4 already. So when you later try to do npx @tailwindcss/upgrade, the upgrade tool sees that you have v4 installed. Thus, it looks at your code as a v4 project. However, your integration code is still v3 and thus causes the error.

You could consider:

• Integrating v3 before running the upgrade tool.
• Manually upgrading to v4.

[alexschcom]

Integrating v3

What does that mean?

Are Astro's docs just wrong, then, since they specifically say to run their add tailwind before upgrading?

[wongjn]

Integrating v3

What does that mean?

Integrating v3 means installing and integrating Tailwind v3 instead of v4.

Are Astro's docs just wrong, then, since they specifically say to run their add tailwind before upgrading?

It doesn't seem like Astro's docs are wrong. Looking at their docs, it seems you tried to do the steps in Add Tailwind 4 before Upgrade from Tailwind 3. The correct procedure would be only to do the steps in Upgrade from Tailwind 3.

[alexschcom]

What do you mean by "integrating"?

I just double-checked and the docs specifically say to "Add Tailwind 4 support to your project" as the first step 🤔

[wongjn]

What do you mean by "integrating"?

I mean installing/combining into.

I just double-checked and the docs specifically say to "Add Tailwind 4 support to your project" as the first step 🤔

Ah, I see, thank you. It seems you may have missed out the second step:

Then, import tailwindcss into src/styles/global.css (or another CSS file of your choosing) to make Tailwind classes available to your Astro project. This file including the import will be created by default if you used the astro add tailwind command to install the Vite plugin.

@import "tailwindcss";

The @import would replace the @tailwind directives.

[alexschcom]

@import "tailwindcss";

Ohhh, I thought the upgrade tool would do that... Now it works, thank you!