isSafeMigration() — tailwindcss Function Reference

Architecture documentation for the isSafeMigration() function in is-safe-migration.ts from the tailwindcss codebase.

Function typescript UpgradeToolkit Codemods calls 4 called by 1

Entity Profile

UpgradeToolkit→ Codemods→ isSafeMigration() — tailwindcss Function Reference

Dependency Diagram

graph TD
  aa2e93eb_f211_d616_3736_f2a6e60dfa72["isSafeMigration()"]
  0e3e8c5a_e3ef_6c0d_8a31_e358e2206f79["is-safe-migration.ts"]
  aa2e93eb_f211_d616_3736_f2a6e60dfa72 -->|defined in| 0e3e8c5a_e3ef_6c0d_8a31_e358e2206f79
  8408bbf2_f1a4_0668_26f9_b4cdef678388["migrateCandidate()"]
  8408bbf2_f1a4_0668_26f9_b4cdef678388 -->|calls| aa2e93eb_f211_d616_3736_f2a6e60dfa72
  5bcf4886_1230_a8ff_7302_a26cc5a9a525["get()"]
  aa2e93eb_f211_d616_3736_f2a6e60dfa72 -->|calls| 5bcf4886_1230_a8ff_7302_a26cc5a9a525
  d4b90da0_01b5_b21d_ff05_b37798744576["parseCandidate()"]
  aa2e93eb_f211_d616_3736_f2a6e60dfa72 -->|calls| d4b90da0_01b5_b21d_ff05_b37798744576
  51e4d688_49f2_6ee8_9c8c_27dabebb233e["isGreaterThan()"]
  aa2e93eb_f211_d616_3736_f2a6e60dfa72 -->|calls| 51e4d688_49f2_6ee8_9c8c_27dabebb233e
  3e2b05f6_b887_fa06_29bc_00b8e9a37e3e["isMiddleOfString()"]
  aa2e93eb_f211_d616_3736_f2a6e60dfa72 -->|calls| 3e2b05f6_b887_fa06_29bc_00b8e9a37e3e
  style aa2e93eb_f211_d616_3736_f2a6e60dfa72 fill:#6366f1,stroke:#818cf8,color:#fff

Relationship Graph

Source Code

packages/@tailwindcss-upgrade/src/codemods/template/is-safe-migration.ts lines 26–188

export function isSafeMigration(
  rawCandidate: string,
  location: { contents: string; start: number; end: number },
  designSystem: DesignSystem,
): boolean {
  // Ensure we are not migrating a candidate in a `<style>` block. The heuristic
  // would be if the candidate is preceded by a whitespace and followed by a
  // colon and whitespace.
  //
  // E.g.:
  // ```vue
  // <template>
  //   <div class="foo"></div>
  // </template>
  //
  //
  // <style>
  // .foo {
  //   flex-shrink: 0;
  //  ^           ^^
  // }
  // </style>
  // ```
  if (
    // Whitespace before the candidate
    location.contents[location.start - 1]?.match(/\s/) &&
    // A colon followed by whitespace after the candidate
    location.contents.slice(location.end, location.end + 2)?.match(/^:\s/)
  ) {
    // Compute all `<style>` ranges once and cache it for the current files
    let ranges = styleBlockRanges.get(location.contents)

    for (let i = 0; i < ranges.length; i += 2) {
      let start = ranges[i]
      let end = ranges[i + 1]

      // Check if the candidate is inside a `<style>` block
      if (location.start >= start && location.end <= end) {
        return false
      }
    }
  }

  let [candidate] = 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 false
  }

  // Parsed a candidate successfully, 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