Tailwind v4 en profundidad: qué cambia y cómo migrar tu proyecto

Tailwind v4 es la reescritura más profunda que ha hecho el framework desde su creación. Motor nuevo en Rust, configuración basada en CSS, variables nativas como primera clase y alineación con estándares modernos como cascade layers, color-mix() y container queries. Para proyectos nuevos, es un salto obvio. Para proyectos en v3, la migración es más corta de lo que parece si sabes qué tocar. Esta guía cubre las novedades, los breaking changes y los pasos para migrar sin llevarse sorpresas.

Si también gestionas un proyecto Next.js, te interesa leer después la guía de migración a Next.js 16, que complementa esta para tener el stack completo actualizado.

Novedades principales de Tailwind v4

1. Motor Oxide (Rust) para builds ultra-rápidos

El corazón del cambio. Tailwind v4 reescribe el compilador en Rust (proyecto Oxide) y abandona el pipeline basado en PostCSS puro. Resultado: builds iniciales 3-5× más rápidos, rebuilds incrementales hasta 100× más rápidos. En desarrollo, el HMR con Tailwind deja de ser un cuello de botella.

2. Configuración CSS-first

Se acabó tailwind.config.js como archivo central. En v4 toda la configuración vive en tu CSS mediante el bloque @theme:

@import "tailwindcss";

@theme {
  --color-brand: #fa3a00;
  --color-brand-dark: #0a0a0a;
  --font-sans: "Inter", system-ui, sans-serif;
  --breakpoint-3xl: 1920px;
  --radius-2xl: 1.25rem;
}

Tailwind lee el bloque @theme y genera automáticamente las utilidades correspondientes: bg-brand, text-brand-dark, font-sans, 3xl:, rounded-2xl. No hay configuración JavaScript, no hay árbol de objetos profundos con theme.extend.

3. Variables CSS nativas en todo el sistema

Todos los valores del theme están disponibles como variables CSS nativas en tiempo de ejecución. Puedes combinarlos con color-mix(), cambiar temas con un único cambio de variable y consumirlos en CSS puro fuera de Tailwind:

.custom-button {
  background: var(--color-brand);
  border: 2px solid color-mix(in oklch, var(--color-brand) 70%, white);
}

4. Detección automática de contenido

Adiós a content: ["./src/**/*.tsx"]. Tailwind v4 detecta automáticamente los archivos del proyecto usando el sistema de ficheros y respetando .gitignore. Para casos especiales puedes añadir @source en tu CSS:

@import "tailwindcss";
@source "../packages/ui/**/*.{ts,tsx}";

5. Container queries nativos

Lo que antes era un plugin externo ahora es utilidad nativa:

<div className="@container">
  <div className="@md:grid-cols-2 @lg:grid-cols-3 grid grid-cols-1 gap-4">
    {/* se adapta al ancho del contenedor, no del viewport */}
  </div>
</div>

6. Valores dinámicos en utilidades

Ya no hace falta registrar cada valor. Las utilidades de tamaño, espaciado y opacidad aceptan números arbitrarios directamente basados en la variable --spacing:

// v3: solo valores predefinidos (p-4, p-8, p-12...)
// v4: cualquier número (dentro de la escala spacing)
<div className="p-17 gap-[21] rounded-3" />

7. Nuevos gradientes y 3D transforms

v4 añade utilidades para gradientes cónicos (bg-conic), radiales (bg-radial), interpolación en espacios de color (oklch, oklab) y transformaciones 3D nativas (rotate-x-45, translate-z-10).

Breaking changes de v3 a v4

Migración paso a paso desde Tailwind v3

Paso 1 — Backup y rama nueva

Commit limpio del estado actual y rama dedicada. No mezcles la migración con otros cambios:

git checkout -b chore/tailwind-v4
git status # debe estar limpio

Paso 2 — Ejecuta el codemod oficial

Tailwind mantiene un upgrade CLI que automatiza el 80% de la migración:

npx @tailwindcss/upgrade@latest

El codemod se encarga de:

• Actualizar tailwindcss a v4 y añadir @tailwindcss/postcss.
• Cambiar @tailwind base/components/utilities por @import "tailwindcss";.
• Convertir clases renombradas (shadow-sm → shadow-xs, text-opacity-* → sintaxis slash).
• Migrar la mayor parte de tailwind.config.js a @theme.
• Actualizar postcss.config.js.

Paso 3 — Instala dependencias según tu bundler

# Next.js / Vite con PostCSS
npm install -D tailwindcss@latest @tailwindcss/postcss

