Add @reference "…"

Author: philipp-spiess

CHANGELOG.md

@@ -7,6 +7,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added
+
+- Add `@reference "…"` API as a replacement for the previous `@import "…" reference` option ([#15228](https://github.com/tailwindlabs/tailwindcss/pull/15228))
+
 ### Fixed
 
 - Use the correct property value for `place-content-between`, `place-content-around`, and `place-content-evenly` utilities ([#15440](https://github.com/tailwindlabs/tailwindcss/pull/15440))
@@ -782,4 +786,3 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ## [4.0.0-alpha.1] - 2024-03-06
 
 - First 4.0.0-alpha.1 release
-

packages/tailwindcss/src/at-import.test.ts

@@ -553,3 +553,36 @@ test('it crashes when inside a cycle', async () => {
     `[Error: Exceeded maximum recursion depth while resolving \`foo.css\` in \`/root\`)]`,
   )
 })
+
+test('resolves @reference as `@import "…" reference`', async () => {
+  let loadStylesheet = async (id: string, base: string) => {
+    expect(base).toBe('/root')
+    expect(id).toBe('./foo/bar.css')
+    return {
+      content: css`
+        @theme {
+          --color-red-500: red;
+        }
+        .foo {
+          color: red;
+        }
+      `,
+      base: '/root/foo',
+    }
+  }
+
+  await expect(
+    run(
+      css`
+        @reference './foo/bar.css';
+        @tailwind utilities;
+      `,
+      { loadStylesheet, candidates: ['text-red-500'] },
+    ),
+  ).resolves.toMatchInlineSnapshot(`
+    ".text-red-500 {
+      color: var(--color-red-500);
+    }
+    "
+  `)
+})

packages/tailwindcss/src/at-import.ts

@@ -15,9 +15,12 @@ export async function substituteAtImports(
   let promises: Promise<void>[] = []
 
   walk(ast, (node, { replaceWith }) => {
-    if (node.kind === 'at-rule' && node.name === '@import') {
+    if (node.kind === 'at-rule' && (node.name === '@import' || node.name === '@reference')) {
       let parsed = parseImportParams(ValueParser.parse(node.params))
       if (parsed === null) return
+      if (node.name === '@reference') {
+        parsed.media = 'reference'
+      }
 
       features |= Features.AtImport