Guía de migración definitiva a Tailwind CSS v4

La llegada de Tailwind CSS v4.0 representa uno de los cambios más importantes en la historia del framework de utilidades. Con un motor de compilación escrito en Rust (Oxide) completamente renovado, las velocidades de compilación son hasta 10 veces más rápidas, y el sistema de configuración se traslada por completo a directivas nativas de CSS en lugar del clásico archivo javascript. Sin embargo, migrar un proyecto existente de la v3 a la v4 requiere entender bien las diferencias críticas para no romper el diseño en el camino.

El nuevo modelo: Adiós a tailwind.config.js

El principal cambio en la versión 4 es la eliminación del archivo tailwind.config.js. Ahora, toda la configuración de fuentes, colores, espaciados y temas se realiza directamente dentro de tu archivo CSS principal (por ejemplo, globals.css) usando la directiva @theme. Esto simplifica la base de código ya que no tenemos que mezclar javascript con declaraciones de estilos CSS. Por ejemplo, definir un color personalizado ahora es tan simple como declarar una variable CSS dentro de la directiva @theme en tu archivo de estilos de entrada.

Pasos para la migración

Para migrar un proyecto existente, el primer paso es actualizar las dependencias en tu package.json instalando la versión más reciente de tailwindcss y su plugin de postcss correspondiente si estás usando un framework como Next.js con configuración tradicional. Si estás en Next.js con el compilador Turbopack, puedes utilizar la nueva integración nativa que no requiere postcss configurado a mano.

Una vez instaladas las dependencias, debes mover las extensiones de temas que tenías en tu antiguo tailwind.config.js al bloque @theme dentro de tu CSS. Las tipografías personalizadas y las animaciones ahora se declaran usando sintaxis CSS estándar. Por ejemplo, las animaciones y keyframes ahora se definen directamente usando propiedades estándar de CSS, y Tailwind v4 las compilará automáticamente en utilidades utilizables en tu JSX.

Depurando clases obsoletas

Un detalle importante de Tailwind v4 es que algunas clases heredadas y comportamientos por defecto han cambiado. La directiva @import 'tailwindcss'; reemplaza las antiguas directivas @tailwind base;, @tailwind components; y @tailwind utilities;. Asegúrate de revisar que tus selectores personalizados y componentes no dependan de comportamientos antiguos de reseteo (Preflight), ya que el reset de la v4 es ligeramente más moderno y compatible con las especificaciones actuales del W3C.

La migración a la v4 no solo limpia tu arquitectura eliminando archivos de configuración intermedios, sino que reduce sustancialmente el tamaño de tu bundle final en producción gracias a un análisis de dependencias mucho más preciso. Es un paso obligatorio para mantener cualquier portfolio o aplicación comercial en el estado del arte de la performance web.