# Vite con plugin nativo (alternativa más rápida)
npm install -D tailwindcss@latest @tailwindcss/vite

# CLI standalone
npm install -D @tailwindcss/cli

Paso 4 — Limpia y adapta tu CSS

Así queda tu globals.css después del codemod:

@import "tailwindcss";

@theme {
  --color-background: #0a0a0a;
  --color-brand: #fa3a00;
  --color-brand-dark: #c92e00;
  --font-sans: "Inter", system-ui, sans-serif;
}

@layer base {
  body {
    background: var(--color-background);
    color: white;
  }
}

Paso 5 — Revisa el comportamiento default

Algunos cambios por defecto pueden alterar tu diseño visualmente:

• Bordes sin color explícito ahora usan currentColor. Si tenías border esperando gris claro, añade border-gray-200.
• Botones nativos ahora tienen cursor: pointer por defecto. Tu código posiblemente lo añadía manualmente — puedes quitarlo.
• Anillos de foco cambiaron de 3px a 1px. Si tu UI dependía del grosor, añade ring-[3px] donde haga falta.
• Sombras: shadow-sm pasa a valor mayor, shadow-xs es la nueva pequeña. Revisa cards y tooltips.

Paso 6 — Migra plugins

Los plugins oficiales tienen versiones v4:

npm install -D @tailwindcss/typography@latest \
               @tailwindcss/forms@latest \
               @tailwindcss/aspect-ratio@latest

Se registran en CSS, no en JS:

@import "tailwindcss";
@plugin "@tailwindcss/typography";
@plugin "@tailwindcss/forms";

Paso 7 — Prueba el build

npm run build

# Si usas Next.js + Turbopack:
npm run dev # verifica HMR instantáneo

Si el build pasa y la UI sigue viéndose como antes, la migración está hecha. Los diffs visuales suelen ser pequeños (sombras, bordes). Haz un smoke test visual de las páginas principales.

Checklist final de migración

• ☐ npx @tailwindcss/upgrade@latest ejecutado
• ☐ @tailwindcss/postcss instalado
• ☐ CSS con @import "tailwindcss";
• ☐ Configuración migrada a @theme
• ☐ Plugins actualizados a versión v4
• ☐ Clases renombradas ajustadas (shadow-xs, slash opacity)
• ☐ Bordes y focus rings revisados
• ☐ Build de producción en verde
• ☐ Smoke test visual de páginas principales
• ☐ Commit con todo el diff de migración

Errores comunes durante la migración

"Module not found: tailwindcss"

Olvidaste instalar @tailwindcss/postcss. En v4 el plugin PostCSS vive en un paquete separado. Instálalo y actualiza postcss.config.js.

Los estilos se ven rotos tras migrar

Casi siempre por el cambio de border default o el cambio de escala de shadows. Revisa componentes con border sin color y cards con shadow-sm.

"Config is ignored" en tailwind.config.js

Tu tailwind.config.js ya no se detecta automáticamente. O lo migras a @theme, o lo cargas explícitamente con @config:

@import "tailwindcss";
@config "../../tailwind.config.js";

Container queries no funcionan

Falta envolver el contenedor con @container. Los prefijos @md:, @lg: solo se aplican dentro de un ancestro con esa clase.

¿Cuándo tiene sentido migrar?

• Proyecto nuevo: empieza en v4 directamente.
• Proyecto pequeño-medio en v3: migración de 1-3h con el codemod. Merece la pena por la velocidad de builds.
• Proyecto grande con muchos plugins custom: 1-2 días. Agenda ventana tranquila, no lo metas a medias de un sprint.
• Con UI libraries (shadcn/ui, etc.): espera a que la librería publique soporte oficial de v4 antes de migrar. La mayoría ya lo tiene.

Conclusión

Tailwind v4 es un salto generacional. Cambia el motor, cambia la filosofía de configuración y abre la puerta a CSS moderno (cascade layers, color-mix, container queries) como ciudadanos de primera. La migración desde v3 es más corta de lo que parece gracias al codemod oficial — para un proyecto medio son unas pocas horas y un par de smoke tests. El retorno es inmediato: builds más rápidos, menos configuración JavaScript y un sistema de diseño que vive en CSS, donde pertenece.

Si tienes el stack Next.js + Tailwind al día te recomiendo leer también la guía de migración a Next.js 16 y la guía de SEO para Next.js. Si quieres que te ayudemos con la migración o con un proyecto nuevo, escríbenos a /contacto.