Some background

The first person who ate crab was truly brave. They looked at this armored sea creature and thought "Yes, I'm going to crack this open and eat what's inside." That pioneering spirit is what we need when tackling new technologies.

I'm working on a project that uses React 19, TailwindCSS v4, and NextJS 15 (canary stable). While I have the OCD to always be using the latest stable versions of everything, I recently ran into an issue that I hadn't encountered before, mainly because I've been using TailwindCSS v3 for a while and V4 had a dramatic breaking change. I decided to keep this post an open and continuous note to myself and whoever struggles with the same issues for future reference.

Oh, one more thing, since I enjoy "vibe coding" recently, based on my shallow observation, a lot of issues have come from the fact that Cursor is not able to keep up with the latest version of the codebases.

The TailwindCSS v4 Issues

1. use @reference over @apply

In TailwindCSS v4, everything has come into global.css from the previous tailwind.config.js, and Cursor and some other "LLM-aid IDEs" have this intentions to use:

@layer base {
  * {
    @reference border-neutral-200 dark:border-neutral-800;
  }
  body {
    @reference bg-background text-foreground;
    font-feature-settings: "rlig" 1, "calt" 1;
  }
}

which will lead to the error Cannot apply unknown utility:

Error: Cannot apply unknown utility class: border-border

The solution is to simply use @reference instead of @apply, to avoid shadowing TailwindCSS generated classes.

2. Build failures (on Vercel)

I personally use a macOS for development, so some issues can only be caught on Vercel, at build time. This time I run into a new issue saying:

Can't build on Linux ARM -> cannot find module '@tailwindcss/oxide-linux-arm64-gnu'
Cannot find module '../lightningcss.linux-x64-gnu.node

After some digging on Github, it seems like we need to add optional dependencies to package.json and reinstall the dependencies:

"optionalDependencies": {
    "@tailwindcss/oxide-linux-x64-gnu": "^4.0.14",
    "lightningcss-linux-x64-gnu": "^1.29"
}