Skip to main content

🚀 Advertencias y Consideraciones al Actualizar a Tailwind CSS v4

Este documento cubre la instalación y configuración de Tailwind CSS v4 en un proyecto React + Vite con las siguientes versiones:

  • Node.js: v20.9.0
  • Vite: create-vite@6.3.1
  • Tailwind CSS: v4
  • React.js: v19.0.0

📌 Uso de la Herramienta de Actualización​

Para facilitar la migración de Tailwind CSS v3 a v4, Tailwind ha desarrollado una herramienta de actualización que automatiza gran parte del proceso.

Cómo ejecutar la herramienta de actualización​

Ejecuta el siguiente comando en la terminal:

npx @tailwindcss/upgrade

🔹 ¿Qué hace la herramienta de actualización?

  • Actualiza las dependencias de Tailwind en el proyecto.
  • Migra el archivo de configuración de Tailwind a CSS.
  • Ajusta automáticamente las plantillas para reflejar cambios en las clases.

⚠ Requisitos previos:

  • Node.js 20 o superior es obligatorio para ejecutar la herramienta. Asegúrate de actualizar tu entorno antes de usarla.

📌 Recomendaciones al actualizar:

  1. Ejecuta la actualización en una nueva rama (git checkout -b tailwind-v4).
  2. Revisa cuidadosamente los cambios (git diff) antes de hacer merge en tu rama principal.
  3. Prueba en el navegador para asegurarte de que todo funciona correctamente.
  4. Consulta la lista de breaking changes de v4 en la documentación oficial.

⚠ Eliminación de Importaciones Anteriores​

En Tailwind CSS v3, las reglas de importación requerían tres líneas:

@tailwind base;
@tailwind components;
@tailwind utilities;

En Tailwind v4, ahora solo se requiere una única importación:

@import "tailwindcss";

🔹 Beneficio: Esto simplifica la configuración y mejora el rendimiento.

🔄 Clases Renombradas en Tailwind CSS v4​

Algunas clases han sido renombradas en Tailwind v4 para mantener consistencia y claridad. Si usas alguna de estas clases en tu código, deberás actualizarlas.

V3 (anterior)V4 (nuevo)
shadow-smshadow-xs
shadowshadow-sm
drop-shadow-smdrop-shadow-xs
drop-shadowdrop-shadow-sm
blur-smblur-xs
blurblur-sm
backdrop-blur-smbackdrop-blur-xs
backdrop-blurbackdrop-blur-sm
rounded-smrounded-xs
roundedrounded-sm
outline-noneoutline-hidden
ringring-3

📌 Recomendación: Usa la herramienta de actualización npx @tailwindcss/upgrade para hacer estos cambios automáticamente en tu código.

🎨 Cómo Agregar Estilos Personalizados en Tailwind v4​

En Tailwind CSS v4, se recomienda utilizar @theme para definir estilos personalizados.

Ejemplo de configuración de colores y breakpoints:

@theme {
  --color-primary: #050816;
  --color-secondary: #aaa6c3;
  --color-tertiary: #151030;
  --color-black-100: #100d25;
  --color-black-200: #090325;
  --color-white-100: #f3f3f3;
  --breakpoint-xs: 450px;
}

🔹 Beneficio: Permite definir variables CSS reutilizables y mantener una estructura organizada.

⚠ Nota: Tailwind v4 migra la configuración de estilos a CSS en lugar de JavaScript (tailwind.config.js). Asegúrate de migrar tus estilos personalizados de manera adecuada.

📝 Resumen de Cambios Clave en Tailwind v4​

✅ Herramienta de actualización disponible → npx @tailwindcss/upgrade
✅ Importaciones simplificadas → @import "tailwindcss";
✅ Clases renombradas para mayor coherencia
✅ Estilos personalizados ahora usan @theme en CSS

🚀 Conclusión​

Tailwind CSS v4 optimiza y simplifica la configuración, pero requiere actualizar las clases, la forma de importar estilos y la gestión de estilos personalizados. Utiliza la herramienta de actualización y revisa bien los cambios en tu código para evitar problemas.

📌 Consulta la guía oficial de migración aquí → Upgrade Guide

¡Ahora estás listo para migrar a Tailwind v4 sin problemas! 🚀🎨