Introducing a new way to review your PRs.

Read the announcement

tailwindlabs / tailwindcss

A utility-first CSS framework for rapid UI development.

View on GitHub

19 documents · Updated Nov 20, 2026

docs / upgrade-tool-transformations

Upgrade tool transformations

The upgrade tool moves a Tailwind CSS project to the current CSS and utility model. It analyzes the project before editing it, then applies known migrations to configuration, stylesheets, templates, and package setup while preserving code that it cannot classify safely. See Developer tools for its place in the tool set and CLI build workflow for the build path it prepares.

The migration uses the same design-system and utility rules as the compiler. The CSS directives and parsing and theme and design tokens pages describe those surrounding concepts.

Upgrade scope

The command treats an upgrade as a project-wide change. It finds Tailwind entry stylesheets, relates them to configuration and source files, applies version-specific transformations, and reports the files that changed.

The main upgrade areas are:

  • Project analysis: Build a stylesheet relationship map and identify Tailwind roots.
  • Configuration migration: Move supported JavaScript configuration into CSS or retain it through a compatibility link.
  • CSS migration: Update imports, directives, layers, utilities, theme references, and compatibility rules.
  • Template migration: Rewrite utility candidates when the newer version has a known equivalent.
  • Project cleanup: Align Tailwind and PostCSS packages with the migrated setup.

The tool edits files in place. It normally requires a clean Git working tree, uses project ignore rules during discovery, and leaves the result for review before commit.

Project analysis

Project analysis creates the shared context for every later migration. The tool parses selected stylesheets, follows local imports, records layer relationships, and links Tailwind roots to their configuration and source rules.

The analysis follows this order:

  1. Use named CSS paths when the user supplies them. Otherwise search for non-ignored CSS files.
  2. Parse each file and resolve local CSS imports. External files are not migration targets.
  3. Mark stylesheets that reference Tailwind as roots. If roots share a parent, use the common parent as the migration root.
  4. Link each root to an explicit @config file or detect the project configuration. Ambiguous links need @config or --config.
  5. Reject a graph when one stylesheet is used through both utility and non-utility layers. The tool cannot safely give that file both meanings without splitting it.

This diagram shows how project files become migration context before source changes begin.

flowchart TD
    A[Project files] --> B[CSS selection]
    B --> C[Import and layer graph]
    C --> D[Tailwind roots and config links]
    D --> E[Shared design-system context]
    E --> F[Config migration]
    E --> G[CSS migration]
    E --> H[Template migration]
    F --> I[Safe writes and package updates]
    G --> I
    H --> I

References: packages/…/index.ts• L44-217 packages/…/analyze.ts• L11-21 packages/…/analyze.ts• L44-120 packages/…/analyze.ts• L167-301 packages/…/stylesheet.ts• L18-67

Configuration migrations

Configuration migration moves project intent from the older JavaScript model into CSS when the mapping is clear. Supported values become current source rules, theme data, plugins, variants, prefixes, and other CSS-level settings.

Older project concernCurrent project expression
content patterns@source entries when automatic discovery does not cover them
Theme values and keyframes@theme values and generated keyframe rules
Static plugins@plugin entries
Dark mode and theme variants@custom-variant entries
PrefixA current import prefix and matching template candidates
Unsupported corePlugins settingsA user-facing notice rather than a converted setting

The tool removes a JavaScript config only after full conversion. Dynamic code, unsupported options, presets, unknown flags, or unsupported theme values keep the original config and add a compatibility @config link. This fallback keeps the old behavior available instead of guessing at project intent.

Configuration links matter when a project has more than one Tailwind root. The tool does not assign an uncertain config silently; the user must make the relationship explicit.

References: packages/…/migrate-js-config.ts• L34-95 packages/…/migrate-js-config.ts• L97-289 packages/…/migrate-js-config.ts• L392-489 packages/…/link.ts• L9-69 packages/…/migrate-config.ts• L9-91 packages/…/prepare-config.ts• L17-69

PostCSS configuration

PostCSS migration updates simple Tailwind v3 setups to use the current Tailwind PostCSS package. It changes recognizable plugin entries and aligns package dependencies with that result.

Dynamic JavaScript PostCSS configuration is not rewritten because arbitrary plugin code cannot be converted safely. Simple JSON and package-based settings can receive the narrow migration when their entries are recognizable.

References: packages/…/migrate-postcss.ts• L20-132 packages/…/migrate-postcss.ts• L134-212 packages/…/migrate-postcss.ts• L215-290

CSS transformations

CSS transformation converts the older directive and layer model to the current import, utility, theme, and variant model. The tool coordinates these changes so an earlier directive change can provide context for a later transformation.

The CSS pass covers these behavior groups:

  • Entry imports and directives: Replace legacy Tailwind paths and @tailwind directives with current imports.
  • Layer structure: Preserve the meaning of rules by placing them in the layer implied by their old position.
  • Custom utilities: Convert supported utility and component layers to current @utility rules. Keep unsafe selectors as ordinary CSS.
  • Variant rules: Move supported @variants input into the utility flow.
  • Utility application: Apply the same candidate migration rules to utilities inside @apply and templates.
  • Theme references: Convert supported theme(…) references to current theme or variable syntax.
  • Screens and imports: Convert @screen rules to media conditions and normalize local imports.
  • Compatibility styles: Add targeted v3 compatibility CSS for changed defaults when the upgrade path needs it.

When utility rules and ordinary rules share an imported file, the tool can create a companion utility stylesheet and rewrite imports. If the original file becomes empty, it reuses the original file instead of leaving an unnecessary companion.

