Tailwind CSS 4: Migración desde v3

Tailwind CSS 4 es la actualización más grande desde la v1. El cambio principal: la configuración se mueve de JavaScript a CSS. Ya no necesitas tailwind.config.js -- todo se define directamente en tu archivo CSS con @theme.

El motor nuevo (Oxide) es significativamente más rápido y detecta tus archivos automáticamente sin necesidad de configurar content. Esta guía cubre como migrar tu proyecto sin romper nada.

Migración automática

Tailwind incluye una herramienta qué hace la mayoria del trabajo:

npx @tailwindcss/upgrade

Esto escanea tu proyecto y:

• Actualiza los paquetes a v4
• Convierte tailwind.config.js a directivas CSS
• Renombra clases que cambiaron
• Actualiza imports en tu CSS

Revisa los cambios antes de commitear. La herramienta es buena pero no perfecta con configuraciones muy custom.

Cambio principal: CSS-first config

Antes (v3) tenias un archivo JS:

// tailwind.config.js (v3 -- ya no se usa)
module.exports = {
  content: ["./app/**/*.tsx", "./components/**/*.tsx"],
  theme: {
    extend: {
      colors: {
        brand: "#35b809",
      },
    },
  },
};

Ahora (v4) todo va en tu CSS:

/* globals.css (v4) */
@import "tailwindcss";
 
@theme inline {
  --color-brand: #35b809;
}

Ventajas: no hay archivo de config separado, los colores se definen como CSS variables nativas, y el autodetect de contenido elimina la necesidad de configurar content.

Cambios que rompen

Clases renombradas

Content detection automático

v4 detecta tus archivos automáticamente. Ya no necesitas:

// ESTO YA NO ES NECESARIO
content: ["./app/**/*.tsx", "./components/**/*.tsx"],

Si necesitas incluir o excluir paths especificos, usas @source en CSS:

@source "../node_modules/mi-librería";

@apply cambia

@apply sigue funcionando pero tiene algunas diferencias con clases que usan variables CSS. Si usas @apply mucho, revisa que los estilos se apliquen correctamente después de migrar.

Definir tu tema con @theme

@import "tailwindcss";
 
@theme inline {
  /* Colores custom */
  --color-brand: #35b809;
  --color-brand-hover: #6ec751;
  --color-surface: #111111;
  --color-border: #222222;
 
  /* Fuentes */
  --font-sans: "Geist", system-ui, sans-serif;
  --font-mono: "Geist Mono", monospace;
 
  /* Spacing custom */
  --spacing-18: 4.5rem;
  --spacing-88: 22rem;
 
  /* Border radius */
  --radius-soft: 0.625rem;
}

después usas tus valores como siempre:

<div class="bg-brand text-white rounded-soft p-18">
  Contenido con tema custom
</div>

Dark mode

v4 sigue soportando dark mode con la clase dark o con prefers-color-scheme:

@import "tailwindcss";
 
@custom-variant dark (&:where(.dark, .dark *));

<div class="bg-white dark:bg-zinc-900">
  Cambia según la clase .dark en html
</div>

Plugins

Si usas plugins como @tailwindcss/typography o @tailwindcss/forms, actualiza a las versiones compatibles con v4:

npm install @tailwindcss/typography@latest

En v4, los plugins se importan en CSS:

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

Checklist de migración

1. Correr npx @tailwindcss/upgrade
2. Verificar que los colores custom se migraron correctamente a @theme
3. Buscar y reemplazar clases renombradas que la herramienta no detecto
4. Eliminar tailwind.config.js si ya no lo necesitas
5. Probar la app completa visualmente -- los cambios de spacing o bordes pueden ser sutiles
6. Correr el build para verificar que no hay errores

Siguiente paso

Si estas configurando un proyecto nuevo con Tailwind v4, la guía de shadcn/ui cubre como integrar componentes UI que usan Tailwind. Y para el deploy de tu proyecto actualizado, revisa la guía de deploy en Vercel.