Add PostCSS plugin to fix relative @content and @plugin paths in @imported files (#14063)

We noticed an issue that happened when handling relative file imports in
the `@plugin` and the upcoming `@content` APIs. The problem arises from
relative files that are inside `@import`ed stylesheets. Take, for
example, the following folder structure:

```css
/* src/index.css */
@import "./dir/index.css";
```
```css
/* src/dir/index.css */
@plugin "../../plugin.ts";
```

It's expected that the path is relative to the CSS file that defined it.
However, right now, we use
[`postcss-import`](https://github.com/postcss/postcss-import) to flatten
the CSS file before running the tailwind build step. This causes these
custom-properties to be inlined in a flat file which removes the
information of which file is being referred:

```css
/* src/flat.css */
@plugin "../../plugin.ts"; /* <- This is now pointing to the wrong file */
```

There are generally two approaches that we can do to solve this:

1. **Handle `@import` flattening inside tailwindcss:** While generally
this would give us more freedom and less dependencies, this would
require some work to get all edge cases right. We need to support
layers/conditional imports and also handle all relative urls for
properties like `background-image`.
2. **Rewrite relative paths as a separate postcss visitor:** The
approach this PR takes is instead to implement a custom postcss plugin
that uses the AST to rewrite relative references inside `@plugin` and
`@content`. This has the benefit of requiring little changes to our
existing APIs. The rule is only enabled for relative references inside
`@plugin` and `@content`, so the surface of this rule is very small.

We can use this plugin inside all three current clients:

- `@tailwindcss/postcss` obviously already uses postcss
- `@tailwindcss/cli` also uses postcss to handle `@import` flattening
- `@tailwindcss/vite` allows us to add custom postcss rules via the CSS
pipeline. There are a few cases that we handle with care (e.g. in vite
you can pass a string to the postcss config which is supposed to load
the config from a file).

To validate the changes, we have added both a list of unit test cases to
the plugin itself as well as verified that all three clients are working
as expected:

- `@tailwindcss/postcss` now has an explicit test for this behavior
- `@tailwindcss/cli` and `@tailwindcss/vite` were manually tested by
updating the vite playground. The CLI was run with `--cwd
playgrounds/vite/ -i ./src/app.css -o foo.css`:
<img width="531" alt="Screenshot 2024-07-29 at 11 35 59"
src="https://github.com/user-attachments/assets/78f0acdc-a46c-4c6c-917a-2916417b1001">

Author: philipp-spiess

packages/@tailwindcss-cli/package.json

@@ -12,7 +12,7 @@
   "homepage": "https://tailwindcss.com",
   "scripts": {
     "lint": "tsc --noEmit",
-    "build": "tsup-node ./src/index.ts --format esm --minify --clean",
+    "build": "tsup-node",
     "dev": "pnpm run build -- --watch"
   },
   "bin": {
@@ -36,7 +36,8 @@
     "picocolors": "^1.0.1",
     "postcss": "8.4.24",
     "postcss-import": "^16.1.0",
-    "tailwindcss": "workspace:^"
+    "tailwindcss": "workspace:^",
+    "internal-postcss-fix-relative-paths": "workspace:^"
   },
   "devDependencies": {
     "@types/postcss-import": "^14.0.3"

packages/@tailwindcss-cli/src/commands/build/index.ts

@@ -1,5 +1,6 @@
 import watcher from '@parcel/watcher'
 import { IO, Parsing, scanDir, scanFiles, type ChangedContent } from '@tailwindcss/oxide'
+import fixRelativePathsPlugin from 'internal-postcss-fix-relative-paths'
 import { Features, transform } from 'lightningcss'
 import { existsSync } from 'node:fs'
 import fs from 'node:fs/promises'
@@ -259,6 +260,7 @@ function handleImports(
 
   return postcss()
     .use(atImport())
+    .use(fixRelativePathsPlugin())
     .process(input, { from: file })
     .then((result) => [
       result.css,

packages/@tailwindcss-cli/tsup.config.ts

@@ -0,0 +1,9 @@
+import { defineConfig } from 'tsup'
+
+export default defineConfig({
+  format: ['esm'],
+  clean: true,
+  minify: true,
+  entry: ['src/index.ts'],
+  noExternal: ['internal-postcss-fix-relative-paths'],
+})

packages/@tailwindcss-postcss/package.json

@@ -12,7 +12,7 @@
   "homepage": "https://tailwindcss.com",
   "scripts": {
     "lint": "tsc --noEmit",
-    "build": "tsup-node ./src/index.ts --format cjs,esm --dts --cjsInterop --splitting --minify --clean",
+    "build": "tsup-node",
     "dev": "pnpm run build -- --watch"
   },
   "files": [
@@ -33,7 +33,8 @@
     "@tailwindcss/oxide": "workspace:^",
     "lightningcss": "^1.25.1",
     "postcss-import": "^16.1.0",
-    "tailwindcss": "workspace:^"
+    "tailwindcss": "workspace:^",
+    "internal-postcss-fix-relative-paths": "workspace:^"
   },
   "devDependencies": {
     "@types/node": "^20.12.12",

packages/@tailwindcss-postcss/src/fixtures/example-project/src/relative-import.css

@@ -0,0 +1 @@
+@plugin '../plugin.js';

packages/@tailwindcss-postcss/src/index.test.ts

@@ -144,7 +144,7 @@ describe('plugins', () => {
     let result = await processor.process(
       css`
         @import 'tailwindcss/utilities';
-        @plugin 'internal-example-plugin';
+        @plugin './plugin.js';
       `,
       { from: INPUT_CSS_PATH },
     )
@@ -166,6 +166,36 @@ describe('plugins', () => {
     `)
   })
 
+  test('local CJS plugin from `@import`-ed file', async () => {
+    let processor = postcss([
+      tailwindcss({ base: `${__dirname}/fixtures/example-project`, optimize: { minify: false } }),
+    ])
+
+    let result = await processor.process(
+      css`
+        @import 'tailwindcss/utilities';
+        @import '../example-project/src/relative-import.css';
+      `,
+      { from: `${__dirname}/fixtures/another-project/input.css` },
+    )
+
+    expect(result.css.trim()).toMatchInlineSnapshot(`
+      ".underline {
+        text-decoration-line: underline;
+      }
+
+      @media (inverted-colors: inverted) {
+        .inverted\\:flex {
+          display: flex;
+        }
+      }
+
+      .hocus\\:underline:focus, .hocus\\:underline:hover {
+        text-decoration-line: underline;
+      }"
+    `)
+  })
+
   test('published CJS plugin', async () => {
     let processor = postcss([
       tailwindcss({ base: `${__dirname}/fixtures/example-project`, optimize: { minify: false } }),

packages/@tailwindcss-postcss/src/index.ts

@@ -2,9 +2,10 @@ import { scanDir } from '@tailwindcss/oxide'
 import fs from 'fs'
 import { Features, transform } from 'lightningcss'
 import path from 'path'
-import postcss, { type AcceptedPlugin, type PluginCreator } from 'postcss'
+import postcss, { AtRule, type AcceptedPlugin, type PluginCreator } from 'postcss'
 import postcssImport from 'postcss-import'
 import { compile } from 'tailwindcss'
+import fixRelativePathsPlugin from '../../internal-postcss-fix-relative-paths/src'
 
 /**
  * A Map that can generate default values for keys that don't exist.
@@ -48,114 +49,118 @@ function tailwindcss(opts: PluginOptions = {}): AcceptedPlugin {
     }
   })
 
+  let hasApply: boolean, hasTailwind: boolean
+
   return {
     postcssPlugin: '@tailwindcss/postcss',
     plugins: [
       // We need to run `postcss-import` first to handle `@import` rules.
       postcssImport(),
+      fixRelativePathsPlugin(),
+
+      {
+        postcssPlugin: 'tailwindcss',
+        Once() {
+          // Reset some state between builds
+          hasApply = false
+          hasTailwind = false
+        },
+        AtRule(rule: AtRule) {
+          if (rule.name === 'apply') {
+            hasApply = true
+          } else if (rule.name === 'tailwind') {
+            hasApply = true
+            hasTailwind = true
+          }
+        },
+        OnceExit(root, { result }) {
+          let inputFile = result.opts.from ?? ''
+          let context = cache.get(inputFile)
+
+          let rebuildStrategy: 'full' | 'incremental' = 'incremental'
+
+          // Track file modification times to CSS files
+          {
+            let files = result.messages.flatMap((message) => {
+              if (message.type !== 'dependency') return []
+              return message.file
+            })
+            files.push(inputFile)
+            for (let file of files) {
+              let changedTime = fs.statSync(file, { throwIfNoEntry: false })?.mtimeMs ?? null
+              if (changedTime === null) {
+                if (file === inputFile) {
+                  rebuildStrategy = 'full'
+                }
+                continue
+              }
 
-      (root, result) => {
-        let inputFile = result.opts.from ?? ''
-        let context = cache.get(inputFile)
-
-        let rebuildStrategy: 'full' | 'incremental' = 'incremental'
+              let prevTime = context.mtimes.get(file)
+              if (prevTime === changedTime) continue
 
-        // Track file modification times to CSS files
-        {
-          let files = result.messages.flatMap((message) => {
-            if (message.type !== 'dependency') return []
-            return message.file
-          })
-          files.push(inputFile)
-          for (let file of files) {
-            let changedTime = fs.statSync(file, { throwIfNoEntry: false })?.mtimeMs ?? null
-            if (changedTime === null) {
-              if (file === inputFile) {
-                rebuildStrategy = 'full'
-              }
-              continue
+              rebuildStrategy = 'full'
+              context.mtimes.set(file, changedTime)
             }
+          }
 
-            let prevTime = context.mtimes.get(file)
-            if (prevTime === changedTime) continue
+          // Do nothing if neither `@tailwind` nor `@apply` is used
+          if (!hasTailwind && !hasApply) return
 
-            rebuildStrategy = 'full'
-            context.mtimes.set(file, changedTime)
+          let css = ''
+
+          // Look for candidates used to generate the CSS
+          let { candidates, files, globs } = scanDir({ base, globs: true })
+
+          // Add all found files as direct dependencies
+          for (let file of files) {
+            result.messages.push({
+              type: 'dependency',
+              plugin: '@tailwindcss/postcss',
+              file,
+              parent: result.opts.from,
+            })
           }
-        }
 
-        let hasApply = false
-        let hasTailwind = false
+          // Register dependencies so changes in `base` cause a rebuild while
+          // giving tools like Vite or Parcel a glob that can be used to limit
+          // the files that cause a rebuild to only those that match it.
+          for (let { base, glob } of globs) {
+            result.messages.push({
+              type: 'dir-dependency',
+              plugin: '@tailwindcss/postcss',
+              dir: base,
+              glob,
+              parent: result.opts.from,
+            })
+          }
 
-        root.walkAtRules((rule) => {
-          if (rule.name === 'apply') {
-            hasApply = true
-          } else if (rule.name === 'tailwind') {
-            hasApply = true
-            hasTailwind = true
-            // If we've found `@tailwind` then we already
-            // know we have to run a "full" build
-            return false
+          if (rebuildStrategy === 'full') {
+            let basePath = path.dirname(path.resolve(inputFile))
+            let { build } = compile(root.toString(), {
+              loadPlugin: (pluginPath) => {
+                if (pluginPath[0] === '.') {
+                  return require(path.resolve(basePath, pluginPath))
+                }
+
+                return require(pluginPath)
+              },
+            })
+            context.build = build
+            css = build(hasTailwind ? candidates : [])
+          } else if (rebuildStrategy === 'incremental') {
+            css = context.build!(candidates)
           }
-        })
-
-        // Do nothing if neither `@tailwind` nor `@apply` is used
-        if (!hasTailwind && !hasApply) return
-
-        let css = ''
-
-        // Look for candidates used to generate the CSS
-        let { candidates, files, globs } = scanDir({ base, globs: true })
-
-        // Add all found files as direct dependencies
-        for (let file of files) {
-          result.messages.push({
-            type: 'dependency',
-            plugin: '@tailwindcss/postcss',
-            file,
-            parent: result.opts.from,
-          })
-        }
-
-        // Register dependencies so changes in `base` cause a rebuild while
-        // giving tools like Vite or Parcel a glob that can be used to limit
-        // the files that cause a rebuild to only those that match it.
-        for (let { base, glob } of globs) {
-          result.messages.push({
-            type: 'dir-dependency',
-            plugin: '@tailwindcss/postcss',
-            dir: base,
-            glob,
-            parent: result.opts.from,
-          })
-        }
-
-        if (rebuildStrategy === 'full') {
-          let basePath = path.dirname(path.resolve(inputFile))
-          let { build } = compile(root.toString(), {
-            loadPlugin: (pluginPath) => {
-              if (pluginPath[0] === '.') {
-                return require(path.resolve(basePath, pluginPath))
-              }
 
-              return require(pluginPath)
-            },
-          })
-          context.build = build
-          css = build(hasTailwind ? candidates : [])
-        } else if (rebuildStrategy === 'incremental') {
-          css = context.build!(candidates)
-        }
-
-        // Replace CSS
-        if (css !== context.css && optimize) {
-          context.optimizedCss = optimizeCss(css, {
-            minify: typeof optimize === 'object' ? optimize.minify : true,
-          })
-        }
-        context.css = css
-        root.removeAll()
-        root.append(postcss.parse(optimize ? context.optimizedCss : context.css, result.opts))
+          // Replace CSS
+          if (css !== context.css && optimize) {
+            context.optimizedCss = optimizeCss(css, {
+              minify: typeof optimize === 'object' ? optimize.minify : true,
+            })
+          }
+          context.css = css
+          root.removeAll()
+          root.append(postcss.parse(optimize ? context.optimizedCss : context.css, result.opts))
+        },
       },
     ],
   }

packages/@tailwindcss-postcss/tsup.config.ts

@@ -0,0 +1,12 @@
+import { defineConfig } from 'tsup'
+
+export default defineConfig({
+  format: ['esm', 'cjs'],
+  clean: true,
+  minify: true,
+  splitting: true,
+  cjsInterop: true,
+  dts: true,
+  entry: ['src/index.ts'],
+  noExternal: ['internal-postcss-fix-relative-paths'],
+})

packages/@tailwindcss-vite/package.json

@@ -11,7 +11,7 @@
   "bugs": "https://github.com/tailwindlabs/tailwindcss/issues",
   "homepage": "https://tailwindcss.com",
   "scripts": {
-    "build": "tsup-node ./src/index.ts --format esm --dts --minify --clean",
+    "build": "tsup-node",
     "dev": "pnpm run build -- --watch"
   },
   "files": [
@@ -30,10 +30,12 @@
   "dependencies": {
     "@tailwindcss/oxide": "workspace:^",
     "lightningcss": "^1.25.1",
+    "postcss-load-config": "^6.0.1",
     "tailwindcss": "workspace:^"
   },
   "devDependencies": {
     "@types/node": "^20.12.12",
+    "internal-postcss-fix-relative-paths": "workspace:^",
     "vite": "^5.2.11"
   },
   "peerDependencies": {