Guía de Migración a Tailwind CSS v4: Todo lo que Cambió y Cómo Actualizar (2026)

Tailwind CSS v4 no es solo una actualización menor—es una reescritura completa. El equipo reconstruyó el motor desde cero usando Rust y Oxide, cambió cómo funciona la configuración, y eliminó el plugin de PostCSS por completo. Si has estado postergando el upgrade, esta guía te mostrará todo lo que cambió y exactamente cómo migrar.

Después de actualizar tres apps en producción, te puedo decir: vale la pena el dolor. Los tiempos de build bajaron 3-10x, el CSS de salida es más pequeño, y la nueva configuración CSS-first es más agradable una vez que te acostumbras.

Vamos a ver qué cambió y cómo manejar cada parte de la migración.

¿Qué cambió?

Antes de los pasos, entiende los cambios grandes:

1. Nuevo Motor Escrito en Rust (Oxide)

Tailwind v3 usaba un motor basado en JavaScript. v4 usa Oxide, un nuevo motor de alto rendimiento escrito en Rust. No es solo una reescritura—es fundamentalmente más rápido:

El motor Rust también significa mejor paralelización y menor uso de memoria. El HMR durante desarrollo se siente instantáneo ahora.

2. Configuración ahora en CSS

Este es el cambio más grande. En v3 configurabas todo en tailwind.config.js:

// v3: tailwind.config.js
module.exports = {
  theme: {
    extend: {
      colors: {
        primary: '#3b82f6',
        secondary: '#10b981',
      },
      fontFamily: {
        sans: ['Inter', 'sans-serif'],
      },
    },
  },
}

En v4, la configuración se mueve a tu archivo CSS usando @theme:

/* v4: app.css */
@import "tailwindcss";

@theme {
  --color-primary: #3b82f6;
  --color-secondary: #10b981;
  --font-sans: "Inter", sans-serif;
}

Por qué importa:

• La configuración vive con tus estilos
• Mejor autocompletado del IDE para valores custom
• Las custom properties de CSS son nativas—inspecciónalas en DevTools
• Sin archivo de config JS separado que mantener

3. Sin Plugin PostCSS

En v3, Tailwind era un plugin de PostCSS:

// v3: postcss.config.js
module.exports = {
  plugins: {
    tailwindcss: {},
    autoprefixer: {},
  },
}

En v4, Tailwind es un CLI independiente o plugin de Vite. PostCSS sigue soportado por compatibilidad, pero no es el default:

// v4: vite.config.ts (recomendado)
import tailwindcss from '@tailwindcss/vite'

export default {
  plugins: [tailwindcss()],
}

# v4: alternativa CLI
npx @tailwindcss/cli -i input.css -o output.css --watch

4. Detección Automática de Contenido

¿Recuerdas configurar las rutas de content en v3?

// v3: tailwind.config.js
module.exports = {
  content: [
    './src/**/*.{js,ts,jsx,tsx,mdx}',
    './components/**/*.{js,ts,jsx,tsx}',
  ],
}

En v4, Tailwind detecta automáticamente qué archivos usan clases de Tailwind analizando tu proyecto. Sin configuración para la mayoría de proyectos. Si necesitas personalizar:

/* v4: Override de auto-detección */
@import "tailwindcss";

@source "../node_modules/some-ui-library";

5. CSS Cascade Layers Nativo

v4 usa CSS @layer nativo (no la implementación custom de Tailwind):

/* v4 genera layers CSS reales */
@layer theme, base, components, utilities;

@layer utilities {
  .text-primary { color: var(--color-primary); }
}

Esto te da control de cascade apropiado y mejor integración con otro CSS.

Pasos de Migración

Vamos al grano. Te muestro los pasos para un proyecto típico React/Next.js.

Paso 1: Actualizar Dependencias

Elimina los paquetes viejos de Tailwind e instala v4:

# Eliminar paquetes v3
npm uninstall tailwindcss postcss autoprefixer

# Instalar v4
npm install tailwindcss@latest

# Si usas Vite, agrega el plugin
npm install @tailwindcss/vite

# Si usas Next.js, agrega el paquete de compatibilidad PostCSS
npm install @tailwindcss/postcss

Paso 2: Actualizar Configuración de Build

Para proyectos Vite:

// vite.config.ts
import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'
import tailwindcss from '@tailwindcss/vite'

