Ensure @import url(…) is hoisted

CHANGELOG.md

@@ -12,6 +12,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Ensure that the `containers` JS theme key is added to the `--container-*` namespace ([#16169](https://github.com/tailwindlabs/tailwindcss/pull/16169))
 - Fix missing `@keyframes` definition ([#16237](https://github.com/tailwindlabs/tailwindcss/pull/16237))
 - Vite: Skip parsing stylesheets with the `?commonjs-proxy` flag ([#16238](https://github.com/tailwindlabs/tailwindcss/pull/16238))
+- Ensure `@import url(…)` is hoisted ([#16203](https://github.com/tailwindlabs/tailwindcss/pull/16203))
 
 ## [4.0.3] - 2025-02-01
 

integrations/cli/index.test.ts

@@ -1253,3 +1253,44 @@ test(
     `)
   },
 )
+
+test(
+  'external imports are properly hoisted to the top',
+  {
+    fs: {
+      'package.json': json`
+        {
+          "dependencies": {
+            "tailwindcss": "workspace:^",
+            "@tailwindcss/cli": "workspace:^"
+          }
+        }
+      `,
+      'index.html': html`
+          <div class="underline flex"></div>
+        `,
+      'src/index.css': css`
+        @charset "UTF-8";
+        @import 'tailwindcss/utilities';
+        @import url('https://fonts.googleapis.com/css2?family=Roboto&display=swap');
+      `,
+    },
+  },
+  async ({ fs, exec, expect }) => {
+    await exec('pnpm tailwindcss --input src/index.css --output dist/out.css')
+
+    expect(await fs.dumpFiles('./dist/*.css')).toMatchInlineSnapshot(`
+      "
+      --- ./dist/out.css ---
+      @charset "UTF-8";
+      @import url('https://fonts.googleapis.com/css2?family=Roboto&display=swap');
+      .flex {
+        display: flex;
+      }
+      .underline {
+        text-decoration-line: underline;
+      }
+      "
+    `)
+  },
+)

packages/tailwindcss/src/ast.test.ts

@@ -1,6 +1,7 @@
 import { expect, it } from 'vitest'
 import { context, decl, optimizeAst, styleRule, toCss, walk, WalkAction } from './ast'
 import * as CSS from './css-parser'
+import { compileCss } from './test-utils/run'
 
 const css = String.raw
 
@@ -181,10 +182,47 @@ it('should not emit empty rules once optimized', () => {
 
   expect(toCss(optimizeAst(ast))).toMatchInlineSnapshot(`
     "@charset "UTF-8";
+    @import url('https://fonts.googleapis.com/css2?family=Cedarville+Cursive&display=swap');
     @layer foo, bar, baz;
     @custom-media --modern (color), (hover);
     @namespace 'http://www.w3.org/1999/xhtml';
+    "
+  `)
+})
+
+it('should hoist external imports to the top', async () => {
+  let input = css`
+    @charset "UTF-8";
+    @import 'tailwindcss';
+    @import url('https://fonts.googleapis.com/css2?family=Cedarville+Cursive&display=swap');
+  `
+  let ast = CSS.parse(input)
+
+  expect(toCss(ast)).toMatchInlineSnapshot(`
+    "@charset "UTF-8";
+    @import 'tailwindcss';
     @import url('https://fonts.googleapis.com/css2?family=Cedarville+Cursive&display=swap');
     "
   `)
+
+  expect(toCss(optimizeAst(ast))).toMatchInlineSnapshot(`
+    "@charset "UTF-8";
+    @import 'tailwindcss';
+    @import url('https://fonts.googleapis.com/css2?family=Cedarville+Cursive&display=swap');
+    "
+  `)
+
+  expect(
+    await compileCss(input, ['flex'], {
+      async loadStylesheet(_id, base) {
+        return { content: '@tailwind utilities;', base }
+      },
+    }),
+  ).toMatchInlineSnapshot(`
+    "@import "https://fonts.googleapis.com/css2?family=Cedarville+Cursive&display=swap";
+
+    .flex {
+      display: flex;
+    }"
+  `)
 })

packages/tailwindcss/src/ast.ts

@@ -240,6 +240,9 @@ export function walkDepth(
 export function optimizeAst(ast: AstNode[]) {
   let atRoots: AstNode[] = []
   let seenAtProperties = new Set<string>()
+  let licenses: AstNode[] = []
+  let charsets: AstNode[] = []
+  let imports: AstNode[] = []
 
   function transform(
     node: AstNode,
@@ -301,13 +304,22 @@ export function optimizeAst(ast: AstNode[]) {
       for (let child of node.nodes) {
         transform(child, copy.nodes, depth + 1)
       }
+
+      if (copy.name === '@charset') {
+        charsets.push(copy)
+        return
+      }
+
+      if (copy.name === '@import') {
+        imports.push(copy)
+        return
+      }
+
       if (
         copy.nodes.length > 0 ||
         copy.name === '@layer' ||
-        copy.name === '@charset' ||
         copy.name === '@custom-media' ||
-        copy.name === '@namespace' ||
-        copy.name === '@import'
+        copy.name === '@namespace'
       ) {
         parent.push(copy)
       }
@@ -338,6 +350,10 @@ export function optimizeAst(ast: AstNode[]) {
 
     // Comment
     else if (node.kind === 'comment') {
+      if (node.value[0] === '!') {
+        licenses.push(node)
+        return
+      }
       parent.push(node)
     }
 
@@ -352,7 +368,7 @@ export function optimizeAst(ast: AstNode[]) {
     transform(node, newAst, 0)
   }
 
-  return newAst.concat(atRoots)
+  return licenses.concat(charsets, imports, newAst, atRoots)
 }
 
 export function toCss(ast: AstNode[]) {

packages/tailwindcss/src/test-utils/run.ts

@@ -1,7 +1,11 @@
 import { Features, transform } from 'lightningcss'
 import { compile } from '..'
 
-export async function compileCss(css: string, candidates: string[] = [], options = {}) {
+export async function compileCss(
+  css: string,
+  candidates: string[] = [],
+  options: Parameters<typeof compile>[1] = {},
+) {
   let { build } = await compile(css, options)
   return optimizeCss(build(candidates)).trim()
 }