nextjs - 💡(How to fix) Fix Tailwind v4 persistent cache stuck on CSS syntax errors in Next.js (Turbopack & Monorepo) [2 comments, 3 participants]

1. Introduce a syntax error in globals.css (e.g., remove a closing brace }).
2. Next.js shows the compilation error.
3. Fix the error in globals.css.
4. Result: The error overlay stays in the browser. Refreshing or restarting the server does not help.
5. This error is only disappear when i clear my .next folder or switch to run dev with --webpack flag
6. Introduce a syntax error in the source file: packages/ui/globals.css.
7. Result: The app crashes with a syntax error.
8. Fix the error in packages/ui/globals.css.
9. Observation: Even after restarting the dev server with either --turbo or --webpack, the error persists. The build process seems to be serving a cached version of the broken CSS file indefinitely. Next.js and the Tailwind v4 engine should invalidate the cache and re-parse the CSS files as soon as the file watcher detects a fix, clearing the error overlay without requiring a manual .next deletion. The error state is cached persistently. It appears the dependency graph (especially when involving @reference or cross-package imports) fails to trigger a clean rebuild after a hard syntax error occurs. I suspect this is a cache invalidation failure within Next.js's build engine. Vite demonstrates that the Tailwind v4 compiler can recover from these errors seamlessly. However, Next.js appears to fail in re-scanning or re-linking the @reference dependency once a hard syntax error has been cached, suggesting that the link between the CSS Module and the referenced file is being lost or stuck in an error state in the .next directory.

Fix Plan

Solution Overview

The issue is caused by a persistent cache of the broken CSS file in the .next directory. To fix this, we need to invalidate the cache and re-parse the CSS files as soon as the file watcher detects a fix.

Configuration Changes

• Update next.config.js to use the turbo configuration with the cache option set to false:

module.exports = { // ... turbo: { cache: false, }, };

#### Code Changes

*   In `globals.css`, use the `@apply` directive instead of `@reference` to import Tailwind classes:
    ```css
/* globals.css */
@tailwind base;
@tailwind components;
@tailwind utilities;

/* Use @apply instead of @reference */
.button {
    @apply bg-blue-500 hover:bg-blue-700 text-white font-bold py-2 px-4 rounded;
}

Infra / Dependency Fixes

• Make sure to delete the .next directory after fixing the error in globals.css to ensure the cache is invalidated.

Temporary Workaround

• Use the temporary workaround rm -rf .next && next dev to invalidate the cache and re-parse the CSS files.

Verification

• After making the changes, run next dev and introduce a syntax error in globals.css.
• Fix the error in globals.css and observe that the error overlay is cleared without requiring a manual .next deletion.
• Verify that the build process serves the updated CSS file without caching the broken version.

Extra Tips

• Make sure to update next.config.js to use the turbo configuration with the cache option set to false to ensure the cache is invalidated.
• Use the @apply directive instead of @reference to import Tailwind classes to