export default defineConfig({
  plugins: [
    react(),
    tailwindcss(),
  ],
})

Para proyectos Next.js:

Next.js 15+ tiene soporte nativo para Tailwind v4. Para versiones anteriores:

// postcss.config.js (compatibilidad Next.js)
module.exports = {
  plugins: {
    '@tailwindcss/postcss': {},
  },
}

Para CLI independiente:

# Agregar a scripts de package.json
"scripts": {
  "css:build": "npx @tailwindcss/cli -i src/input.css -o dist/output.css",
  "css:watch": "npx @tailwindcss/cli -i src/input.css -o dist/output.css --watch"
}

Paso 3: Convertir tu Punto de Entrada CSS

Aquí es donde sucede la mayor parte del trabajo. Tu archivo CSS principal necesita reescribirse.

Antes (v3):

/* globals.css */
@tailwind base;
@tailwind components;
@tailwind utilities;

/* Estilos custom abajo */
.btn-primary {
  @apply bg-blue-500 text-white px-4 py-2 rounded;
}

Después (v4):

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

/* Estilos custom - ahora usa @layer apropiadamente */
@layer components {
  .btn-primary {
    @apply bg-blue-500 text-white px-4 py-2 rounded;
  }
}

Cambios clave:

• @tailwind base/components/utilities → @import "tailwindcss"
• Las clases de componentes custom deben estar en @layer components
• Los overrides de utilities van en @layer utilities

Paso 4: Migrar tailwind.config.js a @theme

Esta es la parte más complicada. Necesitas convertir la configuración JavaScript a CSS custom properties.

Antes (config v3):

// tailwind.config.js
module.exports = {
  theme: {
    extend: {
      colors: {
        primary: {
          50: '#eff6ff',
          100: '#dbeafe',
          500: '#3b82f6',
          600: '#2563eb',
          700: '#1d4ed8',
        },
        accent: '#f59e0b',
      },
      spacing: {
        '18': '4.5rem',
        '88': '22rem',
      },
      fontSize: {
        'xxs': '0.625rem',
      },
      borderRadius: {
        '4xl': '2rem',
      },
      fontFamily: {
        sans: ['Inter', 'system-ui', 'sans-serif'],
        mono: ['JetBrains Mono', 'monospace'],
      },
      screens: {
        'xs': '475px',
        '3xl': '1920px',
      },
    },
  },
}

Después (v4 @theme):

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

@theme {
  /* Colores usan prefijo --color-* */
  --color-primary-50: #eff6ff;
  --color-primary-100: #dbeafe;
  --color-primary-500: #3b82f6;
  --color-primary-600: #2563eb;
  --color-primary-700: #1d4ed8;
  --color-accent: #f59e0b;

  /* Spacing usa prefijo --spacing-* */
  --spacing-18: 4.5rem;
  --spacing-88: 22rem;

  /* Font size usa prefijo --text-* */
  --text-xxs: 0.625rem;

  /* Border radius usa prefijo --radius-* */
  --radius-4xl: 2rem;

  /* Font family usa prefijo --font-* */
  --font-sans: "Inter", system-ui, sans-serif;
  --font-mono: "JetBrains Mono", monospace;

  /* Breakpoints usan prefijo --breakpoint-* */
  --breakpoint-xs: 475px;
  --breakpoint-3xl: 1920px;
}

Cheat Sheet de Nombres de Variables

Paso 5: Manejar Plugins

La mayoría de plugins v3 necesitan actualizaciones o fueron absorbidos en el core.

Plugin Typography:

npm install @tailwindcss/typography@latest

/* v4: Importar plugin en CSS */
@import "tailwindcss";
@plugin "@tailwindcss/typography";

Plugin Forms:

npm install @tailwindcss/forms@latest

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

Plugin Container Queries:

¡Ahora está en el core! No necesitas plugin:

<!-- Funciona nativamente en v4 -->
<div class="@container">
  <div class="@md:grid-cols-2">...</div>
</div>

Paso 6: Actualizar Utilities Deprecadas

Algunas utilities fueron renombradas o cambiaron:

Los modificadores de opacidad son ahora el estándar:

<!-- v3 -->
<div class="bg-blue-500 bg-opacity-50">...</div>

<!-- v4 -->
<div class="bg-blue-500/50">...</div>

