Cómo configurar Tailwind CSS v4 en Next.js desde cero

Tailwind CSS v4 cambió bastante respecto a v3. Si vienes del archivo tailwind.config.js y los colores definidos en JavaScript, el salto puede confundir al principio. Pero una vez entiendes la nueva forma de trabajar, es más limpia y más potente.

Esta guía cubre la instalación real en un proyecto Next.js con App Router y TypeScript. Sin atajos.

Instalación base

El setup moderno usa @tailwindcss/postcss. El flujo es:

• npm install tailwindcss @tailwindcss/postcss como devDependencies.
• Crear un postcss.config.mjs con el plugin de Tailwind CSS.
• Importar Tailwind en tu globals.css con @import "tailwindcss";.

Eso es todo. No hay tailwind.config.js. La configuración ahora vive en CSS.

@theme: tu sistema de diseño en CSS

En v4, el bloque @theme reemplaza al antiguo theme.extend de JavaScript. Aquí defines fuentes, radios, colores y cualquier token de diseño:

``css @theme { --font-sans: 'Inter', sans-serif; --radius-sm: 4px; --radius-md: 8px; } ``

La ventaja: todo tu sistema de diseño está en un solo archivo CSS, sin saltar entre JS y CSS. Es más legible y más fácil de mantener.

Variables CSS para temas

Para dark/light mode, la estrategia que mejor funciona es definir variables CSS en :root y .dark, y usar var() en tus clases. Tailwind v4 las reconoce como tokens del tema si las declaras en @theme.

El patrón que uso en vruz.dev: :root define la paleta light, .dark la sobreescribe, y los componentes solo referencian var(--color-background), var(--color-foreground), etc. Un solo punto de verdad para cada color.

@layer base vs @layer components

Tailwind v4 mantiene los layers pero con reglas más estrictas. @layer base es para resets y defaults globales. @layer components para clases reutilizables como .btn o .card. No mezcles: un estilo base en components genera conflictos de especificidad.

@custom-variant para dark mode

Si usas class-based dark mode (lo recomiendo), necesitas declarar: @custom-variant dark (&:is(.dark, .dark *));. Esto le dice a Tailwind que dark: debe activarse cuando el elemento o sus ancestros tengan la clase .dark.

@utility para clases custom

¿Necesitas una clase como .container-page? En v4 la registras con @utility container-page { ... }. Esto la integra en el sistema de utilidades y la hace disponible con variants como md:container-page.

Errores comunes que te vas a encontrar

• Importar tailwind.config.js: no existe en v4. Si tu template lo trae, bórralo.
• Usar @apply con clases inexistentes: verifica que las clases que aplicas están registradas.
• Olvidar @custom-variant dark: sin esta declaración, dark: no funciona con el approach de clase.
• Mezclar v3 y v4 docs: la documentación de v3 sigue indexada en Google. Verifica que estás leyendo la correcta.

Conclusión

Tailwind CSS v4 es un salto de calidad en cómo defines sistemas de diseño. La configuración en CSS puro es más natural, el sistema de tokens es más potente y la integración con Next.js es directa. Si empiezas un proyecto hoy, empieza con v4. El coste de migración desde v3 es moderado, pero el beneficio a largo plazo merece la inversión.