createConverter() — tailwindcss Function Reference

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

Function typescript CommandLineInterface Codemods calls 7 called by 1

Entity Profile

CommandLineInterface→ Codemods→ createConverter() — tailwindcss Function Reference

Dependency Diagram

graph TD
  f1c7fb37_4a69_f6f5_b7f4_9f3d8b534c40["createConverter()"]
  c36efdeb_7fd2_0935_2c28_bf15095a9dd9["migrate-theme-to-var.ts"]
  f1c7fb37_4a69_f6f5_b7f4_9f3d8b534c40 -->|defined in| c36efdeb_7fd2_0935_2c28_bf15095a9dd9
  a9a5216f_0dd1_0c09_6894_e34986eaf2a5["migrateThemeToVar()"]
  a9a5216f_0dd1_0c09_6894_e34986eaf2a5 -->|calls| f1c7fb37_4a69_f6f5_b7f4_9f3d8b534c40
  49a8c506_c50e_ed4b_5a0e_0393edae2b6f["parse()"]
  f1c7fb37_4a69_f6f5_b7f4_9f3d8b534c40 -->|calls| 49a8c506_c50e_ed4b_5a0e_0393edae2b6f
  91c97086_ce94_1ef6_775d_f4471bc2ca0e["substituteFunctionsInValue()"]
  f1c7fb37_4a69_f6f5_b7f4_9f3d8b534c40 -->|calls| 91c97086_ce94_1ef6_775d_f4471bc2ca0e
  c58cbb33_f3cc_0b4f_844a_15bf66a1dc61["segment()"]
  f1c7fb37_4a69_f6f5_b7f4_9f3d8b534c40 -->|calls| c58cbb33_f3cc_0b4f_844a_15bf66a1dc61
  1767219e_c38a_227c_492b_5d47634d54a4["keyPathToCssProperty()"]
  f1c7fb37_4a69_f6f5_b7f4_9f3d8b534c40 -->|calls| 1767219e_c38a_227c_492b_5d47634d54a4
  05d44181_6631_c1fa_4a63_96653e28f99c["toKeyPath()"]
  f1c7fb37_4a69_f6f5_b7f4_9f3d8b534c40 -->|calls| 05d44181_6631_c1fa_4a63_96653e28f99c
  09df19e7_0346_145d_40c4_e93ff14a2ff9["isValidSpacingMultiplier()"]
  f1c7fb37_4a69_f6f5_b7f4_9f3d8b534c40 -->|calls| 09df19e7_0346_145d_40c4_e93ff14a2ff9
  4982d9ce_98d4_85d9_44af_7cc47b93c482["walk()"]
  f1c7fb37_4a69_f6f5_b7f4_9f3d8b534c40 -->|calls| 4982d9ce_98d4_85d9_44af_7cc47b93c482
  style f1c7fb37_4a69_f6f5_b7f4_9f3d8b534c40 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) {