Moving to Tailwind 4: where did the config file go
When I moved to Tailwind 4, my first question was: where is tailwind.config.ts?
The answer is that it is gone. Entirely. And this is not a mistake, it is the whole idea.
In Tailwind 3 you had two worlds: design tokens in a JavaScript config, styles in CSS. Tailwind 4 merged them — everything now lives inside CSS. On day one that feels odd, and then it starts to look obvious.
This article is about the practical side of that migration: what changes, what breaks, and what to know in advance.
What changes
Your colours used to live like this:
// tailwind.config.ts
export default {
theme: {
extend: {
colors: {
ink: '#0B0B0F',
signal: '#3B82F6',
},
},
},
}Now they live like this:
/* globals.css */
@import "tailwindcss";
@theme {
--color-ink: #0B0B0F;
--color-signal: #3B82F6;
}Different syntax, same result: bg-signal and text-ink work exactly as before.
But there is one important difference. Every token declared inside @theme is simultaneously a real CSS variable. Which means you can use it without Tailwind classes at all:
.custom-shadow {
box-shadow: 0 2px 12px var(--color-ink);
}In Tailwind 3 you had to duplicate the token in two places — the config and a CSS variable — to get that. Now there is a single source. For me this was the clearest benefit of the "CSS-first" idea.
The font trap
Fonts cost me the most time. The reason is that next/font hands you a variable, not a finished value:
import { Golos_Text } from 'next/font/google'
const golos = Golos_Text({
subsets: ['latin'],
variable: '--font-golos',
})Now you want to wire that into @theme. And a plain @theme will not do it, because it treats values as static and cannot resolve a reference to another variable.
The fix is @theme inline:
@theme inline {
--font-sans: var(--font-golos), system-ui, sans-serif;
--font-display: var(--font-unbounded), sans-serif;
--font-mono: var(--font-jetbrains), monospace;
}The inline keyword tells Tailwind: do not copy this value, keep it as a variable reference. Without it the font classes quietly stop working — no error, you just see the default font.
The rule: any token that references another CSS variable belongs in @theme inline.
Plugins and what to drop
During the migration I removed three packages outright.
The first was autoprefixer. Tailwind 4 handles prefixes itself; the separate step is unnecessary.
The second was a component library (daisyui in my case). This one is optional, but I dropped it deliberately: prebuilt components are great for a fast start, and after that you fight them on every customisation. Once you have your own design system they are an extra layer.
The third was the surplus lines in my PostCSS config. In Tailwind 4 a single plugin is usually enough.
If you have third-party Tailwind plugins, check their v4 support before migrating. That is the lesson I took from my Next 16 migration: it is not the main package that holds you back, it is the ecosystem around it.
What breaks
In practice three things needed attention.
First, arbitrary value syntax. Places written with square brackets (like w-[calc(100%-2rem)]) mostly keep working, but some need verifying.
Second, anything that depended on the config. I had a helper that read tokens out of tailwind.config.ts. It stopped working, because the file no longer exists. I moved it to reading a CSS variable instead.
Third, the default colour palette. Some shades shifted slightly. If your design depends on exact colours, declare your own tokens rather than leaning on the defaults.
The nicest surprise was elsewhere: configuring content paths (content: [...]) is not needed at all anymore. Tailwind 4 finds the files itself.
Where dark mode went
In Tailwind 3 the theme was driven by a darkMode: 'class' setting. It disappeared along with the config file, and you now declare the variant yourself:
@custom-variant dark (&:where([data-theme="dark"], [data-theme="dark"] *));At first glance that is extra work. In practice it turned out to be better, because the condition is now yours: I use a data-theme attribute rather than a class, and I write the selector exactly as I need it.
Tokens can also be swapped per theme. For that you write ordinary CSS outside the @theme block:
:root {
--color-surface: #FFFFFF;
}
[data-theme="dark"] {
--color-surface: #0B0B0F;
}The bg-surface class works in both themes and picks the right colour with no dark: prefix at all. That was impossible in Tailwind 3, because tokens there were not CSS variables but values resolved at build time.
Semantic tokens: name the role, not the colour
This is not a Tailwind 4 requirement, but the CSS-first approach makes it a natural step.
During the migration I renamed my tokens. They used to be colour names; now they are role names:
@theme {
--color-ink: #0B0B0F;
--color-signal: #3B82F6;
}
:root {
--color-surface: #FFFFFF;
--color-text: var(--color-ink);
--color-accent: var(--color-signal);
--color-border: #E5E5EA;
}The top block is the palette — raw colours. The bottom block is roles, referencing the palette.
The difference shows up in practice. To change the accent colour you edit one line. If your components write text-signal directly, you are walking through dozens of files instead.
A practical rule: use only role names in components. A raw colour name should appear nowhere but the palette declaration. That simple discipline makes later design-system changes several times cheaper.
Migration order
I went in this order and would recommend it:
- First, write down everything in
tailwind.config.ts— colours, fonts, spacing, breakpoints. That list is your actual design system. - Upgrade the package and simplify the PostCSS config.
- In
globals.css, write@import "tailwindcss"and create a@themeblock. - Move the tokens across. Colours take the
--color-*prefix, fonts--font-*, spacing--spacing-*. - Put fonts separately, in
@theme inline. - Delete the old config file and run
bun run build. - Walk through the site with your eyes — fonts and shadows especially.
That last step matters, because most Tailwind migration mistakes fail silently: the build passes, the class does not apply, and only your eyes catch it.
Is it worth it
My answer is yes, but not because of speed.
The main benefit is conceptual: your design system now lives in one place, in its own native language. Token duplication between a JavaScript config and CSS disappears. A new developer opens globals.css and sees the whole palette — no separate config file to hunt down.
If your project is small, the migration is an hour of work. If it is large and plugin-heavy, check the plugins first, because that is where the real work will be.