Tailwind CSS 4: qué cambia y cómo migrar tu proyecto (guía práctica)

Tailwind 4: la reescritura que nadie esperaba

Tailwind CSS 4 no es una actualización incremental — es una reescritura completa. Adam Wathan y el equipo reescribieron el engine desde cero con Oxide, un compilador escrito en Rust que es hasta 10x más rápido que el anterior. Y de paso, cambiaron la forma en que se configura todo.

Si vienes de Tailwind 3, los cambios son significativos. Pero el resultado es un framework más rápido, más limpio y más cercano a CSS nativo. Migré crisartigas.com y aquí documento lo bueno, lo malo y los pain points.

Lo que cambia respecto a Tailwind 3

1. Adiós tailwind.config.js, hola @theme en CSS

El cambio más grande: la configuración sale del JavaScript y se mueve al CSS. En lugar de un archivo tailwind.config.js con objetos JavaScript, ahora defines tus tokens de diseño directamente en tu CSS:

Antes (Tailwind 3) — tailwind.config.js:

module.exports = {
  theme: {
    extend: {
      colors: {
        electric: '#3B5EFF',
        dark: '#1A1A1A',
      },
      fontFamily: {
        heading: ['Bricolage Grotesque', 'sans-serif'],
        body: ['Plus Jakarta Sans', 'sans-serif'],
      },
    },
  },
};

Después (Tailwind 4) — global.css:

@import "tailwindcss";

@theme {
  --color-electric: #3B5EFF;
  --color-dark: #1A1A1A;
  --font-heading: 'Bricolage Grotesque', sans-serif;
  --font-body: 'Plus Jakarta Sans', sans-serif;
}

Es más limpio, más explícito, y las variables CSS que genera son accesibles directamente en tu código. No más theme('colors.electric') — usas var(--color-electric).

2. El engine Oxide: velocidad bruta

El nuevo engine está escrito en Rust y compila increíblemente rápido. En mi proyecto (220 páginas), el tiempo de build de los estilos pasó de ~800ms a ~80ms. En HMR (hot module replacement) durante desarrollo, los cambios se reflejan prácticamente en tiempo real.

3. Container queries nativos

Una de las features más esperadas. Ahora puedes usar container queries directamente:

<div class="@container">
  <div class="@sm:flex @lg:grid @lg:grid-cols-3">
    <!-- Responde al tamaño del contenedor, no del viewport -->
  </div>
</div>

Esto cambia las reglas del juego para componentes reutilizables. Ya no necesitas media queries que responden al ancho de la ventana — cada componente responde a su propio contenedor.

4. 3D transforms y nuevas utilidades

Nuevas clases para rotaciones 3D, perspectiva y transformaciones que antes requerían CSS custom:

<div class="rotate-x-12 rotate-y-6 perspective-800">
  <!-- Elemento con transformación 3D -->
</div>

5. Mejoras en variantes

Variantes más potentes y composables, incluyendo not-*, has-* mejorado, y variantes de grupo más flexibles.

Cómo migrar: paso a paso

Paso 1: Ejecuta la herramienta de migración automática

npx @tailwindcss/upgrade

Esta herramienta analiza tu proyecto y hace los cambios automáticamente:

• Convierte tailwind.config.js a @theme en tu CSS
• Actualiza imports y directivas
• Renombra utilidades que cambiaron de nombre

En mi experiencia, resuelve correctamente el 80% de la migración.

Paso 2: Revisa lo que no migró

El otro 20% incluye:

Plugins de terceros: si usas plugins como @tailwindcss/typography, daisyUI o plugins custom, verifica que tienen versión compatible con v4. La mayoría de plugins oficiales ya se actualizaron, pero los de la comunidad pueden tardar.

Utilidades custom: si tenías utilidades custom en tu tailwind.config.js con addUtilities() o addComponents(), necesitas migrarlas a CSS puro con @utility:

/* Antes: en tailwind.config.js plugin */
/* addUtilities({ '.brutal-card': { ... } }) */

/* Después: en tu CSS */
@utility brutal-card {
  border: 2.5px solid var(--color-dark);
  border-radius: 20px;
  box-shadow: 4px 4px 0 var(--color-dark);
  transition: all 0.2s;
}

Breakpoints custom: si habías definido breakpoints personalizados, ahora se definen en @theme:

@theme {
  --breakpoint-xs: 475px;
  --breakpoint-3xl: 1920px;
}

Paso 3: Verifica visualmente

No confíes solo en que compila sin errores. Revisa cada página visualmente. En mi migración, encontré 3 problemas que la herramienta no detectó:

1. Opacidades con /: la sintaxis bg-dark/50 no cambió, pero algunos valores de opacidad se calculaban ligeramente diferente
2. Ring utilities: ring-2 cambió de box-shadow a outline internamente — el resultado visual puede variar
3. Space utilities: space-y-4 sigue funcionando pero si tenías overrides CSS, pueden entrar en conflicto

Paso 4: Limpia el config antiguo

Elimina tailwind.config.js, tailwind.config.ts y postcss.config.js (Tailwind 4 incluye PostCSS automáticamente). Menos archivos de configuración = menos mantenimiento.

Errores comunes en la migración

”Mis colores custom no funcionan”

Asegúrate de que los nombres en @theme usan el formato --color-nombre. Si antes tenías colors: { brand: '#123' }, ahora es --color-brand: #123;.

”El purge no funciona”

Tailwind 4 usa detección automática de contenido. Ya no necesitas configurar content: ['./src/**/*.astro']. Si algo no se detecta, puedes usar @source en tu CSS:

@source "../components/**/*.astro";

“Mi plugin de tipografía se rompió”

@tailwindcss/typography v4 cambió la forma de customizar. Las clases prose siguen funcionando, pero los overrides por componente ahora se hacen con CSS custom properties en lugar de config JS.

¿Vale la pena migrar?

Si estás empezando un proyecto nuevo: sí, sin duda. Tailwind 4 es superior en todo.

Si tienes un proyecto existente en Tailwind 3: depende. Si es un proyecto activo con desarrollo frecuente, la migración vale la pena por la velocidad de compilación y las nuevas features. Si es un proyecto en mantenimiento que apenas se toca, quédate en v3 hasta que sea necesario.

Mi regla: migra cuando necesites una feature nueva de v4 o cuando empieces a tener problemas de velocidad de compilación. No migres solo por estar en la última versión.