Make candidate template migrations faster (#18025)

This PR makes the migrations for templates much faster. To make this
work, I also had to move things around a bit (so you might want to check
this PR commit by commit). I also solved an issue by restructuring the
code.

### Performance

For starters, we barely applied any caching when migrating candidates
from α to β. The problem with this is that in big projects the same
candidates will appear _everywhere_, so caching is going to be useful
here.

One of the reasons why we didn't do any caching is that some migrations
were checking if a migration is actually safe to do. To do this, we were
checking the `location` (the location of the candidate in the template).
Since this location is unique for each template, caching was not
possible.

So the first order of business was to hoist the `isSafeMigration` check
up as the very first thing we do in the migration.

If we do this first, then the only remaining code relies on the
`DesignSystem`, `UserConfig` and `rawCandidate`.

In a project, the `DesignSystem` and `UserConfig` will be the same
during the migration, only the `rawCandidate` will be different which
means that we can move all this logic in a good old `DefaultMap` and
cache the heck out of it.

Running the numbers on our Tailwind Plus repo, this results in:
```
    Total seen candidates: 2 211 844
Total migrated candidates: 7 775 
               Cache hits: 1 575 700
```

That's a lot of work we _don't_ have to do. Looking at the timings, the
template migration step goes from ~45s to ~10s because of this.

Another big benefit of this is that this makes migrations _actually_
safe. Before we were checking if a migration was safe to do in specific
migrations. But other migrations were still printing the candidate which
could still result in an unsafe migration.

For example when migrating the `blur` and the `shadow` classes, the
`isSafeMigration` was used. But if the input was `!flex` then the safety
check wasn't even checked in this specific migration.

### Safe migrations

Also made some changes to the `isSafeMigration` logic itself. We used to
start by checking the location, but thinking about the problem again,
the actual big problem we were running into is classes that are short
like `blur`, and `shadow` because they could be used in other contexts
than a Tailwind CSS class.

Inverting this logic means that more specific Tailwind CSS classes will
very likely _not_ cause any issues at all.

For example:
- If you have variants: `hover:focus:flex`
- If you have arbitrary properties: `[color:red]`
- If you have arbitrary values: `bg-[red]`
- If you have a modifier: `bg-red-500/50`
- If you have a `-` in the name: `bg-red-500`

Even better if we can't parse a candidate at all, we can skip the
migrations all together.

This brings us to the issue in #17974, one of the issues was already
solved by just hoisting the `isSafeMigration`. But to make the issue was
completely solved I also made sure that in Vue attributes like
`:active="…"` are also considered unsafe (note: `:class` is allowed).

Last but not least, in case of the `!duration` that got replaced with
`duration!` was solved by verifying that the candidate actually produces
valid CSS. We can compute the signature for this class.

The reason this wasn't thrown away earlier is because we can correctly
parse `duration` but `duration` on its own doesn't exist,
`duration-<number>` does exist as a functional utility which is why it
parsed in the first place.

Fixes: #17974

## Test plan

1. Ran the tool on our Tailwind UI Templates repo to compare the new
output with the "old" behavior and there were no differences in output.
2. Ran the tool on our Tailwind Plus repo, and the template migration
step went from ~45s to ~10s.
3. Added additional tests to verify the issues in #17974 are fixed.


[ci-all] let's run this on all CI platforms...

Author: RobinMalfait

CHANGELOG.md

@@ -17,11 +17,13 @@ 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))
+- Upgrade: Fix unsafe migrations in Vue files ([#18025](https://github.com/tailwindlabs/tailwindcss/pull/18025))
 - Ignore custom variants using `:merge(…)` selectors in legacy JS plugins ([#18020](https://github.com/tailwindlabs/tailwindcss/pull/18020))
 
 ### Added
 
 - Upgrade: Migrate bare values to named values ([#18000](https://github.com/tailwindlabs/tailwindcss/pull/18000))
+- Upgrade: Make candidate template migrations faster using caching ([#18025](https://github.com/tailwindlabs/tailwindcss/pull/18025))
 
 ## [4.1.6] - 2025-05-09
 

integrations/upgrade/js-config.test.ts

@@ -151,7 +151,7 @@ test(
         <div
           class="[letter-spacing:theme(letterSpacing.superWide)] [line-height:theme(lineHeight.superLoose)]"
         ></div>
-        <div class="text-red-superRed/superOpaque leading-superLoose"></div>
+        <div class="text-superRed/superOpaque leading-superLoose"></div>
       `,
       'node_modules/my-external-lib/src/template.html': html`
         <div class="text-red-500">
@@ -169,7 +169,7 @@ test(
       <div
         class="[letter-spacing:var(--tracking-super-wide)] [line-height:var(--leading-super-loose)]"
       ></div>
-      <div class="text-red-super-red/super-opaque leading-super-loose"></div>
+      <div class="text-super-red/super-opaque leading-super-loose"></div>
 
       --- src/input.css ---
       @import 'tailwindcss';

packages/@tailwindcss-upgrade/src/codemods/template/is-safe-migration.test.ts

@@ -0,0 +1,61 @@
+import { __unstable__loadDesignSystem } from '@tailwindcss/node'
+import { expect, test, vi } from 'vitest'
+import * as versions from '../../utils/version'
+import { migrateCandidate } from './migrate'
+vi.spyOn(versions, 'isMajor').mockReturnValue(true)
+
+test('does not replace classes in invalid positions', async () => {
+  let designSystem = await __unstable__loadDesignSystem('@import "tailwindcss";', {
+    base: __dirname,
+  })
+
+  async function shouldNotReplace(example: string, candidate = '!border') {
+    expect(
+      await migrateCandidate(designSystem, {}, candidate, {
+        contents: example,
+        start: example.indexOf(candidate),
+        end: example.indexOf(candidate) + candidate.length,
+      }),
+    ).toEqual(candidate)
+  }
+
+  await shouldNotReplace(`let notBorder = !border    \n`)
+  await shouldNotReplace(`{ "foo": !border.something + ""}\n`)
+  await shouldNotReplace(`<div v-if="something && !border"></div>\n`)
+  await shouldNotReplace(`<div v-else-if="something && !border"></div>\n`)
+  await shouldNotReplace(`<div v-show="something && !border"></div>\n`)
+  await shouldNotReplace(`<div v-if="!border || !border"></div>\n`)
+  await shouldNotReplace(`<div v-else-if="!border || !border"></div>\n`)
+  await shouldNotReplace(`<div v-show="!border || !border"></div>\n`)
+  await shouldNotReplace(`<div v-if="!border"></div>\n`)
+  await shouldNotReplace(`<div v-else-if="!border"></div>\n`)
+  await shouldNotReplace(`<div v-show="!border"></div>\n`)
+  await shouldNotReplace(`<div x-if="!border"></div>\n`)
+
+  await shouldNotReplace(`let notShadow = shadow    \n`, 'shadow')
+  await shouldNotReplace(`{ "foo": shadow.something + ""}\n`, 'shadow')
+  await shouldNotReplace(`<div v-if="something && shadow"></div>\n`, 'shadow')
+  await shouldNotReplace(`<div v-else-if="something && shadow"></div>\n`, 'shadow')
+  await shouldNotReplace(`<div v-show="something && shadow"></div>\n`, 'shadow')
+  await shouldNotReplace(`<div v-if="shadow || shadow"></div>\n`, 'shadow')
+  await shouldNotReplace(`<div v-else-if="shadow || shadow"></div>\n`, 'shadow')
+  await shouldNotReplace(`<div v-show="shadow || shadow"></div>\n`, 'shadow')
+  await shouldNotReplace(`<div v-if="shadow"></div>\n`, 'shadow')
+  await shouldNotReplace(`<div v-else-if="shadow"></div>\n`, 'shadow')
+  await shouldNotReplace(`<div v-show="shadow"></div>\n`, 'shadow')
+  await shouldNotReplace(`<div x-if="shadow"></div>\n`, 'shadow')
+  await shouldNotReplace(
+    `<div style={{filter: 'drop-shadow(30px 10px 4px #4444dd)'}}/>\n`,
+    'shadow',
+  )
+
+  // Next.js Image placeholder cases
+  await shouldNotReplace(`<Image placeholder="blur" src="/image.jpg" />`, 'blur')
+  await shouldNotReplace(`<Image placeholder={'blur'} src="/image.jpg" />`, 'blur')
+  await shouldNotReplace(`<Image placeholder={blur} src="/image.jpg" />`, 'blur')
+
+  // https://github.com/tailwindlabs/tailwindcss/issues/17974
+  await shouldNotReplace('<div v-if="!duration">', '!duration')
+  await shouldNotReplace('<div :active="!duration">', '!duration')
+  await shouldNotReplace('<div :active="!visible">', '!visible')
+})

packages/@tailwindcss-upgrade/src/codemods/template/is-safe-migration.ts

@@ -1,18 +1,84 @@
+import { parseCandidate } from '../../../../tailwindcss/src/candidate'
+import type { DesignSystem } from '../../../../tailwindcss/src/design-system'
+import * as version from '../../utils/version'
+
 const QUOTES = ['"', "'", '`']
 const LOGICAL_OPERATORS = ['&&', '||', '?', '===', '==', '!=', '!==', '>', '>=', '<', '<=']
 const CONDITIONAL_TEMPLATE_SYNTAX = [
   // Vue
   /v-else-if=['"]$/,
   /v-if=['"]$/,
   /v-show=['"]$/,
+  /(?<!:?class)=['"]$/,
 
   // Alpine
   /x-if=['"]$/,
   /x-show=['"]$/,
 ]
 const NEXT_PLACEHOLDER_PROP = /placeholder=\{?['"]$/
 
-export function isSafeMigration(location: { contents: string; start: number; end: number }) {
+export function isSafeMigration(
+  rawCandidate: string,
+  location: { contents: string; start: number; end: number },
+  designSystem: DesignSystem,
+): boolean {
+  let [candidate] = Array.from(parseCandidate(rawCandidate, designSystem))
+
+  // If we can't parse the candidate, then it's not a candidate at all. However,
+  // we could be dealing with legacy classes like `tw__flex` in Tailwind CSS v3
+  // land, which also wouldn't parse.
+  //
+  // So let's only skip if we couldn't parse and we are not in Tailwind CSS v3.
+  //
+  if (!candidate && version.isGreaterThan(3)) {
+    return true
+  }
+
+  // Parsed a candidate succesfully, verify if it's a valid candidate
+  else if (candidate) {
+    // When we have variants, we can assume that the candidate is safe to migrate
+    // because that requires colons.
+    //
+    // E.g.: `hover:focus:flex`
+    if (candidate.variants.length > 0) {
+      return true
+    }
+
+    // When we have an arbitrary property, the candidate has such a particular
+    // structure it's very likely to be safe.
+    //
+    // E.g.: `[color:red]`
+    if (candidate.kind === 'arbitrary') {
+      return true
+    }
+
+    // A static candidate is very likely safe if it contains a dash.
+    //
+    // E.g.: `items-center`
+    if (candidate.kind === 'static' && candidate.root.includes('-')) {
+      return true
+    }
+
+    // A functional candidate is very likely safe if it contains a value (which
+    // implies a `-`). Or if the root contains a dash.
+    //
+    // E.g.: `bg-red-500`, `bg-position-20`
+    if (
+      (candidate.kind === 'functional' && candidate.value !== null) ||
+      (candidate.kind === 'functional' && candidate.root.includes('-'))
+    ) {
+      return true
+    }
+
+    // If the candidate contains a modifier, it's very likely to be safe because
+    // it implies that it contains a `/`.
+    //
+    // E.g.: `text-sm/7`
+    if (candidate.kind === 'functional' && candidate.modifier) {
+      return true
+    }
+  }
+
   let currentLineBeforeCandidate = ''
   for (let i = location.start - 1; i >= 0; i--) {
     let char = location.contents.at(i)!

packages/@tailwindcss-upgrade/src/codemods/template/migrate-arbitrary-utilities.ts

@@ -51,27 +51,6 @@ export function migrateArbitraryUtilities(
       continue
     }
 
-    // 1. Canonicalize the value. This might be a bit wasteful because it might
-    //    have been done by other migrations before, but essentially we want to
-    //    canonicalize the arbitrary value to its simplest canonical form. We
-    //    won't be constant folding `calc(…)` expressions (yet?), but we can
-    //    remove unnecessary whitespace (which the `printCandidate` already
-    //    handles for us).
-    //
-    // E.g.:
-    //
-    // ```
-    // [display:_flex_] => [display:flex]
-    // [display:_flex]  => [display:flex]
-    // [display:flex_]  => [display:flex]
-    // [display:flex]   => [display:flex]
-    // ```
-    //
-    let canonicalizedCandidate = designSystem.printCandidate(readonlyCandidate)
-    if (canonicalizedCandidate !== rawCandidate) {
-      return migrateArbitraryUtilities(designSystem, _userConfig, canonicalizedCandidate)
-    }
-
     // The below logic makes use of mutation. Since candidates in the
     // DesignSystem are cached, we can't mutate them directly.
     let candidate = structuredClone(readonlyCandidate) as Writable<typeof readonlyCandidate>

packages/@tailwindcss-upgrade/src/codemods/template/migrate-canonicalize-candidate.test.ts

@@ -0,0 +1,27 @@
+import { __unstable__loadDesignSystem } from '@tailwindcss/node'
+import { expect, test, vi } from 'vitest'
+import * as versions from '../../utils/version'
+import { migrateCanonicalizeCandidate } from './migrate-canonicalize-candidate'
+vi.spyOn(versions, 'isMajor').mockReturnValue(true)
+
+test.each([
+  // Normalize whitespace in arbitrary properties
+  ['[display:flex]', '[display:flex]'],
+  ['[display:_flex]', '[display:flex]'],
+  ['[display:flex_]', '[display:flex]'],
+  ['[display:_flex_]', '[display:flex]'],
+
+  // Normalize whitespace in `calc` expressions
+  ['w-[calc(100%-2rem)]', 'w-[calc(100%-2rem)]'],
+  ['w-[calc(100%_-_2rem)]', 'w-[calc(100%-2rem)]'],
+
+  // Normalize the important modifier
+  ['!flex', 'flex!'],
+  ['flex!', 'flex!'],
+])('%s => %s', async (candidate, result) => {
+  let designSystem = await __unstable__loadDesignSystem('@import "tailwindcss";', {
+    base: __dirname,
+  })
+
+  expect(migrateCanonicalizeCandidate(designSystem, {}, candidate)).toEqual(result)
+})

packages/@tailwindcss-upgrade/src/codemods/template/migrate-canonicalize-candidate.ts

@@ -0,0 +1,29 @@
+import type { Config } from '../../../../tailwindcss/src/compat/plugin-api'
+import type { DesignSystem } from '../../../../tailwindcss/src/design-system'
+
+// Canonicalize the value to its minimal form. This will normalize whitespace,
+// and print the important modifier `!` in the correct place.
+//
+// E.g.:
+//
+// ```
+// [display:_flex_] => [display:flex]
+// [display:_flex]  => [display:flex]
+// [display:flex_]  => [display:flex]
+// [display:flex]   => [display:flex]
+// ```
+//
+export function migrateCanonicalizeCandidate(
+  designSystem: DesignSystem,
+  _userConfig: Config | null,
+  rawCandidate: string,
+) {
+  for (let readonlyCandidate of designSystem.parseCandidate(rawCandidate)) {
+    let canonicalizedCandidate = designSystem.printCandidate(readonlyCandidate)
+    if (canonicalizedCandidate !== rawCandidate) {
+      return canonicalizedCandidate
+    }
+  }
+
+  return rawCandidate
+}