References: packages/…/migrate.ts• L17-56 packages/…/migrate-tailwind-directives.ts• L5-127 packages/…/migrate-missing-layers.ts• L4-161 packages/…/migrate-at-layer-utilities.ts• L8-16 packages/…/migrate-at-layer-utilities.ts• L289-339 packages/…/split.ts• L18-61 packages/…/split.ts• L63-187 packages/…/split.ts• L210-257

CSS compatibility

Compatibility CSS keeps visible behavior when a version changes a default that the old project did not set explicitly. The tool adds it only for the affected upgrade path, so later upgrades do not repeat the v3-to-v4 bridge.

The generated block is a review point. The project may keep the old default or replace it with an explicit current utility or theme value.

References: packages/…/migrate-preflight.ts• L11-33 packages/…/migrate-preflight.ts• L35-114

Template transformations

Template migration updates utility candidates in source files without changing the surrounding template or program logic. A candidate is a possible Tailwind utility string found by the content scan; the tool validates it against the current design system and the old project configuration before it changes the text.

The candidate pass handles prefix changes, renamed utilities, changed default scales, arbitrary-value syntax, important modifiers, variant order, and other known differences between Tailwind versions. The same candidate rules also serve CSS @apply migrations.

The tool favors a missed migration over an unsafe rewrite. It skips CSS files, ignored or generated paths, and strings that look like utilities but occur in style blocks, inline style values, conditions, function calls, event payloads, component variant values, or other non-class code. Recent safety checks also distinguish class strings from values such as Next.js image placeholders, Vue or Alpine attributes, Vue event names, JavaScript arguments, and variant values. Strings inside a component variant map remain eligible when they are class names.

When the candidate parser cannot validate a current utility, the original text remains unchanged. This lets an engineer review unusual or custom syntax instead of receiving a guessed rewrite.

References: packages/…/index.ts• L294-437 packages/…/candidates.ts• L5-17 packages/…/migrate.ts• L27-69 packages/…/migrate.ts• L73-135 packages/…/is-safe-migration.ts• L26-211 packages/…/is-safe-migration.ts• L213-322 packages/…/is-safe-migration.ts• L367-459 packages/…/is-safe-migration.test.ts• L24-231

Dependency and file changes

After source migration, the command aligns the project’s Tailwind package set with the new setup. It updates packages already in use, adds the current PostCSS package when needed, and removes obsolete packages only when the migrated configuration no longer uses them.

The command writes through a temporary file before replacing the target. A failed write or replacement therefore leaves the prior file in place, while the final report identifies files that need review.

References: packages/…/index.ts• L255-289 packages/…/index.ts• L440-453 packages/…/write-file-safely.ts• L5-49 packages/…/packages.ts• L25-73

Upgrade controls

The command provides a small set of controls for selecting project input and protecting the working tree. Its default mode checks the installed and expected Tailwind versions, blocks a dirty Git tree, and follows project ignore rules.

ControlPurpose
Positional CSS pathsLimit analysis to named stylesheets
--config / -cSelect the older JavaScript config when linking is unclear
--force / -fAllow migration with uncommitted changes
--help / -hShow command usage
--version / -vShow the upgrade tool version

The version check prevents version-specific migration rules from running with the wrong installed package. The detected major version also controls whether v3-to-v4 compatibility work applies.

References: packages/…/index.ts• L28-42 packages/…/index.ts• L44-89 packages/…/args.ts• L3-10 packages/…/version.ts• L11-62 packages/…/git.ts• L15-29

Change checklist

When these files or sections are changed, remember to consider these:

  • Changes to template safety checks must preserve the boundary between class strings and values used by framework props, style attributes, events, or program logic.
  • Changes to candidate safety checks must remain consistent with @apply, because CSS utility migration shares the template candidate rules.
  • Changes to variant-value detection must preserve class strings inside variant maps while skipping component variant names and comparisons.
  • Changes to stylesheet graph analysis must remain aligned with splitting, so a layer change does not alter the output order of imported utility rules.
  • Changes to config conversion must keep the compatibility path for dynamic or unsupported configs.
  • Changes to version checks must keep one-time compatibility CSS gated to the correct upgrade path.

Important failure modes

TriggerConsequenceGuard
A candidate appears inside a style block or inline style valueA CSS property name could be rewritten as a utilityKeep style-block and style-attribute range checks before candidate migration
A candidate is a framework prop value, event name, function argument, or conditionApplication data could change instead of a class nameRequire safe class context and reject known conditional positions
A class string appears in a component variant valueA variant name could be changed as if it were a utilityReject the active variant value but allow class strings in variant maps and class props
A candidate cannot be parsed or validated for the current design systemThe migration cannot prove that the replacement is validKeep the original text for manual review
One stylesheet is imported through utility and non-utility layersThe migrated output can change based on import pathReject the graph or split the stylesheet before migration
A configuration contains dynamic or unsupported logicAutomatic conversion could remove project behaviorRetain the old config and add a compatibility link

Key files

FileWhy to read it
packages/…/index.tsShows the end-to-end order from project checks through migration and reporting
packages/…/stylesheet.tsDefines the stylesheet graph and migration context
packages/…/analyze.tsShows how imports and layers become project analysis
packages/…/migrate.tsShows the coordinated CSS migration stages
packages/…/migrate-js-config.tsDefines the boundary between config conversion and compatibility fallback
packages/…/migrate.tsShows the shared candidate migration used for templates and @apply
packages/…/is-safe-migration.tsDefines the safety boundary for changing utility-like strings
packages/…/is-safe-migration.test.tsShows the supported class contexts and protected non-class contexts
packages/…/split.tsShows how mixed imported stylesheets preserve utility placement