Minitutorial: Tailwind CSS v4 con Astro y Next.js

Guía complementaria para el Curso de TailwindCSS de Platzi, que muestra la versión 3 mientras que la versión actual es la 4.

Introducción

Si estás siguiendo el Curso de TailwindCSS de Platzi, habrás notado que algunas partes no coinciden con lo que obtienes al instalar Tailwind hoy. La razón es que el curso usa la versión 3 y la versión actual es la 4, que cambió la forma de instalar y configurar el framework. Las ideas de fondo no cambian: las clases de utilidad, el diseño responsivo, Flexbox y Grid funcionan igual. Lo que cambia es la instalación, la configuración y algunos nombres de utilidades.

Este minitutorial explica qué es diferente y cómo configurar Tailwind v4 en Astro y en Next.js, para que puedas seguir las lecciones sin quedarte atascado.

La idea principal: configuración desde CSS

La versión 4 sigue un enfoque llamado CSS-first. En la versión 3, la personalización vivía en un archivo de JavaScript llamado tailwind.config.js. En la versión 4 ese archivo ya no es necesario, porque la configuración se escribe directamente en tu archivo CSS. Tampoco necesitas indicar en qué archivos buscar clases, porque Tailwind los detecta automáticamente.

Instalación en Astro

En la versión 3, el curso usa la integración @astrojs/tailwind (o el comando npx astro add tailwind). En la versión 4 se usa directamente el plugin de Vite que ofrece Tailwind.

Primero, instala los paquetes:

npm install tailwindcss @tailwindcss/vite

Luego, registra el plugin en astro.config.mjs:

import { defineConfig } from "astro/config";
import tailwindcss from "@tailwindcss/vite";

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

Después, crea el archivo src/styles/global.css con una sola línea:

@import "tailwindcss";

Esa línea reemplaza las tres directivas de la versión 3 (@tailwind base, @tailwind components y @tailwind utilities).

Por último, importa el CSS en tu layout, por ejemplo en src/layouts/Layout.astro:

---
import "../styles/global.css";
---
<html lang="es">
  <body>
    <slot />
  </body>
</html>

Con esto ya puedes usar clases como bg-slate-900, text-white o md:flex en cualquier componente o página de Astro.

Personalización con @theme

En la versión 3, los colores, fuentes y breakpoints propios se agregaban dentro de theme.extend en tailwind.config.js. En la versión 4 se declaran dentro de un bloque @theme en tu CSS:

@import "tailwindcss";

@theme {
  --color-brand: #ff5a1f;
  --color-brand-dark: #c2410c;
  --font-display: "Poppins", sans-serif;
  --breakpoint-3xl: 120rem;
}

Cada variable genera sus utilidades de forma automática. Por ejemplo, --color-brand te permite usar bg-brand, text-brand y border-brand. El prefijo del nombre determina qué tipo de utilidad se crea: --color-* para colores, --font-* para familias tipográficas y --breakpoint-* para puntos de quiebre responsivos. Además, todas estas variables quedan disponibles como variables CSS normales, así que puedes usarlas con var(--color-brand) en tu propio CSS.

Plugins: forms, typography y aspect-ratio

En la versión 3, los plugins se agregaban en el arreglo plugins del archivo de configuración. En la versión 4 se declaran en el CSS con la directiva @plugin.

Instala los paquetes que necesites:

npm install @tailwindcss/typography @tailwindcss/forms

Y decláralos en tu CSS:

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

Con el plugin de typography ya puedes usar la clase prose, que se ve en la lección 17 del curso. Sobre el plugin de aspect-ratio de la lección 16: ya no hace falta instalarlo, porque las utilidades aspect-video, aspect-square y aspect-[4/3] vienen incluidas en el núcleo de Tailwind.

Detección automática de archivos

La versión 3 exigía una propiedad content con la lista de archivos donde buscar clases. La versión 4 los detecta sola y respeta tu archivo .gitignore. Solo necesitas intervenir si quieres que Tailwind escanee algo que normalmente ignora, como una librería dentro de node_modules. Para eso se usa @source:

