From 1238d07ca2cc8ed2145b30aa239a9d1570994cf2 Mon Sep 17 00:00:00 2001
From: Philipp Spiess <hello@philippspiess.com>
Date: Thu, 5 Dec 2024 16:18:06 +0100
Subject: [PATCH] Reference imports should not generate utilities (#15307)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

We noticed an issue where the new `@import "…" reference` syntax was not
throwing away `@tailwind` declarations, effectively causing you to
create utility classes whenever you used this feature.

This is especially noticed in setups with very strict compilers like
Svelte.

## Test Plan

### Before

<img width="1142" alt="Screenshot 2024-12-05 at 11 56 00"
src="https://github.com/user-attachments/assets/546f0eb3-4401-48c9-9268-76992e899226">

### After

<img width="2560" alt="Screenshot 2024-12-05 at 12 27 30"
src="https://github.com/user-attachments/assets/16732000-e02c-49bc-ac6f-91da0cfcc7e8">
---
 CHANGELOG.md                           |  4 +++-
 integrations/vite/svelte.test.ts       | 11 ++++------
 integrations/vite/vue.test.ts          |  2 +-
 packages/tailwindcss/src/index.test.ts | 30 ++++++++++++++++++++++++++
 packages/tailwindcss/src/index.ts      | 16 +++++++++++---
 5 files changed, 51 insertions(+), 12 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 6e7e13bff..07fa9c953 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -7,7 +7,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
-- Nothing yet!
+### Fixed
+
+- Ensure `@import "…" reference` never generates utilities ([#15307](https://github.com/tailwindlabs/tailwindcss/pull/15307))
 
 ## [4.0.0-beta.5] - 2024-12-04
 
diff --git a/integrations/vite/svelte.test.ts b/integrations/vite/svelte.test.ts
index 0f7953c63..3cbfc66fa 100644
--- a/integrations/vite/svelte.test.ts
+++ b/integrations/vite/svelte.test.ts
@@ -48,7 +48,7 @@ test(
           target: document.body,
         })
       `,
-      'src/index.css': css`@import 'tailwindcss' reference;`,
+      'src/index.css': css`@import 'tailwindcss';`,
       'src/App.svelte': html`
         <script>
           import './index.css'
@@ -58,7 +58,7 @@ test(
         <h1 class="global local underline">Hello {name}!</h1>
 
         <style>
-          @import 'tailwindcss/theme' theme(reference);
+          @import 'tailwindcss' reference;
           @import './other.css';
         </style>
       `,
@@ -165,14 +165,11 @@ test(
         <h1 class="local global underline">Hello {name}!</h1>
 
         <style>
-          @import 'tailwindcss/theme' theme(reference);
+          @import 'tailwindcss' reference;
           @import './other.css';
         </style>
       `,
-      'src/index.css': css`
-        @import 'tailwindcss/theme' theme(reference);
-        @import 'tailwindcss/utilities';
-      `,
+      'src/index.css': css` @import 'tailwindcss'; `,
       'src/other.css': css`
         .local {
           @apply text-red-500;
diff --git a/integrations/vite/vue.test.ts b/integrations/vite/vue.test.ts
index dec61d808..626733705 100644
--- a/integrations/vite/vue.test.ts
+++ b/integrations/vite/vue.test.ts
@@ -45,7 +45,7 @@ test(
       `,
       'src/App.vue': html`
         <style>
-          @import 'tailwindcss' reference;
+          @import 'tailwindcss';
           .foo {
             @apply text-red-500;
           }
diff --git a/packages/tailwindcss/src/index.test.ts b/packages/tailwindcss/src/index.test.ts
index 1c4afe2ef..de59e08be 100644
--- a/packages/tailwindcss/src/index.test.ts
+++ b/packages/tailwindcss/src/index.test.ts
@@ -3138,6 +3138,36 @@ describe('`@import "…" reference`', () => {
     `)
   })
 
+  test('does not generate utilities', async () => {
+    let loadStylesheet = async (id: string, base: string) => {
+      if (id === './foo/baz.css') {
+        return {
+          content: css`
+            @layer utilities {
+              @tailwind utilities;
+            }
+          `,
+          base: '/root/foo',
+        }
+      }
+      return {
+        content: css`
+          @import './foo/baz.css';
+        `,
+        base: '/root/foo',
+      }
+    }
+
+    let { build } = await compile(
+      css`
+        @import './foo/bar.css' reference;
+      `,
+      { loadStylesheet },
+    )
+
+    expect(build(['text-underline', 'border']).trim()).toMatchInlineSnapshot(`"@layer utilities;"`)
+  })
+
   test('removes styles when the import resolver was handled outside of Tailwind CSS', async () => {
     await expect(
       compileCss(
diff --git a/packages/tailwindcss/src/index.ts b/packages/tailwindcss/src/index.ts
index 9904608ed..cbfad6b3f 100644
--- a/packages/tailwindcss/src/index.ts
+++ b/packages/tailwindcss/src/index.ts
@@ -388,11 +388,21 @@ async function parseCss(
                 return WalkAction.Skip
               }
 
-              // Other at-rules, like `@media`, `@supports`, or `@layer` should
-              // be recursively traversed as these might be inserted by the
-              // `@import` resolution.
+              case '@media':
+              case '@supports':
+              case '@layer': {
+                // These rules should be recursively traversed as these might be
+                // inserted by the `@import` resolution.
+                return
+              }
+
+              default: {
+                replaceWith([])
+                return WalkAction.Skip
+              }
             }
           })
+
           node.nodes = [contextNode({ reference: true }, node.nodes)]
         }