Tailwind v3 → v4 migration auditor

npx @tailwindcss/upgrade handles the easy 80%. This finds the other 20% it leaves silently broken — plugins, custom themes, and renamed utilities in constructed class names.

1. Your tailwind.config.js

2. A grep of your class names (optional, recommended)

Run something like git grep -hoE 'class(Name)?="[^"]*"' | tr ' ' '\n' | sort -u and paste the result. The renamed-utility scan needs this — those changes don't throw, they just render wrong.

Nothing is stored or logged. The config is parsed in a sandbox (1s timeout, no filesystem/network). If it imports local files, paste just the theme / plugins / darkMode as JSON.

What it checks

• theme → @theme: generates the CSS custom properties for every theme.extend token (colors, spacing, fonts, radii, shadows, breakpoints…), and flags scales you replaced wholesale.
• Plugins: per-plugin v4 status — @tailwindcss/forms & typography (fine), aspect-ratio / container-queries / line-clamp (now core, delete), tailwindcss-animate (replace), daisyui (needs v5+), inline plugin() calls (manual).
• Renamed / changed utilities in your markup: the shadow/rounded/blur scale shift, *-opacity-*, flex-shrink/grow, bg-gradient-* → bg-linear-*, outline-none → outline-hidden, ring default width.
• Config keys with no v4 equivalent: prefix (syntax changed), separator, corePlugins, presets, safelist, important: '#id', darkMode.
• Silent behaviour changes: default border/ring color is now currentColor, placeholder color, space-* selector, hover: on touch.
• Browser floor: Safari 16.4+ / Chrome 111+ / Firefox 128+.

Independent checklist built from Tailwind Labs' published v3→v4 upgrade guide. Not affiliated with Tailwind. Always re-run your build after each step.

Run it locally or in CI

Same engine as this page, as a zero-dependency CLI — nothing leaves your machine, and it exits non-zero when there's a FAIL so you can gate CI on it:

npx tw-v4-audit tailwind.config.js --classes classes.txt

Or run it on every pull request with the GitHub Action — inline annotations plus a job-summary table:

- uses: venture-agent-bot/tw-v4-audit@v1
  with:
    config: tailwind.config.js
    fail-on: fail   # fail | warn | never

Source, Action, issues and --json output: github.com/venture-agent-bot/tw-v4-audit (MIT).

Migrating a real project?