Resolve @import in core (#14446)

This PR brings `@import` resolution into Tailwind CSS core. This means
that our clients (PostCSS, Vite, and CLI) no longer need to depend on
`postcss` and `postcss-import` to resolve `@import`. Furthermore this
simplifies the handling of relative paths for `@source`, `@plugin`, or
`@config` in transitive CSS files (where the relative root should always
be relative to the CSS file that contains the directive). This PR also
fixes a plugin resolution bug where non-relative imports (e.g. directly
importing node modules like `@plugin '@tailwindcss/typography';`) would
not work in CSS files that are based in a different npm package.

### Resolving `@import`

The core of the `@import` resolution is inside
`packages/tailwindcss/src/at-import.ts`. There, to keep things
performant, we do a two-step process to resolve imports. Imagine the
following input CSS file:

```css
@import "tailwindcss/theme.css";
@import "tailwindcss/utilities.css";
```

Since our AST walks are synchronous, we will do a first traversal where
we start a loading request for each `@import` directive. Once all loads
are started, we will await the promise and do a second walk where we
actually replace the AST nodes with their resolved stylesheets. All of
this is recursive, so that `@import`-ed files can again `@import` other
files.

The core `@import` resolver also includes extensive test cases for
[various combinations of media query and supports conditionals as well
als layered
imports](https://developer.mozilla.org/en-US/docs/Web/CSS/@import).

When the same file is imported multiple times, the AST nodes are
duplicated but duplicate I/O is avoided on a per-file basis, so this
will only load one file, but include the `@theme` rules twice:

```css
@import "tailwindcss/theme.css";
@import "tailwindcss/theme.css";
```

### Adding a new `context` node to the AST

One limitation we had when working with the `postcss-import` plugin was
the need to do an additional traversal to rewrite relative `@source`,
`@plugin`, and `@config` directives. This was needed because we want
these paths to be relative to the CSS file that defines the directive
but when flattening a CSS file, this information is no longer part of
the stringifed CSS representation. We worked around this by rewriting
the content of these directives to be relative to the input CSS file,
which resulted in added complexity and caused a lot of issues with
Windows paths in the beginning.

Now that we are doing the `@import` resolution in core, we can use a
different data structure to persist this information. This PR adds a new
`context` node so that we can store arbitrary context like this inside
the Ast directly. This allows us to share information with the sub tree
_while doing the Ast walk_.

Here's an example of how the new `context` node can be used to share
information with subtrees:

```ts
const ast = [
  rule('.foo', [decl('color', 'red')]),
  context({ value: 'a' }, [
    rule('.bar', [
      decl('color', 'blue'),
      context({ value: 'b' }, [
        rule('.baz', [decl('color', 'green')]),
      ]),
    ]),
  ]),
]

walk(ast, (node, { context }) => {
  if (node.kind !== 'declaration') return
  switch (node.value) {
    case 'red':   assert(context.value === undefined)
    case 'blue':  assert(context.value === 'a')
    case 'green': assert(context.value === 'b')
  }
})
```

In core, we use this new Ast node specifically to persist the `base`
path of the current CSS file. We put the input CSS file `base` at the
root of the Ast and then overwrite the `base` on every `@import`
substitution.

### Removing the dependency on `postcss-import`

Now that we support `@import` resolution in core, our clients no longer
need a dependency on `postcss-import`. Furthermore, most dependencies
also don't need to know about `postcss` at all anymore (except the
PostCSS client, of course!).

This also means that our workaround for rewriting `@source`, the
`postcss-fix-relative-paths` plugin, can now go away as a shared
dependency between all of our clients. Note that we still have it for
the PostCSS plugin only, where it's possible that users already have
`postcss-import` running _before_ the `@tailwindcss/postcss` plugin.

Here's an example of the changes to the dependencies for our Vite client
✨ :

<img width="854" alt="Screenshot 2024-09-19 at 16 59 45"
src="https://github.com/user-attachments/assets/ae1f9d5f-d93a-4de9-9244-61af3aff1237">

### Performance

Since our Vite and CLI clients now no longer need to use `postcss` at
all, we have also measured a significant improvement to the initial
build times. For a small test setup that contains only a hand full of
files (nothing super-complex), we measured an improvement in the
**3.5x** range:

<img width="1334" alt="Screenshot 2024-09-19 at 14 52 49"
src="https://github.com/user-attachments/assets/06071fb0-7f2a-4de6-8ec8-f202d2cc78e5">

The code for this is in the commit history if you want to reproduce the
results. The test was based on the Vite client.

### Caveats

One thing to note is that we previously relied on finding specific
symbols in the input CSS to _bail out of Tailwind processing
completely_. E.g. if a file does not contain a `@tailwind` or `@apply`
directive, it can never be a Tailwind file.

Since we no longer have a string representation of the flattened CSS
file, we can no longer do this check. However, the current
implementation was already inconsistent with differences on the allowed
symbol list between our clients. Ideally, Tailwind CSS should figure out
wether a CSS file is a Tailwind CSS file. This, however, is left as an
improvement for a future API since it goes hand-in-hand with our planned
API changes for the core `tailwindcss` package.

---------

Co-authored-by: Jordan Pittman <[email protected]>

Author: philipp-spiess

CHANGELOG.md

@@ -33,6 +33,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Disallow negative bare values in core utilities and variants ([#14453](https://github.com/tailwindlabs/tailwindcss/pull/14453))
 - Preserve explicit shadow color when overriding shadow size ([#14458](https://github.com/tailwindlabs/tailwindcss/pull/14458))
 - Preserve explicit transition duration and timing function when overriding transition property ([#14490](https://github.com/tailwindlabs/tailwindcss/pull/14490))
+- Change the implementation for `@import` resolution to speed up initial builds ([#14446](https://github.com/tailwindlabs/tailwindcss/pull/14446))
 
 ## [4.0.0-alpha.24] - 2024-09-11
 

integrations/postcss/index.test.ts

@@ -79,6 +79,86 @@ test(
   },
 )
 
+test(
+  'production build with `postcss-import` (string)',
+  {
+    fs: {
+      'package.json': json`{}`,
+      'pnpm-workspace.yaml': yaml`
+        #
+        packages:
+          - project-a
+      `,
+      'project-a/package.json': json`
+        {
+          "dependencies": {
+            "postcss": "^8",
+            "postcss-cli": "^10",
+            "postcss-import": "^16",
+            "tailwindcss": "workspace:^",
+            "@tailwindcss/postcss": "workspace:^"
+          }
+        }
+      `,
+      'project-a/postcss.config.js': js`
+        module.exports = {
+          plugins: {
+            'postcss-import': {},
+            '@tailwindcss/postcss': {},
+          },
+        }
+      `,
+      'project-a/index.html': html`
+        <div
+          class="underline 2xl:font-bold hocus:underline inverted:flex"
+        ></div>
+      `,
+      'project-a/plugin.js': js`
+        module.exports = function ({ addVariant }) {
+          addVariant('inverted', '@media (inverted-colors: inverted)')
+          addVariant('hocus', ['&:focus', '&:hover'])
+        }
+      `,
+      'project-a/tailwind.config.js': js`
+        module.exports = {
+          content: ['../project-b/src/**/*.js'],
+        }
+      `,
+      'project-a/src/index.css': css`
+        @import 'tailwindcss/utilities';
+        @config '../tailwind.config.js';
+        @source '../../project-b/src/**/*.html';
+        @plugin '../plugin.js';
+      `,
+      'project-a/src/index.js': js`
+        const className = "content-['a/src/index.js']"
+        module.exports = { className }
+      `,
+      'project-b/src/index.html': html`
+        <div class="flex" />
+      `,
+      'project-b/src/index.js': js`
+        const className = "content-['b/src/index.js']"
+        module.exports = { className }
+      `,
+    },
+  },
+  async ({ root, fs, exec }) => {
+    await exec('pnpm postcss src/index.css --output dist/out.css', {
+      cwd: path.join(root, 'project-a'),
+    })
+
+    await fs.expectFileToContain('project-a/dist/out.css', [
+      candidate`underline`,
+      candidate`flex`,
+      candidate`content-['a/src/index.js']`,
+      candidate`content-['b/src/index.js']`,
+      candidate`inverted:flex`,
+      candidate`hocus:underline`,
+    ])
+  },
+)
+
 test(
   'production build (ESM)',
   {

packages/@tailwindcss-cli/package.json

@@ -36,12 +36,6 @@
     "lightningcss": "catalog:",
     "mri": "^1.2.0",
     "picocolors": "^1.0.1",
-    "postcss-import": "^16.1.0",
-    "postcss": "^8.4.41",
     "tailwindcss": "workspace:^"
-  },
-  "devDependencies": {
-    "@types/postcss-import": "^14.0.3",
-    "internal-postcss-fix-relative-paths": "workspace:^"
   }
 }

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

@@ -2,13 +2,10 @@ import watcher from '@parcel/watcher'
 import { compile } from '@tailwindcss/node'
 import { clearRequireCache } from '@tailwindcss/node/require-cache'
 import { Scanner, type ChangedContent } from '@tailwindcss/oxide'
-import fixRelativePathsPlugin from 'internal-postcss-fix-relative-paths'
 import { Features, transform } from 'lightningcss'
-import { existsSync, readFileSync } from 'node:fs'
+import { existsSync } from 'node:fs'
 import fs from 'node:fs/promises'
 import path from 'node:path'
-import postcss from 'postcss'
-import atImport from 'postcss-import'
 import type { Arg, Result } from '../../utils/args'
 import { Disposables } from '../../utils/disposables'
 import {
@@ -19,7 +16,6 @@ import {
   println,
   relative,
 } from '../../utils/renderer'
-import { resolveCssId } from '../../utils/resolve'
 import { drainStdin, outputFile } from './utils'
 
 const css = String.raw
@@ -83,17 +79,13 @@ export async function handle(args: Result<ReturnType<typeof options>>) {
 
   let start = process.hrtime.bigint()
 
-  // Resolve the input
-  let [input, cssImportPaths] = await handleImports(
-    args['--input']
-      ? args['--input'] === '-'
-        ? await drainStdin()
-        : await fs.readFile(args['--input'], 'utf-8')
-      : css`
-          @import 'tailwindcss';
-        `,
-    args['--input'] ?? base,
-  )
+  let input = args['--input']
+    ? args['--input'] === '-'
+      ? await drainStdin()
+      : await fs.readFile(args['--input'], 'utf-8')
+    : css`
+        @import 'tailwindcss';
+      `
 
   let previous = {
     css: '',
@@ -128,7 +120,7 @@ export async function handle(args: Result<ReturnType<typeof options>>) {
 
   let inputFile = args['--input'] && args['--input'] !== '-' ? args['--input'] : process.cwd()
   let inputBasePath = path.dirname(path.resolve(inputFile))
-  let fullRebuildPaths: string[] = cssImportPaths.slice()
+  let fullRebuildPaths: string[] = []
 
   function createCompiler(css: string) {
     return compile(css, {
@@ -143,12 +135,7 @@ export async function handle(args: Result<ReturnType<typeof options>>) {
   let compiler = await createCompiler(input)
   let scanner = new Scanner({
     detectSources: { base },
-    sources: compiler.globs.map(({ origin, pattern }) => ({
-      // Ensure the glob is relative to the input CSS file or the config file
-      // where it is specified.
-      base: origin ? path.dirname(path.resolve(inputBasePath, origin)) : inputBasePath,
-      pattern,
-    })),
+    sources: compiler.globs,
   })
 
   // Watch for changes
@@ -196,30 +183,24 @@ export async function handle(args: Result<ReturnType<typeof options>>) {
             // Clear all watchers
             cleanupWatchers()
 
-            // Collect the new `input` and `cssImportPaths`.
-            ;[input, cssImportPaths] = await handleImports(
-              args['--input']
-                ? await fs.readFile(args['--input'], 'utf-8')
-                : css`
-                    @import 'tailwindcss';
-                  `,
-              args['--input'] ?? base,
-            )
+            // Read the new `input`.
+            let input = args['--input']
+              ? args['--input'] === '-'
+                ? await drainStdin()
+                : await fs.readFile(args['--input'], 'utf-8')
+              : css`
+                  @import 'tailwindcss';
+                `
             clearRequireCache(resolvedFullRebuildPaths)
-            fullRebuildPaths = cssImportPaths.slice()
+            fullRebuildPaths = []
 
             // Create a new compiler, given the new `input`
             compiler = await createCompiler(input)
 
             // Re-scan the directory to get the new `candidates`
             scanner = new Scanner({
               detectSources: { base },
-              sources: compiler.globs.map(({ origin, pattern }) => ({
-                // Ensure the glob is relative to the input CSS file or the
-                // config file where it is specified.
-                base: origin ? path.dirname(path.resolve(inputBasePath, origin)) : inputBasePath,
-                pattern,
-              })),
+              sources: compiler.globs,
             })
 
             // Scan the directory for candidates
@@ -367,51 +348,6 @@ async function createWatchers(dirs: string[], cb: (files: string[]) => void) {
   }
 }
 
-function handleImports(
-  input: string,
-  file: string,
-): [css: string, paths: string[]] | Promise<[css: string, paths: string[]]> {
-  // TODO: Should we implement this ourselves instead of relying on PostCSS?
-  //
-  // Relevant specification:
-  //   - CSS Import Resolve: https://csstools.github.io/css-import-resolve/
-
-  if (!input.includes('@import')) {
-    return [input, [file]]
-  }
-
-  return postcss()
-    .use(
-      atImport({
-        resolve(id, basedir) {
-          let resolved = resolveCssId(id, basedir)
-          if (!resolved) {
-            throw new Error(`Could not resolve ${id} from ${basedir}`)
-          }
-          return resolved
-        },
-        load(id) {
-          // We need to synchronously read the file here because when bundled
-          // with bun, some of the ids might resolve to files inside the bun
-          // embedded files root which can only be read by `node:fs` and not
-          // `node:fs/promises`.
-          return readFileSync(id, 'utf-8')
-        },
-      }),
-    )
-    .use(fixRelativePathsPlugin())
-    .process(input, { from: file })
-    .then((result) => [
-      result.css,
-
-      // Use `result.messages` to get the imported files. This also includes the
-      // current file itself.
-      [file].concat(
-        result.messages.filter((msg) => msg.type === 'dependency').map((msg) => msg.file),
-      ),
-    ])
-}
-
 function optimizeCss(
   input: string,
   { file = 'input.css', minify = false }: { file?: string; minify?: boolean } = {},

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

@@ -5,5 +5,4 @@ export default defineConfig({
   clean: true,
   minify: true,
   entry: ['src/index.ts'],
-  noExternal: ['internal-postcss-fix-relative-paths'],
 })

packages/@tailwindcss-node/package.json

@@ -40,6 +40,7 @@
     "tailwindcss": "workspace:^"
   },
   "dependencies": {
+    "enhanced-resolve": "^5.17.1",
     "jiti": "^2.0.0-beta.3"
   }
 }