Tailwind CSS v4: Guía de migración y nuevas funciones

Tailwind CSS v4 es la reescritura más importante desde el lanzamiento del marco. El archivo de configuración de JavaScript desapareció y fue reemplazado por una configuración de CSS primero que utiliza propiedades personalizadas. La API de clase prácticamente no ha cambiado, pero los componentes internos son completamente nuevos: un motor basado en Rust (oxide), soporte de primera clase para la gama de colores P3, consultas de contenedores nativos y una canalización de compilación que se integra directamente con CSS en lugar de a través de complementos PostCSS.

Esta guía le explica qué cambió, por qué cambió y cómo migrar una aplicación de producción real de Tailwind v3 a v4. Cubriremos los cambios más importantes que lo harán tropezar y las nuevas funciones que vale la pena adoptar de inmediato.

Conclusiones clave

• tailwind.config.js está en desuso: la configuración se traslada a CSS usando la directiva @theme
• La importación cambió de @tailwind base/components/utilities a un solo @import "tailwindcss"
• Los colores personalizados ahora usan propiedades personalizadas de CSS en el espacio de nombres --color-*
• La configuración content es automática: Tailwind v4 escanea archivos automáticamente a través de glob
• Las consultas de contenedor ahora están integradas con las variantes @container y @sm:, @lg:
• Compatibilidad con la gama de colores P3 a través del espacio de color oklch() para todos los colores integrados
• @apply todavía funciona pero es menos necesario con las propiedades personalizadas de CSS
• El motor JIT es reemplazado por Oxide (Rust): compilación dramáticamente más rápida

---

Qué cambió y por qué

Tailwind v3 utilizó PostCSS como canal de procesamiento, un archivo de configuración de JavaScript y generó clases de utilidad a través de un motor JIT escrito en JavaScript. Esto funcionó bien pero tenía limitaciones:

• La configuración requiere JavaScript, lo que lo hace inaccesible desde herramientas exclusivas de CSS
• Las propiedades personalizadas debían configurarse por separado de la configuración de Tailwind
• Las consultas de contenedores requerían un complemento.
• El sistema de color no admitía la gama P3

Tailwind v4 aborda todo esto moviendo la configuración al propio CSS, utilizando el sistema de propiedades personalizadas CSS nativo del navegador y reescribiendo el motor en Rust para compilaciones entre 5 y 10 veces más rápidas.

---

Instalación

# Tailwind v4
pnpm add tailwindcss@^4.0.0 @tailwindcss/vite

# For Next.js
pnpm add tailwindcss@^4.0.0 @tailwindcss/postcss

El complemento @tailwindcss/vite se integra directamente con Vite. Para Next.js (que usa PostCSS internamente), use @tailwindcss/postcss.

---

Primera configuración CSS

Este es el mayor cambio conceptual. Su globals.css se convierte en la fuente de verdad para la configuración de Tailwind:

/* Before: globals.css with v3 */
@tailwind base;
@tailwind components;
@tailwind utilities;

/* After: globals.css with v4 */
@import "tailwindcss";

/* Theme configuration replaces tailwind.config.js */
@theme {
  /* Custom colors as CSS custom properties */
  --color-brand-50: oklch(97% 0.02 250);
  --color-brand-100: oklch(94% 0.04 250);
  --color-brand-500: oklch(62% 0.18 250);
  --color-brand-900: oklch(28% 0.09 250);

  /* Custom font families */
  --font-sans: 'Inter', system-ui, sans-serif;
  --font-mono: 'JetBrains Mono', monospace;

  /* Custom spacing */
  --spacing-18: 4.5rem;
  --spacing-88: 22rem;

  /* Custom breakpoints */
  --breakpoint-3xl: 1920px;

  /* Custom shadows */
  --shadow-card: 0 1px 3px oklch(0% 0 0 / 12%), 0 1px 2px oklch(0% 0 0 / 8%);
}

Su tailwind.config.js se puede eliminar (o conservar por ahora; la versión 4 admite ambos durante la migración).

---

Detección de contenido

Tailwind v4 detecta automáticamente archivos de plantilla. La configuración content que mantuviste meticulosamente en v3 ya no existe:

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

En v4, Tailwind escanea su proyecto automáticamente utilizando valores predeterminados sensatos. Si tiene archivos en ubicaciones inusuales, puede incluirlos explícitamente:

@import "tailwindcss";
@source "../scripts/*.ts"; /* Scan additional paths */
@source "../../packages/ui/src/**/*.tsx"; /* Monorepo workspace packages */

---

Actualización de configuración posterior a CSS

Para proyectos Next.js (y cualquier configuración basada en PostCSS), actualice su configuración de PostCSS:

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

