Tailwind v4 salió a finales de 2024 y la primera reacción de muchos fue: "¿por qué cambiaron lo que funcionaba?". Después de migrar tres proyectos de VantLabs, mi reacción es: "ojalá hubiera cambiado más". Esta es la migración real, sin marketing.
Lo más raro: adiós a tailwind.config.js
En v3, toda tu configuración vivía en tailwind.config.js. Tema, plugins, content paths, presets. Era un archivo JavaScript familiar que cualquier dev podía leer.
En v4, ese archivo no existe. La configuración pasó a un bloque @theme inline dentro de tu CSS:
@import "tailwindcss";
@theme inline {
--color-accent-500: oklch(76% 0.230 132);
--font-display: "Bricolage Grotesque", system-ui;
--radius-lg: 20px;
}La primera reacción es de "esto se siente raro". Pero después de dos semanas, mi conclusión es que es mejor. Las razones:
- Tu paleta vive en CSS variables nativas, no en JavaScript. Eso significa que las puedes usar desde CSS puro, desde inline styles, desde otras librerías que esperan CSS variables. Una sola fuente de verdad.
- El build no necesita ejecutar JavaScript para resolver el theme. Es más rápido y más predecible.
- Color-mix, oklch, container queries y otros features modernos de CSS funcionan nativamente sin transformaciones, porque vives en CSS desde el principio.
Lo que dolió
1. Algunas utilities cambiaron de nombre. flex-shrink-0 sigue funcionando, pero shrink-0 es ahora canónica. overflow-ellipsis es text-ellipsis. Hay un codemod automático pero pasa el 80% — el 20% restante hay que cazar a mano.
2. Los plugins de v3 que dependían de la config JS no funcionan. @tailwindcss/typography en particular no tiene equivalente oficial en v4 al momento que migré. Tuve que escribir mi propio sistema de Prose con descendant selectors, lo cual está documentado en mi código en components/blog/prose.tsx. Funciona bien, pero fue trabajo extra.
3. Cascade layers cambiaron el debugging. Tailwind v4 usa cascade layers de forma más estricta: @layer theme, base, components, utilities. Si escribes CSS fuera de cualquier layer (como hacíamos todos en v3), entras al "implicit outer layer" que tiene MÁS prioridad que utilities. Eso causó que un p { margin: 0 } mío aplastara silenciosamente todos los mb-* aplicados a párrafos. Tres días de debugging me costó esa lección.
Lo que mejoró notablemente
OKLCH nativo. En v3 podías usar oklch en tu config, pero las utilities generadas eran HSL convertidos. En v4 las utilities son oklch genuino. Eso me da contraste perceptualmente correcto y dark-mode mixing que en HSL era imposible sin trucos. Es la razón por la que pude tener una paleta lime brillante con texto oscuro automáticamente accesible.
Container queries de primera clase. En v4 vienen built-in con sintaxis directa: @container en JSX. Antes había que instalar el plugin. Pequeño cambio, pero menos fricción.
Build más rápido. En proyectos medianos noté builds 30-40% más rápidos. Para un proyecto chico no se nota. Para uno grande con muchos componentes, se nota.
Menos archivos en el repo. Adiós a tailwind.config.js, adiós a postcss.config.js en algunos casos (el de v4 es minimal: solo carga @tailwindcss/postcss). Es satisfactorio.
Cuánto tiempo tomó
Para los tres proyectos:
- vantlabs.io (corporativo): 4 horas. Es chico y nuevo, así que no había deuda técnica.
- ReclamaAI (web): 12 horas. Más componentes, más utilities exóticas, plugin de typography que tuve que reemplazar.
- VantFi backend admin: 2 horas. Es mínimo en frontend.
Total: ~18 horas reales. Suma. Pero el ROI es positivo desde el día siguiente: el código es más limpio, el theme es más portable, y el build es más rápido. Para proyectos que esperas mantener años, vale la pena.
Lo que NO migraría todavía
Si estás trabajando en un proyecto crítico que lleva años en producción y depende fuertemente de plugins de typography, forms o aspect-ratio, espera. Algunos plugins están migrados, otros todavía no. Verifica primero que tu stack completo tenga equivalente en v4 antes de empezar la migración.
Para proyectos nuevos, en cambio: empieza directamente en v4. La curva de aprendizaje del bloque @theme inline es de un par de horas, y todo lo que aprendes te sirve para los próximos años de Tailwind.