createConverter() — tailwindcss Function Reference

Architecture documentation for the createConverter() function in migrate-theme-to-var.ts from the tailwindcss codebase.

Function typescript UpgradeToolkit Codemods calls 7 called by 1

Entity Profile

UpgradeToolkit→ Codemods→ createConverter() — tailwindcss Function Reference

Dependency Diagram

graph TD
  dc9585e4_0c18_e5de_1302_9b707f3ab6ed["createConverter()"]
  de8dd9be_8c47_4694_db3b_393c549a926a["migrate-theme-to-var.ts"]
  dc9585e4_0c18_e5de_1302_9b707f3ab6ed -->|defined in| de8dd9be_8c47_4694_db3b_393c549a926a
  36a33041_3344_f866_1e23_f035f7e8756f["migrateThemeToVar()"]
  36a33041_3344_f866_1e23_f035f7e8756f -->|calls| dc9585e4_0c18_e5de_1302_9b707f3ab6ed
  2d6c8361_96d8_df0d_ca51_c62f179fdc73["parse()"]
  dc9585e4_0c18_e5de_1302_9b707f3ab6ed -->|calls| 2d6c8361_96d8_df0d_ca51_c62f179fdc73
  3c91d7fd_a929_4393_fc7e_e8d30dedc179["substituteFunctionsInValue()"]
  dc9585e4_0c18_e5de_1302_9b707f3ab6ed -->|calls| 3c91d7fd_a929_4393_fc7e_e8d30dedc179
  f712ed47_45d4_4e5a_dd73_fdefa1da71da["segment()"]
  dc9585e4_0c18_e5de_1302_9b707f3ab6ed -->|calls| f712ed47_45d4_4e5a_dd73_fdefa1da71da
  ae20c4fb_29d7_ca79_3c49_ca02c45d5369["keyPathToCssProperty()"]
  dc9585e4_0c18_e5de_1302_9b707f3ab6ed -->|calls| ae20c4fb_29d7_ca79_3c49_ca02c45d5369
  1b250eae_0bea_d404_ca9e_42da26c56b45["toKeyPath()"]
  dc9585e4_0c18_e5de_1302_9b707f3ab6ed -->|calls| 1b250eae_0bea_d404_ca9e_42da26c56b45
  a15b3c4a_76ff_0090_fc86_bac24f0a4135["isValidSpacingMultiplier()"]
  dc9585e4_0c18_e5de_1302_9b707f3ab6ed -->|calls| a15b3c4a_76ff_0090_fc86_bac24f0a4135
  ed78da58_8727_ad98_120c_61f35cea357a["walk()"]
  dc9585e4_0c18_e5de_1302_9b707f3ab6ed -->|calls| ed78da58_8727_ad98_120c_61f35cea357a
  style dc9585e4_0c18_e5de_1302_9b707f3ab6ed fill:#6366f1,stroke:#818cf8,color:#fff

Relationship Graph

Source Code

packages/@tailwindcss-upgrade/src/codemods/template/migrate-theme-to-var.ts lines 16–170

export function createConverter(designSystem: DesignSystem, { prettyPrint = false } = {}) {
  function convert(input: string, options = Convert.All): [string, CandidateModifier | null] {
    let ast = ValueParser.parse(input)

    // In some scenarios (e.g.: variants), we can't migrate to `var(…)` if it
    // ends up in the `@media (…)` part. In this case we only have to migrate to
    // the new `theme(…)` notation.
    if (options & Convert.MigrateThemeOnly) {
      return [substituteFunctionsInValue(ast, toTheme), null]
    }

    let themeUsageCount = 0
    let themeModifierCount = 0

    // Analyze AST
    walk(ast, (node) => {
      if (node.kind !== 'function') return
      if (node.value !== 'theme') return

      // We are only interested in the `theme` function
      themeUsageCount += 1

      // Figure out if a modifier is used
      walk(node.nodes, (child) => {
        // If we see a `,`, it means that we have a fallback value
        if (child.kind === 'separator' && child.value.includes(',')) {
          return WalkAction.Stop
        }

        // If we see a `/`, we have a modifier
        else if (child.kind === 'word' && child.value === '/') {
          themeModifierCount += 1
          return WalkAction.Stop
        }

        return WalkAction.Skip
      })
    })

    // No `theme(…)` calls, nothing to do
    if (themeUsageCount === 0) {
      return [input, null]
    }

    // No `theme(…)` with modifiers, we can migrate to `var(…)`
    if (themeModifierCount === 0) {
      return [substituteFunctionsInValue(ast, toVar), null]
    }

    // Multiple modifiers which means that there are multiple `theme(…/…)`
    // values. In this case, we can't convert the modifier to a candidate
    // modifier.
    //
    // We also can't migrate to `var(…)` because that would lose the modifier.
    //
    // Try to convert each `theme(…)` call to the modern syntax.
    if (themeModifierCount > 1) {
      return [substituteFunctionsInValue(ast, toTheme), null]
    }

    // Only a single `theme(…)` with a modifier left, that modifier will be
    // migrated to a candidate modifier.
    let modifier: CandidateModifier | null = null
    let result = substituteFunctionsInValue(ast, (path, fallback) => {
      let parts = segment(path, '/').map((part) => part.trim())

      // Multiple `/` separators, which makes this an invalid path
      if (parts.length > 2) return null

      // The path contains a `/`, which means that there is a modifier such as
      // `theme(colors.red.500/50%)`.
      //
      // Currently, we are assuming that this is only being used for colors,
      // which means that we can typically convert them to a modifier on the
      // candidate itself.
      //
      // If there is more than one node in the AST though, `theme(…)` must not
      // be the whole value so it's not safe to use a modifier instead.
      //
      // E.g.: `inset 0px 1px theme(colors.red.500/50%)` is a shadow, not a color.
      if (ast.length === 1 && parts.length === 2 && options & Convert.MigrateModifier) {