Tailwind CSS v3 Config to v4 Migrator

Tailwind CSS v4 moved theme customization out of tailwind.config.js and into CSS itself, via an @theme block of CSS custom properties. That's a real, mechanical rewrite for any project with a customized theme — every colors, spacing, fontFamily, and similar entry needs a matching --namespace-key: value; line, and getting the naming convention wrong (or missing that v3's top-level theme keys replace the defaults while v4's @theme always extends them) produces CSS that silently doesn't match the old config. This tool automates that specific translation and flags everything else — plugins, darkMode, renamed utilities — as an explicit checklist instead of guessing.

How it works

Paste your tailwind.config.js content into the input box. The tool:

• Locates the theme object (and theme.extend) and converts every recognized key — colors, spacing, fontFamily, fontSize, fontWeight, lineHeight, letterSpacing, borderRadius, boxShadow, screens, aspectRatio, blur, dropShadow, transitionTimingFunction — into its v4 --namespace-* CSS variable, flattening nested objects (colors.primary.600 → --color-primary-600) and handling a DEFAULT key as the bare variable name.
• Adds a --namespace-*: initial; reset line for any theme key that sat at the top level (not inside extend) — those replaced Tailwind's built-in scale in v3, and v4's @theme extends by default, so the reset is needed to reproduce the same behavior.
• Flags anything it can't convert safely: require(...) calls (a color palette import, for instance — copy the specific values you use directly), spread expressions, and theme keys with no direct v4 namespace.
• Produces a separate migration-notes checklist covering darkMode (converted to the @custom-variant dark CSS equivalent), your plugins list, and a static reference of utility classes Tailwind renamed between v3 and v4 (shadow-sm → shadow-xs, rounded → rounded-sm, flex-shrink-* → shrink-*, and more).

How to use it

1. Paste the full contents of your tailwind.config.js (or just the module.exports/export default object) into the input box.
2. The @theme CSS block and migration notes generate automatically.
3. Copy or download the CSS block into your stylesheet, then work through the migration-notes checklist for anything that needs a manual decision.

FAQ

Does this cover everything in a tailwind.config.js? No — it converts theme/theme.extend, the part with a genuine 1:1 CSS-variable equivalent. content/safelist globs aren't needed at all in v4 (template files are auto-detected), and plugins — arbitrary JavaScript functions — can't be mechanically translated, so they're listed in the notes for you to rewrite by hand as CSS @plugin/@utility/@variant rules.

Why does my config's colors object turn into a --color-*: initial; reset? Because it sat outside theme.extend — in v3, a top-level theme.colors replaces Tailwind's default palette entirely. v4's @theme always extends the defaults instead, so reproducing a v3 override requires explicitly resetting the namespace first with initial, then redefining it. If your customization was already inside extend, no reset is added.

Is my config sent anywhere? No — parsing and conversion run entirely in your browser (or, over the API, only inside that single request). Nothing is stored or logged.

What if I need the reverse — Tailwind classes from plain CSS, or CSS from Tailwind classes? See the CSS to Tailwind Converter and Tailwind Classes to CSS tools. For generating a custom color scale to add to your theme, try the Tailwind CSS Color Scale Generator.