Migrando a Tailwind 4 en Next.js 15

Lanzamiento de TailwindCSS 4.0

El día de ayer (22 de enero del 2025) salió oficialmente la versión 4.0 de TailwindCSS. Esta versión trae consigo varias mejoras, una de ellas es que ya no será necesario tener un archivo de configuración tailwind.config.js. Si bien este puede seguir existiendo, lo mejor es aprovechar la nueva integración directamente en el archivo CSS principal.

Contexto de la migración

Este artículo no hablará de todos los cambios en Tailwind, sino que se centrará en algunos problemas que encontré al migrar un proyecto que había iniciado recientemente. Pensé que sería una buena idea probar la nueva versión de Tailwind, así que decidí actualizar directamente.

La página oficial ya ofrece una guía bastante completa para realizar la migración. Incluye un script para hacer el upgrade automáticamente, y en mi caso funcionó bastante bien, salvo algunos pequeños inconvenientes.

Configuración del proyecto

En mi proyecto utilizo las siguientes herramientas:

• Tailwind Typography
• Next Themes
• Fuentes de Google directamente con next/font/google

Problemas encontrados tras la migración

Una vez que ejecuté el script de migración y corrí el proyecto, casi todo funcionó correctamente, excepto dos aspectos:

1. Mis colores personalizados definidos en el archivo de configuración de Tailwind.
2. Las fuentes definidas en el layout de Next.js.

En los componentes donde definía los colores y las propiedades de manera explícita, todo funcionaba bien. Sin embargo, suelo agregar clases generales en el body para el color de fondo y las letras del tema claro y oscuro, y esto era lo que fallaba.

El script de migración trasladó toda mi configuración de Tailwind al archivo CSS y actualizó los nombres de las clases que debían cambiar, incluyendo el plugin de Tailwind Typography. Incluso las clases personalizadas que creé para expandir Tailwind funcionaban correctamente. Sin embargo, ignoraba mis directrices generales.

Solución

El problema estaba en que mi archivo CSS sobrescribía los estilos del body.

Esta clase se agrega por defecto al crear un proyecto en Next.js, y olvidé quitarla. Normalmente, con Tailwind puedes sobrescribir esto, pero no había revisado el archivo CSS.

Además, mi archivo CSS contenía variables que no utilizaba:

Aunque estas variables no afectaron mi flujo porque todos mis estilos están definidos con Tailwind, es buena práctica eliminarlas si no se van a usar.

Problema con las fuentes

Mis fuentes no se respetaban en ningún lugar donde utilizaba la clase generada por Tailwind. Esto se debía a que en Next.js declaraba las variables de fuentes con un nombre diferente al utilizado en el archivo de configuración de Tailwind.

En esta versión de Tailwind, que trabaja a nivel CSS, es necesario ser más explícito y usar el mismo nombre tanto en el archivo CSS como en el layout de Next.js. De lo contrario, el navegador no encontrará la variable definida.

Conclusión

Migrar a TailwindCSS 4.0 ofrece muchas ventajas, pero también requiere atención a detalles que muchas veces se dejan de lado, ya que Tailwind se encargaba de ellos. Revisar y ajustar los estilos generales y las variables puede evitar problemas comunes. Espero que esta experiencia te sea útil si decides dar el salto a esta nueva versión.

Foto de portada de: Luis Quintero

Source: View source