PostCSS: Improve error recovery (#17754)

Closes #17295

This commit addresses an issue where the PostCSS plugin would get stuck
in an error state when processing files with e.g. invalid @apply
directives.

This change prevents the PostCSS plugin from getting stuck in an error
states particularly when the error happened inside an `@import`ed CSS
files (as these were not registered as dependencies correctly before).

## Error overlays

Some frameworks (e.g. Angular 19 or Next.js) handle errors inside
PostCSS transforms to render a nice error overlay. This works well and
gives immediate feedback that something went wrong. However, even when
dependencies are registered before an error is thrown, these frameworks
_will not consider changes to these dependencies anymore_ when an error
occurs, as you can see in this Next.js example:


https://github.com/user-attachments/assets/985c9dd7-daf8-4628-b4ad-6543ef220954

To avoid conditions where errors are not recoverable, this PR makes it
so that these overlays will no longer show up in the app and only be
logged to the output console. This will need follow-up upstream work
before we can revisit this.

## Test plan

- Tested with the repro in #17295. The error can now be recovered from.
- Tested with a Next.js app where the issue in the screencast above is
now no longer happening.
- Added an integration test for errors in `@import`-ed files
- Added a unit test for the changed `@apply` behavior.

Author: philipp-spiess

CHANGELOG.md

@@ -18,6 +18,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Hide default shadow suggestions when missing theme keys ([#17743](https://github.com/tailwindlabs/tailwindcss/pull/17743))
 - Replace `_` with `.` in theme suggestions for `@utility` if surrounded by digits ([#17743](https://github.com/tailwindlabs/tailwindcss/pull/17743))
 - Upgrade: Bump all Tailwind CSS related dependencies during upgrade ([#17763](https://github.com/tailwindlabs/tailwindcss/pull/17763))
+- PostCSS: Ensure that errors in stylesheet dependencies are recoverable ([#17754](https://github.com/tailwindlabs/tailwindcss/pull/17754))
 
 ## [4.1.4] - 2025-04-14
 

integrations/postcss/index.test.ts

@@ -635,3 +635,91 @@ test(
     await fs.expectFileToContain('project-a/dist/out.css', [candidate`content-['c/src/index.js']`])
   },
 )
+
+test(
+  'rebuild error recovery',
+  {
+    fs: {
+      'package.json': json`
+        {
+          "devDependencies": {
+            "postcss": "^8",
+            "postcss-cli": "^10",
+            "tailwindcss": "workspace:^",
+            "@tailwindcss/postcss": "workspace:^"
+          }
+        }
+      `,
+      'postcss.config.js': js`
+        module.exports = {
+          plugins: {
+            '@tailwindcss/postcss': {},
+          },
+        }
+      `,
+      'src/index.html': html`
+        <div class="underline"></div>
+      `,
+      'src/index.css': css` @import './tailwind.css'; `,
+      'src/tailwind.css': css`
+        @reference 'tailwindcss/does-not-exist';
+        @import 'tailwindcss/utilities';
+      `,
+    },
+  },
+  async ({ fs, expect, spawn }) => {
+    let process = await spawn('pnpm postcss src/index.css --output dist/out.css --watch --verbose')
+
+    await process.onStderr((message) =>
+      message.includes('Package path ./does-not-exist is not exported from package'),
+    )
+
+    expect(await fs.dumpFiles('dist/*.css')).toMatchInlineSnapshot(`
+      "
+      --- dist/out.css ---
+      <EMPTY>
+      "
+    `)
+
+    await process.onStderr((message) => message.includes('Waiting for file changes...'))
+
+    // Fix the CSS file
+    await fs.write(
+      'src/tailwind.css',
+      css`
+        @reference 'tailwindcss/theme';
+        @import 'tailwindcss/utilities';
+      `,
+    )
+    await process.onStderr((message) => message.includes('Finished src/index.css'))
+
+    expect(await fs.dumpFiles('dist/*.css')).toMatchInlineSnapshot(`
+      "
+      --- dist/out.css ---
+      .underline {
+        text-decoration-line: underline;
+      }
+      "
+    `)
+
+    // Now break the CSS file again
+    await fs.write(
+      'src/tailwind.css',
+      css`
+        @reference 'tailwindcss/does-not-exist';
+        @import 'tailwindcss/utilities';
+      `,
+    )
+    await process.onStderr((message) =>
+      message.includes('Package path ./does-not-exist is not exported from package'),
+    )
+    await process.onStderr((message) => message.includes('Finished src/index.css'))
+
+    expect(await fs.dumpFiles('dist/*.css')).toMatchInlineSnapshot(`
+      "
+      --- dist/out.css ---
+      <EMPTY>
+      "
+    `)
+  },
+)