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:
- Use named CSS paths when the user supplies them. Otherwise search for non-ignored CSS files.
- Parse each file and resolve local CSS imports. External files are not migration targets.
- Mark stylesheets that reference Tailwind as roots. If roots share a parent, use the common parent as the migration root.
- Link each root to an explicit
@configfile or detect the project configuration. Ambiguous links need@configor--config. - 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 concern | Current 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 |
| Prefix | A current import prefix and matching template candidates |
Unsupported corePlugins settings | A 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
@tailwinddirectives 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
@utilityrules. Keep unsafe selectors as ordinary CSS. - Variant rules: Move supported
@variantsinput into the utility flow. - Utility application: Apply the same candidate migration rules to utilities inside
@applyand templates. - Theme references: Convert supported
theme(…)references to current theme or variable syntax. - Screens and imports: Convert
@screenrules 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.
| Control | Purpose |
|---|---|
| Positional CSS paths | Limit analysis to named stylesheets |
--config / -c | Select the older JavaScript config when linking is unclear |
--force / -f | Allow migration with uncommitted changes |
--help / -h | Show command usage |
--version / -v | Show 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
| Trigger | Consequence | Guard |
|---|---|---|
| A candidate appears inside a style block or inline style value | A CSS property name could be rewritten as a utility | Keep style-block and style-attribute range checks before candidate migration |
| A candidate is a framework prop value, event name, function argument, or condition | Application data could change instead of a class name | Require safe class context and reject known conditional positions |
A class string appears in a component variant value | A variant name could be changed as if it were a utility | Reject 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 system | The migration cannot prove that the replacement is valid | Keep the original text for manual review |
| One stylesheet is imported through utility and non-utility layers | The migrated output can change based on import path | Reject the graph or split the stylesheet before migration |
| A configuration contains dynamic or unsupported logic | Automatic conversion could remove project behavior | Retain the old config and add a compatibility link |
Key files
| File | Why to read it |
|---|---|
| packages/…/index.ts | Shows the end-to-end order from project checks through migration and reporting |
| packages/…/stylesheet.ts | Defines the stylesheet graph and migration context |
| packages/…/analyze.ts | Shows how imports and layers become project analysis |
| packages/…/migrate.ts | Shows the coordinated CSS migration stages |
| packages/…/migrate-js-config.ts | Defines the boundary between config conversion and compatibility fallback |
| packages/…/migrate.ts | Shows the shared candidate migration used for templates and @apply |
| packages/…/is-safe-migration.ts | Defines the safety boundary for changing utility-like strings |
| packages/…/is-safe-migration.test.ts | Shows the supported class contexts and protected non-class contexts |
| packages/…/split.ts | Shows how mixed imported stylesheets preserve utility placement |