// After: postcss.config.mjs with v4
export default {
  plugins: {
    '@tailwindcss/postcss': {},
  },
};

autoprefixer está incluido en @tailwindcss/postcss de forma predeterminada. Elimine la dependencia autoprefixer separada.

---

Sistema de color: OKLCH

Tailwind v4 utiliza OKLCH para su paleta de colores incorporada. OKLCH es un espacio de color perceptualmente uniforme: ajustar la luminosidad en realidad parece pasos iguales para el ojo humano, a diferencia de HSL.

/* v4 colors use OKLCH internally */
/* bg-blue-500 generates: */
background-color: oklch(62.8% 0.258 264.1);

/* Custom colors with OKLCH */
@theme {
  --color-ecosire-amber: oklch(78% 0.18 80);
  --color-ecosire-navy: oklch(22% 0.04 250);
}

Para pantallas de gama más amplia (la mayoría de los teléfonos y Mac modernos), OKLCH habilita colores que sRGB simplemente no puede representar. Los valores oklch() se convierten automáticamente a rgb() para pantallas que no admiten P3.

---

Consultas de contenedor: integradas

Las consultas de contenedores ahora son de primera clase en la versión 4. No se necesita complemento:

/* Define a container */
.card-wrapper {
  container-type: inline-size;
  container-name: card;
}

<!-- Responsive based on parent container, not viewport -->
<div class="card-wrapper">
  <div class="@sm:flex-row @lg:grid-cols-3 flex flex-col">
    <!-- Layout changes based on container width, not screen width -->
  </div>
</div>

Esto permite la capacidad de respuesta a nivel de componente: una tarjeta de barra lateral y una tarjeta de ancho completo pueden tener diseños diferentes sin CSS separado.

Los contenedores con nombre le permiten dirigirse a ancestros específicos:

<div class="card-wrapper [container-name:card]">
  <div class="@card/sm:text-lg text-base">
    Responsive to the 'card' container
  </div>
</div>

---

Integración de propiedades personalizadas de CSS

Las propiedades personalizadas definidas en @theme son accesibles en todas partes: CSS, JavaScript y herramientas de diseño que leen variables CSS:

@theme {
  --color-primary: oklch(62% 0.18 250);
  --spacing-section: 5rem;
}

// Access in JavaScript/TypeScript
const style = getComputedStyle(document.documentElement);
const primary = style.getPropertyValue('--color-primary');

<!-- Use in inline styles -->
<div style={{ color: 'var(--color-primary)' }}>
  Themed content
</div>

Esto reemplaza el patrón de mantener valores paralelos en tailwind.config.js y un archivo tokens.ts; ahora hay una única fuente de verdad en CSS.

---

Cambios importantes

1. Cambios en la API del complemento

Los complementos v3 que usan addBase, addComponents, addUtilities son incompatibles con v4. Vuelva a escribirlos como CSS usando el nuevo sistema de capas:

/* v3 plugin equivalent in v4 CSS */
@layer base {
  h1 {
    @apply text-3xl font-bold;
  }
}

@layer components {
  .btn {
    @apply px-4 py-2 rounded-lg font-medium;
  }
}

2. @apply con clases personalizadas

@apply con clases que no son Tailwind está más restringido en v4. Utilice @apply solo con clases de servicios públicos reales:

/* This works in v4 */
.btn-primary {
  @apply bg-blue-500 text-white px-4 py-2 rounded-lg;
}

/* This is deprecated — use regular CSS instead */
.btn-primary {
  @apply custom-shadow; /* custom-shadow is not a Tailwind utility */
}

3. tailwind.config.js theme.extend ya no está

La configuración en JS ya no es la ruta principal. Utilice @theme en CSS. Si tiene ambos, la configuración CSS tiene prioridad.

4. Nombre de paleta de colores predeterminado

Algunos nombres de colores cambiaron en v4. Ejecute el codemod oficial para capturarlos:

npx @tailwindcss/upgrade@next --config tailwind.config.js

---

Estrategia de migración

Para una aplicación de producción grande, migre de forma incremental:

Fase 1: Instalación de la actualización

pnpm remove tailwindcss autoprefixer postcss
pnpm add tailwindcss@^4.0.0 @tailwindcss/postcss

Actualización postcss.config.mjs:

export default {
  plugins: { '@tailwindcss/postcss': {} },
};

Actualización globals.css:

/* Replace the three @tailwind directives */
@import "tailwindcss";

Fase 2: ejecutar el codemod

npx @tailwindcss/upgrade@next

Esto automatiza la mayor parte de la migración: actualiza los nombres de los colores, convierte la configuración a CSS y señala problemas que necesitan atención manual.

Fase 3: Mover la configuración a CSS