Paso 7: Actualizar Dark Mode

Dark mode sigue funcionando igual, pero la configuración se movió:

/* v4: Habilitar dark mode basado en clase */
@import "tailwindcss";

@variant dark (&:where(.dark, .dark *));

O usa el default (prefers-color-scheme):

/* Este es el default - sin config necesaria */
@import "tailwindcss";

Problemas Comunes de Migración y Soluciones

Después de migrar varios proyectos, estos son los problemas que probablemente encontrarás:

Problema 1: "Unknown at-rule @tailwind"

Tu editor/linter sigue esperando sintaxis v3.

Solución: Actualiza tu archivo CSS para usar @import "tailwindcss" en lugar de las directivas viejas.

Problema 2: Colores Custom No Funcionan

Síntoma: bg-primary-500 no funciona después de la migración.

Solución: Asegúrate de que tus variables de color usen la convención exacta de nombres:

/* Mal */
--primary-500: #3b82f6;

/* Bien */
--color-primary-500: #3b82f6;

Problema 3: Errores de PostCSS en Next.js

Síntoma: Build falla con errores relacionados a PostCSS.

Solución: Asegúrate de usar el paquete de compatibilidad:

npm install @tailwindcss/postcss

// postcss.config.js
module.exports = {
  plugins: {
    '@tailwindcss/postcss': {},
  },
}

Problema 4: Plugins No Cargan

Síntoma: Las clases del plugin typography o forms no funcionan.

Solución: Los plugins ahora se cargan vía CSS, no config:

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

Problema 5: Detección de Contenido Falta Archivos

Síntoma: Las clases en ciertos archivos no generan CSS.

Solución: Usa @source para incluir rutas explícitamente:

@import "tailwindcss";

@source "../node_modules/@your-company/ui-kit/src";
@source "./content/**/*.mdx";

Problema 6: IDE No Reconoce Nueva Sintaxis

Solución: Actualiza la extensión Tailwind CSS IntelliSense de VS Code a la última versión. Soporta completamente la sintaxis v4 incluyendo @theme y @plugin.

Comparación de Performance: Números Reales

Esto es lo que medimos en una app Next.js en producción (500+ componentes):

El motor Oxide es genuinamente así de rápido. Si estás en un codebase grande, el upgrade vale la pena solo por performance.

Checklist de Migración

Usa este checklist para tu migración:

• Actualizar dependencias (tailwindcss@latest, eliminar paquetes viejos)
• Elegir integración: plugin Vite, PostCSS, o CLI
• Convertir directivas @tailwind a @import "tailwindcss"
• Mover tema de tailwind.config.js a @theme en CSS
• Actualizar plugins para usar sintaxis @plugin
• Convertir clases de opacidad a sintaxis de modificador (/50)
• Actualizar utilities renombradas
• Configurar dark mode si usas estrategia de clase
• Agregar @source para rutas de contenido no estándar
• Probar todas las páginas/componentes para regresiones visuales
• Actualizar extensión VS Code
• Eliminar archivos de config viejos después de confirmar que todo funciona

¿Deberías Actualizar?

Actualiza ahora si:

• Los tiempos de build son dolorosos (v4 es 5-10x más rápido)
• Quieres bundles CSS más pequeños
• Estás empezando un proyecto nuevo
• Te gusta el approach de configuración CSS-first

Espera si:

• Dependes mucho de plugins que no han sido actualizados
• Estás en medio de un release crítico
• Tu tailwind.config.js tiene lógica programática compleja

Para la mayoría de proyectos, el upgrade toma 1-4 horas dependiendo de la complejidad del config. Las ganancias de performance son reales—Tailwind v4 es el upgrade de framework CSS más suave que he hecho en años.

Conclusión

Tailwind v4 es un upgrade importante—nuevo motor, nuevo paradigma de config, nuevos defaults. El approach CSS-first con @theme se siente raro al principio pero tiene sentido cuanto más lo usas. La configuración se vuelve visible en DevTools, el IDE funciona mejor, y tu CSS es la fuente de verdad.

El motor Oxide es genuinamente rápido. Hot reloads instantáneos. Builds 5-10x más rápidos. Si estás en un proyecto grande, solo eso justifica migrar.

Empieza con algo simple para acostumbrarte, luego ataca tu codebase principal. No es complicado—solo diferente.

Feliz styling.