Do not scan tailwind-merge sources for candidates (#16005)

Resolves #15722 This PR adds a list of ignored dependencies (in the current form only `tailwind-merge`) to the Vite extension which, when included in the dependency tree, are no longer scanned by the Tailwind CSS compiler for candidates. This is to work around an issue where some dependencies contain vast lists of valid Tailwind CSS class names which would otherwise always be inlined in the build. ## Test plan This was tested in our Vite playground on both dev and prod builds across macOS and Windows: ### Windows prod build before ![telegram-cloud-photo-size-4-5823632138052944949-y](https://github.com/user-attachments/assets/a2bca1c7-cef3-4f04-a588-cbf1afdbdd37) ### Windows prod build after This includes a debug `console.log(…)` to make sure it matches the right module. ![telegram-cloud-photo-size-4-5823632138052944951-y](https://github.com/user-attachments/assets/109b82c5-1946-4d44-b812-d68474686eb7) ### Windows dev build after This includes a debug `console.log(…)` to make sure it matches the right module. ![telegram-cloud-photo-size-4-5823632138052944948-y](https://github.com/user-attachments/assets/41cbe7f1-f997-4c6c-b5fe-01d574f7a999)
2025-12-08 21:36:08 +00:00 · 2025-01-29 17:32:06 +01:00 · 2025-01-29 17:32:06 +01:00 · a4761ea967
commit a4761ea967
parent 9fef2bde50
3 changed files with 96 additions and 0 deletions
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@ -26,6 +26,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Find utilities when using the Angular class shorthand syntax ([#15974](https://github.com/tailwindlabs/tailwindcss/pull/15974))
 - Find utilities when using functions inside arrays ([#15974](https://github.com/tailwindlabs/tailwindcss/pull/15974))
 - Ensure that `@tailwindcss/browser` does not pollute the global namespace ([#15978](https://github.com/tailwindlabs/tailwindcss/pull/15978))
+- Ensure that `tailwind-merge` is not scanned when using the Vite plugin ([#16005](https://github.com/tailwindlabs/tailwindcss/pull/16005))
 - Ensure CSS theme variables are available within shadow roots ([#15975](https://github.com/tailwindlabs/tailwindcss/pull/15975))
 - Fix crash when project lives in the `/` directory ([#15988](https://github.com/tailwindlabs/tailwindcss/pull/15988))
 - Ensure `@custom-variant` has a non-empty selector list  ([#16009](https://github.com/tailwindlabs/tailwindcss/pull/16009))
--- a/integrations/vite/ignored-packages.test.ts
+++ b/integrations/vite/ignored-packages.test.ts
@ -0,0 +1,81 @@
+import { candidate, css, fetchStyles, html, js, retryAssertion, test, ts, txt } from '../utils'
+
+const WORKSPACE = {
+  fs: {
+    'package.json': txt`
+    {
+      "type": "module",
+      "dependencies": {
+        "tailwind-merge": "^2",
+        "@tailwindcss/vite": "workspace:^",
+        "tailwindcss": "workspace:^"
+      },
+      "devDependencies": {
+        "vite": "^6"
+      }
+    }
+  `,
+    'vite.config.ts': ts`
+      import tailwindcss from '@tailwindcss/vite'
+      import { defineConfig } from 'vite'
+
+      export default defineConfig({
+        build: { cssMinify: false },
+        plugins: [tailwindcss()],
+      })
+    `,
+    'index.html': html`
+      <head>
+        <link rel="stylesheet" href="./src/index.css" />
+        <script type="module" src="./src/index.js"></script>
+      </head>
+    `,
+    'src/index.js': js`
+      import { twMerge } from 'tailwind-merge'
+
+      twMerge('underline')
+
+      console.log('underline')
+    `,
+    'src/index.css': css`@import 'tailwindcss/utilities' layer(utilities);`,
+  },
+}
+
+test(
+  'does not scan tailwind-merge in production builds',
+  WORKSPACE,
+  async ({ fs, exec, expect }) => {
+    await exec('pnpm vite build')
+
+    let files = await fs.glob('dist/**/*.css')
+    expect(files).toHaveLength(1)
+    let [, content] = files[0]
+
+    expect(content).toMatchInlineSnapshot(`
+      "@layer utilities {
+        .underline {
+          text-decoration-line: underline;
+        }
+      }
+      "
+    `)
+  },
+)
+
+test('does not scan tailwind-merge in dev builds', WORKSPACE, async ({ spawn, expect }) => {
+  let process = await spawn('pnpm vite dev')
+  await process.onStdout((m) => m.includes('ready in'))
+
+  let url = ''
+  await process.onStdout((m) => {
+    let match = /Local:\s*(http.*)\//.exec(m)
+    if (match) url = match[1]
+    return Boolean(url)
+  })
+
+  await retryAssertion(async () => {
+    let styles = await fetchStyles(url, '/index.html')
+
+    expect(styles).not.toContain(candidate`flex`)
+  })
+})
--- a/packages/@tailwindcss-vite/src/index.ts
+++ b/packages/@tailwindcss-vite/src/index.ts
@ -9,6 +9,8 @@ import type { Plugin, ResolvedConfig, Rollup, Update, ViteDevServer } from 'vite
 const DEBUG = env.DEBUG
 const SPECIAL_QUERY_RE = /[?&](raw|url)\b/

+const IGNORED_DEPENDENCIES = ['tailwind-merge']
+
 export default function tailwindcss(): Plugin[] {
  let servers: ViteDevServer[] = []
  let config: ResolvedConfig | null = null
@ -62,6 +64,18 @@ export default function tailwindcss(): Plugin[] {
  })

  function scanFile(id: string, content: string, extension: string, isSSR: boolean) {
+    for (let dependency of IGNORED_DEPENDENCIES) {
+      // We validated that Vite IDs always use posix style path separators, even on Windows.
+      // In dev build, Vite precompiles dependencies
+      if (id.includes(`.vite/deps/${dependency}.js`)) {
+        return
+      }
+      // In prod builds, use the node_modules path
+      if (id.includes(`/node_modules/${dependency}/`)) {
+        return
+      }
+    }
+
    let updated = false
    for (let candidate of moduleGraphScanner.scanFiles([{ content, extension }])) {
      updated = true