@source "../node_modules/mi-libreria/dist";

Instalación en Next.js

Next.js usa PostCSS en lugar de Vite, por lo que cambia el paquete de integración.

npm install tailwindcss @tailwindcss/postcss postcss

Crea o edita postcss.config.mjs:

const config = {
  plugins: {
    "@tailwindcss/postcss": {},
  },
};

export default config;

Y en tu archivo global de estilos, normalmente app/globals.css, agrega:

@import "tailwindcss";

En la versión 4 ya no necesitas instalar autoprefixer ni postcss-import, porque Tailwind los incluye internamente. La personalización con @theme y @plugin funciona exactamente igual que en Astro, ya que es CSS puro.

Modo watch con el CLI (lecciones 3 y 4)

Si sigues las lecciones donde se usa Node y el modo watch sin ningún framework, el CLI ahora vive en un paquete aparte llamado @tailwindcss/cli:

npm install tailwindcss @tailwindcss/cli
npx @tailwindcss/cli -i ./src/input.css -o ./dist/output.css --watch

El archivo input.css solo necesita contener @import "tailwindcss";.

Equivalencias entre la versión 3 y la versión 4

Como referencia rápida, esto es lo que en el curso verás de una forma y en la versión 4 se escribe de otra:

• Las tres directivas @tailwind base, @tailwind components y @tailwind utilities se reemplazan por @import "tailwindcss";.
• La personalización en theme.extend de tailwind.config.js pasa a un bloque @theme en el CSS.
• El arreglo plugins con require(...) pasa a ser una directiva @plugin en el CSS.
• La propiedad content desaparece gracias a la detección automática, y @source cubre los casos especiales.
• La integración @astrojs/tailwind se reemplaza por el plugin @tailwindcss/vite.
• En proyectos con PostCSS, el plugin tailwindcss junto con autoprefixer se reemplaza por @tailwindcss/postcss.
• Para el CLI, el comando de la versión 3 pasa a ejecutarse desde @tailwindcss/cli.

Otros cambios que conviene conocer

Algunas utilidades cambiaron de nombre para que la escala sea más consistente. Si copias código del curso y notas que el resultado visual es distinto, revisa esta lista:

• shadow-sm ahora es shadow-xs, y shadow ahora es shadow-sm.
• rounded ahora es rounded-sm.
• blur ahora es blur-sm.
• outline-none ahora es outline-hidden.
• Las utilidades de opacidad como bg-opacity-50 desaparecieron; se usa la sintaxis con barra, por ejemplo bg-black/50.

Otro cambio importante es el color de borde por defecto. En la versión 3, la clase border usaba un gris claro. En la versión 4 usa currentColor, es decir, el color del texto. Por eso conviene indicar siempre el color del borde de forma explícita, por ejemplo border border-gray-200.

Finalmente, la versión 4 está pensada para navegadores modernos, con soporte a partir de Safari 16.4, Chrome 111 y Firefox 128. Para un entorno de desarrollo actual no representa ningún problema.

Migrar un proyecto existente

Si tienes un proyecto hecho con la versión 3 y quieres actualizarlo, Tailwind ofrece una herramienta oficial que automatiza la mayor parte del trabajo:

npx @tailwindcss/upgrade

Si por algún motivo necesitas conservar un archivo tailwind.config.js, puedes cargarlo desde el CSS con la directiva @config, aunque lo recomendado es migrar la configuración al CSS.

Cómo aprovechar el curso

Mi recomendación es seguir las lecciones para entender los conceptos, que siguen vigentes: clases de utilidad, tipografía, cajas, colores, breakpoints, Flexbox y Grid. Al mismo tiempo, aplica en tu proyecto la configuración de la versión 4 descrita en este documento. Las lecciones 14 a 18, que tratan sobre la integración con Astro, la personalización, los plugins y Next.js, son las que más se ven afectadas, así que ahí es donde conviene tener esta guía a la mano.