Tome los valores de su tema tailwind.config.js y muévalos a @theme en su CSS. Elimine el archivo de configuración después de la verificación.

Fase 4: Adoptar nuevas funciones

Reemplace los puntos de interrupción de respuesta basados ​​en ventanas gráficas con consultas de contenedor cuando corresponda. Adopte OKLCH para colores personalizados y obtener compatibilidad con la gama P3.

---

Mejoras de rendimiento

El motor Oxide (Rust) de Tailwind v4 ofrece construcciones considerablemente más rápidas:

Para aplicaciones grandes, esto se traduce en un desarrollo de HMR notablemente más rápido y tiempos de construcción de CI significativamente más cortos.

---

Ejemplo de migración en el mundo real

Aquí hay un antes/después práctico para la configuración básica de un sistema de diseño:

// Before: tailwind.config.js (v3)
module.exports = {
  theme: {
    extend: {
      colors: {
        brand: {
          50: '#fef3c7',
          500: '#f59e0b',
          900: '#78350f',
        },
      },
      fontFamily: {
        sans: ['Inter', 'system-ui'],
      },
      boxShadow: {
        card: '0 1px 3px rgba(0,0,0,0.12)',
      },
    },
  },
  plugins: [
    require('@tailwindcss/typography'),
    require('@tailwindcss/forms'),
  ],
};

/* After: globals.css (v4) */
@import "tailwindcss";
@plugin "@tailwindcss/typography";
@plugin "@tailwindcss/forms";

@theme {
  --color-brand-50: oklch(97% 0.04 85);
  --color-brand-500: oklch(78% 0.18 85);
  --color-brand-900: oklch(33% 0.08 85);

  --font-sans: 'Inter', system-ui, sans-serif;

  --shadow-card: 0 1px 3px oklch(0% 0 0 / 12%);
}

La configuración nativa de CSS es más concisa y elimina la dependencia de node_modules para leer la configuración.

---

Preguntas frecuentes

¿Necesito eliminar tailwind.config.js inmediatamente?

No: Tailwind v4 admite la configuración JS y CSS simultáneamente durante la migración. La configuración JS todavía funciona, pero funciones como @theme en CSS solo están disponibles sin ella. Migre de forma incremental: primero cree la aplicación con v4, luego mueva gradualmente la configuración a CSS y luego elimine la configuración JS cuando esté seguro.

¿Mis clases existentes de Tailwind v3 seguirán funcionando en v4?

La gran mayoría de las clases de servicios públicos se mantienen sin cambios. Se actualizaron algunos nombres de colores (gris → neutro en algunos contextos) y se eliminaron algunas utilidades obsoletas. Ejecute npx @tailwindcss/upgrade@next para detectar la mayoría de los problemas automáticamente. Las principales incompatibilidades están en los complementos y la configuración de temas personalizados, no en cómo usa las clases en HTML/JSX.

¿OKLCH es compatible con todos los navegadores?

OKLCH es compatible con todos los navegadores modernos (Chrome 111+, Firefox 113+, Safari 15.4+). Tailwind v4 genera alternativas para navegadores más antiguos cuando sea necesario. Para la gama de colores P3 (los colores ampliados), la compatibilidad requiere una pantalla de gama amplia y un navegador compatible: Tailwind genera rgb() reservas para pantallas de gama más estrecha.

¿Cómo uso Tailwind v4 con shadcn/ui?

shadcn/ui 2.0+ es compatible con Tailwind v4. Actualice su components.json para usar el formato de variables CSS v4. La biblioteca de componentes utiliza propiedades personalizadas de CSS para la temática, que se asigna naturalmente al sistema @theme de Tailwind v4. Ejecute npx shadcn@latest init en un proyecto existente para obtener la configuración compatible con v4.

¿Existen tipos de TypeScript para la nueva configuración?

La configuración de Tailwind v4 es CSS, por lo que no hay tipos de TypeScript para la configuración en sí. La compatibilidad con IDE proviene de servicios de lenguaje CSS que comprenden propiedades personalizadas. Para acceder a los valores del tema en TypeScript (para gráficos, animaciones, etc.), use getComputedStyle para leer las propiedades personalizadas de CSS en tiempo de ejecución o genere un archivo de tokens desde su CSS como parte de su compilación.

---

Próximos pasos

Tailwind CSS v4 es una actualización importante que vale la pena adoptar para nuevos proyectos y planificar los existentes. La pila de interfaz de ECOSIRE ejecuta Tailwind CSS v4.1 en producción en una aplicación Next.js 16 de 249 páginas con un sistema de diseño integral.

¿Necesita ayuda con una migración de Tailwind v4 o desea un sistema de diseño creado desde cero? Explore nuestros servicios de ingeniería frontend para ver cómo podemos ayudarle.