migrateTailwindDirectives() — tailwindcss Function Reference

Source Code

packages/@tailwindcss-upgrade/src/codemods/css/migrate-tailwind-directives.ts lines 5–128

export function migrateTailwindDirectives(options: { newPrefix: string | null }): Plugin {
  let prefixParams = options.newPrefix ? ` prefix(${options.newPrefix})` : ''

  function migrate(root: Root) {
    let baseNode = null as AtRule | null
    let utilitiesNode = null as AtRule | null
    let orderedNodes: AtRule[] = []

    let defaultImportNode = null as AtRule | null
    let utilitiesImportNode = null as AtRule | null
    let preflightImportNode = null as AtRule | null
    let themeImportNode = null as AtRule | null

    let layerOrder: string[] = []

    root.walkAtRules((node) => {
      // Migrate legacy `@import "tailwindcss/tailwind.css"`
      if (node.name === 'import' && node.params.match(/^["']tailwindcss\/tailwind\.css["']$/)) {
        node.params = node.params.replace('tailwindcss/tailwind.css', 'tailwindcss')
      }

      // Append any new prefix() param to existing `@import 'tailwindcss'` directives
      if (node.name === 'import' && node.params.match(/^["']tailwindcss["']/)) {
        node.params += prefixParams
      }

      // Track old imports and directives
      else if (
        (node.name === 'tailwind' && node.params === 'base') ||
        (node.name === 'import' && node.params.match(/^["']tailwindcss\/base["']$/))
      ) {
        layerOrder.push('base')
        orderedNodes.push(node)
        baseNode = node
      } else if (
        (node.name === 'tailwind' && node.params === 'utilities') ||
        (node.name === 'import' && node.params.match(/^["']tailwindcss\/utilities["']$/))
      ) {
        layerOrder.push('utilities')
        orderedNodes.push(node)
        utilitiesNode = node
      }

      // Remove directives that are not needed anymore
      else if (
        (node.name === 'tailwind' && node.params === 'components') ||
        (node.name === 'tailwind' && node.params === 'screens') ||
        (node.name === 'tailwind' && node.params === 'variants') ||
        (node.name === 'import' && node.params.match(/^["']tailwindcss\/components["']$/))
      ) {
        node.remove()
      }

      // Replace Tailwind CSS v2 directives that still worked in v3.
      else if (node.name === 'responsive') {
        if (node.nodes) {
          for (let child of node.nodes) {
            child.raws.tailwind_pretty = true
          }
          node.replaceWith(node.nodes)
        } else {
          node.remove()
        }
      }
    })

    // Insert default import if all directives are present
    if (baseNode !== null && utilitiesNode !== null) {
      if (!defaultImportNode) {
        findTargetNode(orderedNodes).before(
          new AtRule({ name: 'import', params: `'tailwindcss'${prefixParams}` }),
        )
      }
      baseNode?.remove()
      utilitiesNode?.remove()
    }

    // Insert individual imports if not all directives are present
    else if (utilitiesNode !== null) {
      if (!utilitiesImportNode) {
        findTargetNode(orderedNodes).before(
          new AtRule({ name: 'import', params: "'tailwindcss/utilities' layer(utilities)" }),
        )
      }
      utilitiesNode?.remove()
    } else if (baseNode !== null) {
      if (!themeImportNode) {
        findTargetNode(orderedNodes).before(
          new AtRule({ name: 'import', params: `'tailwindcss/theme' layer(theme)${prefixParams}` }),
        )
      }

      if (!preflightImportNode) {
        findTargetNode(orderedNodes).before(
          new AtRule({ name: 'import', params: "'tailwindcss/preflight' layer(base)" }),
        )
      }

      baseNode?.remove()
    }

    // Insert `@layer …;` at the top when the order in the CSS was different
    // from the default.
    {
      // Determine if the order is different from the default.
      let sortedLayerOrder = layerOrder.toSorted((a, z) => {
        return DEFAULT_LAYER_ORDER.indexOf(a) - DEFAULT_LAYER_ORDER.indexOf(z)
      })

      if (layerOrder.some((layer, index) => layer !== sortedLayerOrder[index])) {
        // Create a new `@layer` rule with the sorted order.
        let newLayerOrder = DEFAULT_LAYER_ORDER.toSorted((a, z) => {
          return layerOrder.indexOf(a) - layerOrder.indexOf(z)
        })
        root.prepend({ name: 'layer', params: newLayerOrder.join(', ') })
      }
    }
  }

  return {
    postcssPlugin: '@tailwindcss/upgrade/migrate-tailwind-directives',
    OnceExit: migrate,
  }
}