Ignore custom variants with :merge(…) selectors

Author: philipp-spiess

CHANGELOG.md

@@ -17,6 +17,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Ensure that running the Standalone build does not leave temporary files behind ([#17981](https://github.com/tailwindlabs/tailwindcss/pull/17981))
 - Fix `-rotate-*` utilities with arbitrary values ([#18014](https://github.com/tailwindlabs/tailwindcss/pull/18014))
 - Upgrade: Change casing of utilities with named values to kebab-case to match updated theme variables ([#18017](https://github.com/tailwindlabs/tailwindcss/pull/18017))
+- Ignore custom variants using `:merge(…)` selectors in legacy JS plugins as they would create invalid CSS in v4 ([#18020](https://github.com/tailwindlabs/tailwindcss/pull/18020))
 
 ### Added
 

packages/tailwindcss/src/compat/plugin-api.test.ts

@@ -1830,6 +1830,44 @@ describe('addVariant', () => {
       }"
     `)
   })
+
+  test('ignores variants that use :merge(…) and ensures `peer-*` and `group-*` rules work out of the box', async () => {
+    let { build } = await compile(
+      css`
+        @plugin "my-plugin";
+        @layer utilities {
+          @tailwind utilities;
+        }
+      `,
+      {
+        loadModule: async (id, base) => {
+          return {
+            path: '',
+            base,
+            module: ({ addVariant }: PluginAPI) => {
+              addVariant('optional', '&:optional')
+              addVariant('group-optional', ':merge(.group):optional &')
+              addVariant('peer-optional', ':merge(.peer):optional ~ &')
+            },
+          }
+        },
+      },
+    )
+    let compiled = build([
+      'optional:flex',
+      'group-optional:flex',
+      'peer-optional:flex',
+      'group-optional/foo:flex',
+    ])
+
+    expect(optimizeCss(compiled).trim()).toMatchInlineSnapshot(`
+      "@layer utilities {
+        .group-optional\\:flex:is(:where(.group):optional *), .group-optional\\/foo\\:flex:is(:where(.group\\/foo):optional *), .peer-optional\\:flex:is(:where(.peer):optional ~ *), .optional\\:flex:optional {
+          display: flex;
+        }
+      }"
+    `)
+  })
 })
 
 describe('matchVariant', () => {

packages/tailwindcss/src/compat/plugin-api.ts

@@ -115,6 +115,16 @@ export function buildPluginApi({
         )
       }
 
+      // Ignore variants emitting v3 `:merge(…)` rules. In v4, the `group-*` and `peer-*` variants
+      // compound automatically.
+      if (typeof variant === 'string') {
+        if (variant.includes(':merge(')) return
+      } else if (Array.isArray(variant)) {
+        if (variant.some((v) => v.includes(':merge('))) return
+      } else if (typeof variant === 'object') {
+        if (Object.keys(variant).some((v) => v.includes(':merge('))) return
+      }
+
       // Single selector or multiple parallel selectors
       if (typeof variant === 'string' || Array.isArray(variant)) {
         designSystem.variants.static(