Tailwind CSS 4: Migracion desde v3

Tailwind CSS 4 es la actualizacion mas grande desde la v1. El cambio principal: la configuracion 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 mas rapido y detecta tus archivos automaticamente sin necesidad de configurar content. Esta guia cubre como migrar tu proyecto sin romper nada.

Migracion automatica

Tailwind incluye una herramienta que 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 automatico

v4 detecta tus archivos automaticamente. 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-libreria";

@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 despues 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;
}

Despues 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 segun 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 migracion

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 guia de shadcn/ui cubre como integrar componentes UI que usan Tailwind. Y para el deploy de tu proyecto actualizado, revisa la guia de deploy en Vercel.