isSafeMigration() — tailwindcss Function Reference

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

Function typescript CommandLineInterface Codemods calls 4 called by 1

Entity Profile

CommandLineInterface→ Codemods→ isSafeMigration() — tailwindcss Function Reference

Dependency Diagram

graph TD
  b779d35b_89d6_7939_9231_39f9aa250ab3["isSafeMigration()"]
  d5e14c3d_f7c4_162e_96e8_83915119d547["is-safe-migration.ts"]
  b779d35b_89d6_7939_9231_39f9aa250ab3 -->|defined in| d5e14c3d_f7c4_162e_96e8_83915119d547
  66c57db2_afd7_9e7b_cea6_76cdb074b086["migrateCandidate()"]
  66c57db2_afd7_9e7b_cea6_76cdb074b086 -->|calls| b779d35b_89d6_7939_9231_39f9aa250ab3
  2820372c_b982_9e06_fc23_f8f4ac308d00["get()"]
  b779d35b_89d6_7939_9231_39f9aa250ab3 -->|calls| 2820372c_b982_9e06_fc23_f8f4ac308d00
  7d328a86_10c6_b5c1_6390_36f4fffe9c14["parseCandidate()"]
  b779d35b_89d6_7939_9231_39f9aa250ab3 -->|calls| 7d328a86_10c6_b5c1_6390_36f4fffe9c14
  1c72a2ee_1eed_b243_e3d5_5f78aeeb465b["isGreaterThan()"]
  b779d35b_89d6_7939_9231_39f9aa250ab3 -->|calls| 1c72a2ee_1eed_b243_e3d5_5f78aeeb465b
  d1610c40_828a_2a82_2129_746c9cd742ea["isMiddleOfString()"]
  b779d35b_89d6_7939_9231_39f9aa250ab3 -->|calls| d1610c40_828a_2a82_2129_746c9cd742ea
  style b779d35b_89d6_7939_9231_39f9aa250ab3 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