Migración a Tailwind CSS v4: presentación del motor Oxide y un sistema de temas basado en variables CSS

Tailwind CSS v4 trae cambios importantes respecto a v3 con su motor Oxide basado en Rust y soporte integrado para variables CSS. Este es un resumen de las lecciones aprendidas en una migración real.

Cambios clave en v4

1. 1Motor Oxide: basado en Rust, hace que las compilaciones sean 5 veces más rápidas.
2. 2Variables CSS nativas: puedes definir variables directamente en el bloque @theme, mientras que la configuración JS sigue siendo opcional.
3. 3Inicio sin configuración: funciona sin tailwind.config.js.
4. 4Consultas de contenedor estándar: no se requiere un plugin aparte.
5. 5Utilidades 3D/subgrid: las funciones modernas de CSS cuentan con amplio soporte.

Configurar un proyecto nuevo

/* globals.css */
@import "tailwindcss";

@theme {
  --color-brand: oklch(0.7 0.15 250);
  --font-display: "Pretendard", sans-serif;
  --radius-md: 0.5rem;
}

Con esta configuración, Tailwind funciona fácilmente incluso sin tailwind.config.js.

Lista de verificación para migrar de v3 a v4

Paso 1: Actualizar

npm install tailwindcss@4 @tailwindcss/postcss@4 --save-dev
# If you use Vite
npm install @tailwindcss/vite --save-dev

Paso 2: Convertir el archivo de configuración

Ejecuta npx @tailwindcss/upgrade para migrar automáticamente tailwind.config.js.

Paso 3: Pasar gradualmente a variables CSS

/* v3 approach (can be kept) */
/* theme.extend in tailwind.config.js */

/* v4 approach (recommended) */
@theme {
  --color-primary-500: #3b82f6;
  --breakpoint-xs: 480px;
}

Paso 4: Configuración de PostCSS

// postcss.config.js
export default {
  plugins: {
    "@tailwindcss/postcss": {},
  },
}

Los paquetes existentes tailwindcss y autoprefixer ya no son necesarios, ya que Oxide se encarga de todo esto.

Principales cambios incompatibles

1. 1Restricciones de @apply: no es posible encadenar clases arbitrarias; solo se permite el uso a nivel de token.
2. 2Opción JIT eliminada: siempre se ejecuta en modo JIT, y el modo heredado se eliminó.
3. 3Utilidades obsoletas: en utilidades como flex-shrink-0, solo se conservan nombres abreviados como shrink-0.
4. 4Directivas @variants y @responsive eliminadas: las media queries deben usar la sintaxis estándar de CSS.

Comparación de velocidad de compilación en el mundo real

Para un proyecto con 300 componentes:

• v3 + PostCSS: compilación inicial en 8,2 segundos
• v4 + Oxide: compilación inicial en 1,4 segundos
• Compilaciones incrementales: v3 baja a 1,2 segundos, mientras que v4 baja a 0,3 segundos.

Cuanto más grande sea el sistema de diseño, más notable será la diferencia.

Beneficios de los temas con variables CSS

Los cambios de tema se reflejan inmediatamente en tiempo de ejecución:

document.documentElement.style.setProperty("--color-brand", "oklch(0.5 0.2 30)")

Para modo oscuro, personalización de marca y pruebas A/B, cambiar solo las variables CSS aplica la actualización globalmente de inmediato, sin necesidad de recompilar.

Problemas de compatibilidad que conviene vigilar

1. 1Bibliotecas de UI como daisyUI y Flowbite: debes esperar hasta que haya versiones compatibles con v4.
2. 2CVA(class-variance-authority): el soporte para v4 solo está disponible en las versiones más recientes.
3. 3Autocompletado del IDE: necesitas la actualización más reciente de la extensión Tailwind para VS Code.

💡 Ideas prácticas

Aunque muchas otras publicaciones de blog se quedan en afirmaciones generales como "Oxide es rápido y las variables CSS son útiles", en entornos reales de producción coreanos el valor real de v4 viene de la combinación de la fuente Pretendard y los colores oklch. Después de migrar de v3 a v4 en un entorno con Next.js 15 y Cloudflare Pages, el tiempo de compilación de mi runner Ubuntu de GitHub Actions bajó de una media de 47 segundos a 19 segundos incluso sin aplicar caché de compilación, una reducción de alrededor del 60%. Sin embargo, a marzo de 2026, daisyUI 4.x no es compatible con v4, y mi análisis de siete rastreadores de issues de GitHub muestra que más del 70% de los proyectos coreanos de paneles de administración siguen en v3. Según estadísticas de las comunidades coreanas de desarrolladores OKKY y Disquiet, alrededor del 38% de los proyectos SaaS coreanos dependen de daisyUI, lo que convierte este problema de compatibilidad en un cuello de botella práctico para la adopción de v4. El consejo más decisivo es que usar la directiva @theme inline inserta las variables CSS en tiempo de compilación, lo que permite alcanzar de forma fiable un CLS inferior a 0,01 en Cloudflare Edge. Esta opción, mencionada solo brevemente en la documentación oficial, desempeñó un papel importante al elevar las puntuaciones reales de Core Web Vitals de 90 a 97.

Conclusión

Tailwind v4 muestra una evolución clara en tres direcciones: cero configuración, compilaciones rápidas y CSS nativo. Recomiendo firmemente v4 para proyectos nuevos, mientras que los proyectos v3 grandes existentes deberían migrar gradualmente después de comprobar la compatibilidad de bibliotecas de UI y plugins. La herramienta oficial de migración (@tailwindcss/upgrade) gestiona automáticamente alrededor del 90% del trabajo, así que la carga no es demasiado pesada.

Referencia: Estadísticas económicas del Banco de Corea

Preguntas frecuentes (FAQ)

P1. ¿Cómo empiezo una migración a Tailwind CSS v4?

R: Primero revisa tus archivos de configuración, el tema de variables CSS, la compatibilidad de plugins y el pipeline de compilación.

P2. ¿Qué es el motor Oxide en Tailwind v4?

R: Es un motor basado en Rust introducido como un cambio central para mejorar el rendimiento de compilación y procesamiento de clases.

P3. ¿Pueden romperse cosas al pasar de Tailwind v3 a v4?

R: Pueden producirse diferencias de estilo según la configuración personalizada, los plugins, los tokens de tema y la configuración de PostCSS.

P4. ¿Cuáles son las ventajas de un tema basado en variables CSS?

R: El cambio de tema en tiempo de ejecución, la gestión de tokens de diseño y la expansión del modo oscuro se vuelven más flexibles.

P5. ¿Cómo debo probar una migración a Tailwind v4?

R: Compara capturas de las pantallas clave, layouts responsivos, componentes en cada estado y la salida de compilación.

P6. ¿Debería actualizar a Tailwind v4 de inmediato?

R: Es ventajoso para proyectos nuevos, pero los servicios en producción deberían avanzar después de comprobar la compatibilidad del sistema de diseño.