Add CSS codemods for migrating @apply

packages/tailwindcss/package.json

@@ -89,6 +89,7 @@
   "devDependencies": {
     "@tailwindcss/oxide": "workspace:^",
     "@types/node": "catalog:",
+    "dedent": "1.5.3",
     "lightningcss": "catalog:"
   }
 }

packages/tailwindcss/src/compat/codemods/migrate-at-apply.test.ts

@@ -0,0 +1,70 @@
+import dedent from 'dedent'
+import { expect, it } from 'vitest'
+import { toCss } from '../../ast'
+import * as CSS from '../../css-parser'
+import { migrateAtApply } from './migrate-at-apply'
+
+const css = dedent
+
+function migrate(input: string) {
+  let ast = CSS.parse(input)
+  migrateAtApply(ast)
+  return toCss(ast).trim()
+}
+
+it('should not migrate `@apply`, when there are no issues', () => {
+  expect(
+    migrate(css`
+      .foo {
+        @apply flex flex-col items-center;
+      }
+    `),
+  ).toMatchInlineSnapshot(`
+    ".foo {
+      @apply flex flex-col items-center;
+    }"
+  `)
+})
+
+it('should append `!` to each utility, when using `!important`', () => {
+  expect(
+    migrate(css`
+      .foo {
+        @apply flex flex-col !important;
+      }
+    `),
+  ).toMatchInlineSnapshot(`
+    ".foo {
+      @apply flex! flex-col!;
+    }"
+  `)
+})
+
+// Sass/SCSS
+it('should append `!` to each utility, when using `#{!important}`', () => {
+  expect(
+    migrate(css`
+      .foo {
+        @apply flex flex-col #{!important};
+      }
+    `),
+  ).toMatchInlineSnapshot(`
+    ".foo {
+      @apply flex! flex-col!;
+    }"
+  `)
+})
+
+it('should move the legacy `!` prefix, to the new `!` postfix notation', () => {
+  expect(
+    migrate(css`
+      .foo {
+        @apply !flex flex-col! hover:!items-start items-center;
+      }
+    `),
+  ).toMatchInlineSnapshot(`
+    ".foo {
+      @apply flex! flex-col! hover:items-start! items-center;
+    }"
+  `)
+})

packages/tailwindcss/src/compat/codemods/migrate-at-apply.ts

@@ -0,0 +1,37 @@
+import { walk, type AstNode } from '../../ast'
+import { segment } from '../../utils/segment'
+
+export function migrateAtApply(ast: AstNode[]) {
+  walk(ast, (node) => {
+    if (node.kind !== 'rule' || node.selector[0] !== '@' || !node.selector.startsWith('@apply')) {
+      return
+    }
+
+    let utilities = segment(node.selector.slice(7), ' ')
+    let important =
+      utilities[utilities.length - 1] === '!important' ||
+      utilities[utilities.length - 1] === '#{!important}' // Sass/SCSS
+
+    if (important) utilities.pop() // Ignore `!important`
+
+    let params = utilities.map((part) => {
+      let variants = segment(part, ':')
+      let utility = variants.pop()!
+
+      // Apply the important modifier to all the rules if necessary
+      if (important && utility[0] !== '!' && utility[utility.length - 1] !== '!') {
+        utility += '!'
+      }
+
+      // Migrate the important modifier to the end of the utility
+      if (utility[0] === '!') {
+        utility = `${utility.slice(1)}!`
+      }
+
+      // Reconstruct the utility with the variants
+      return [...variants, utility].join(':')
+    })
+
+    node.selector = `@apply ${params.join(' ')}`
+  })
+}

packages/tailwindcss/src/css-parser.ts

@@ -19,6 +19,7 @@ const CLOSE_BRACKET = 0x5d
 const DASH = 0x2d
 const AT_SIGN = 0x40
 const EXCLAMATION_MARK = 0x21
+const HASH = 0x23
 
 export function parse(input: string) {
   input = input.replaceAll('\r\n', '\n')
@@ -54,6 +55,37 @@ export function parse(input: string) {
       i += 1
     }
 
+    // Parse scss-like hash interpolation.
+    //
+    // E.g.:
+    // ```css
+    // .btn {
+    //   @apply font-bold py-2 px-4 rounded #{!important};
+    //                                      ^^^^^^^^^^^^^
+    // }
+    // ```
+    // TODO: Do we want to support this? It currently helps with codemods.
+    else if (currentChar === HASH && input.charCodeAt(i + 1) === OPEN_CURLY) {
+      let start = i
+
+      for (let j = i + 2; j < input.length; j++) {
+        peekChar = input.charCodeAt(j)
+
+        // Current character is a `\` therefore the next character is escaped.
+        if (peekChar === BACKSLASH) {
+          j += 1
+        }
+
+        // End of the block.
+        else if (peekChar === CLOSE_CURLY) {
+          i = j
+          break
+        }
+      }
+
+      buffer += input.slice(start, i + 1)
+    }
+
     // Start of a comment.
     //
     // E.g.: