Tailwind v3 to v4 Config Migrator
Convert a tailwind.config.js theme into v4's CSS-first @theme block, with the parts that moved elsewhere called out.
Turn a tailwind.config.js theme into v4's @theme block, with the pieces that moved elsewhere called out.
Converted
Values moved
9
Namespaces
5
Plugins are not part of @theme. In v4 they are loaded with @plugin "name"; in your CSS file.
darkMode moved to a custom variant: @custom-variant dark (&:where(.dark, .dark *));
The content array is gone. v4 detects sources automatically, with @source only for the unusual cases.
The config is read by scanning text, never by running it, because pasted JavaScript is untrusted input. That means an unusual config shape may be missed rather than mis-executed, so check the list against your original.
@import "tailwindcss";
@theme {
--color-surface: #0b0d12;
--color-brand: #6d5efc;
--color-brand-light: #8b7dff;
--color-brand-dark: #4a3cd0;
--font-sans: Inter, system-ui, sans-serif;
--radius-xl: 12px;
--radius-2xl: 16px;
--spacing-18: 4.5rem;
--breakpoint-3xl: 1920px;
}About the tailwind v3 to v4 config migrator
Tailwind v4 removed the JavaScript config. Theme values now live in an @theme block as CSS custom properties with a fixed naming convention: colours become --color-*, spacing --spacing-*, fonts --font-*. Translating a real config by hand is slow and easy to get subtly wrong.
This rewrites the mechanical half. It reads the theme and theme.extend blocks and emits the matching custom properties, then lists the things that did not move into @theme at all: plugins, dark mode, and the content array that v4 no longer needs.
How to use it
- 1Paste your tailwind.config.js.
- 2Copy the generated @theme block into your CSS entry file.
- 3Work through the list of what moved elsewhere.
- 4Delete the config file once nothing is left in it.
Questions
Does v4 still support tailwind.config.js?
It can load one for compatibility, but it is not the recommended path and new features assume the CSS-first form. Migrating means the config eventually disappears.
What is the naming convention?
The namespace decides the utility family. --color-brand creates bg-brand, text-brand and border-brand. --spacing-18 creates p-18 and m-18. The namespace is not optional; a custom property outside one is just a variable.
Which utilities were renamed?
The scale shifted for shadows, blur and rounded. The old shadow-sm is now shadow-xs, and the old shadow is shadow-sm. Also, bg-opacity-* and its siblings are gone in favour of the slash syntax, so bg-black/50.
Is my config executed?
No. It is read by scanning the text, never by running it, because pasted JavaScript is untrusted input. That means an unusual config shape may be missed rather than mis-executed, so check the output against your original.