Configuración de Tailwind CSS v4

Instala Tailwind CSS v4, configúralo con el enfoque CSS-first, configura @theme y usa @import "tailwindcss".

Receta

Tarjeta de receta de referencia rápida — lista para copiar y pegar.

# Instala Tailwind CSS v4 con Next.js
npm install tailwindcss @tailwindcss/postcss postcss
 
# O con Vite
npm install tailwindcss @tailwindcss/vite

/* app/globals.css — la ÚNICA configuración que necesitas */
@import "tailwindcss";
 
/* Valores de tema personalizados */
@theme {
  --color-brand: #3b82f6;
  --color-brand-dark: #1d4ed8;
  --font-family-heading: "Inter", sans-serif;
  --breakpoint-3xl: 1920px;
}

// postcss.config.mjs (Next.js)
export default {
  plugins: {
    "@tailwindcss/postcss": {},
  },
};

// vite.config.ts (Vite)
import tailwindcss from "@tailwindcss/vite";
import { defineConfig } from "vite";
 
export default defineConfig({
  plugins: [tailwindcss()],
});

Cuándo usarlo: Al inicio de cada proyecto nuevo que use Tailwind CSS v4 — la configuración es más simple que en v3, sin necesidad de tailwind.config.js.

Ejemplo funcional

/* app/globals.css — configuración completa del proyecto */
@import "tailwindcss";
 
/* Detección de fuentes — indica a Tailwind dónde están tus clases */
@source "../components/**/*.tsx";
@source "../lib/**/*.ts";
 
/* Tema personalizado */
@theme {
  /* Colores */
  --color-primary: #2563eb;
  --color-primary-foreground: #ffffff;
  --color-secondary: #64748b;

// Uso en componentes
export function Hero() {
  return (
    <section className="container-narrow animate-fade-in py-18">
      <h1 className="text-4xl font-bold text-primary">¡Hola!</h1>
      <p className="mt-4 text-secondary">Construye algo genial.</p>

Lo que demuestra esto:

• @import "tailwindcss" reemplaza las antiguas directivas @tailwind
• Bloque @theme para configuración CSS-first (sin archivo de configuración JS)
• @source para detección explícita de contenido
• Utilidades personalizadas con @utility
• Variantes personalizadas con @variant
• Valores de tema usados como clases de utilidad (text-primary, shadow-soft, etc.)

Análisis profundo

Cómo funciona

• Tailwind v4 es CSS-first — toda la configuración vive en tu archivo CSS, no en un config JS
• @import "tailwindcss" incluye todas las capas base, components y utilities de Tailwind
• @theme define propiedades personalizadas CSS que Tailwind convierte en clases de utilidad
• Convención de nombres: --color-* se convierte en text-*, bg-*, border-*; --spacing-* se convierte en p-*, m-*, gap-*
• @source indica a Tailwind dónde escanear nombres de clase (reemplaza content en la configuración de v3)
• Tailwind v4 detecta fuentes automáticamente en la mayoría de frameworks — @source solo es necesario para rutas no estándar
• El bloque @theme se compila a propiedades personalizadas CSS, lo que permite theming en tiempo de ejecución

Variaciones

Migrar desde la configuración de v3:

# Herramienta de migración automática
npx @tailwindcss/upgrade

/* colores de tailwind.config.js v3 → @theme v4 */
/* Antes (JS): colors: { brand: { 500: '#3b82f6' } } */
/* Después (CSS): */
@theme {
  --color-brand-500: #3b82f6;
}

Desactivar valores de tema por defecto:

@theme {
  /* Elimina todos los colores por defecto */
  --color-*: initial;
 
  /* Define solo tus colores */
  --color-primary: #2563eb;
  --color-gray-50: #f9fafb;
  --color-gray-900: #111827;
}

Múltiples archivos CSS:

/* styles/theme.css */
@theme {
  --color-brand: #3b82f6;
}
 
/* app/globals.css */
@import "tailwindcss";
@import "./styles/theme.css";

Notas de TypeScript

// Sin impacto en TypeScript — Tailwind es solo CSS
// Pero puedes tipar tus tokens de tema para consistencia:
const themeColors = {
  primary: "text-primary",
  secondary: "text-secondary",
  destructive: "text-destructive",
} as const;
 
type ThemeColor = keyof typeof themeColors;

Trampas

• No hay tailwind.config.js por defecto — v4 no lee un archivo de configuración JS. Solución: Toda la configuración va en CSS vía @theme. Si debes usar configuración JS (para plugins), usa @config "./tailwind.config.js" en tu CSS.

• @tailwind base/components/utilities se eliminó — v4 usa @import "tailwindcss" en su lugar. Solución: Reemplaza las tres directivas @tailwind con un solo @import.

• El plugin de PostCSS cambió — El plugin ahora es @tailwindcss/postcss, no tailwindcss. Solución: Actualiza tu configuración de PostCSS.

• Detección automática de contenido — v4 escanea tu proyecto automáticamente. Si las clases no se detectan, agrega rutas @source explícitas. Solución: Usa @source "../path/**/*.tsx" para ubicaciones de archivos no estándar.

• Nombres de propiedades personalizadas CSS — Los valores de @theme deben seguir el patrón --category-name para generar utilidades correctas. --color-brand se convierte en text-brand, pero --brand-color no.

Alternativas

FAQs

@theme {
  --color-*: initial;
  --color-primary: #2563eb;
}

const themeColors = {
  primary: "text-primary",
  secondary: "text-secondary",
} as const;
 
type ThemeColor = keyof typeof themeColors;

@utility container-narrow {
  max-width: 42rem;
  margin-inline: auto;
}
 
@variant hocus (&:hover, &:focus-visible);

@import "tailwindcss";
@import "./styles/theme.css";

Relacionado

• Ejemplos — 30 patrones comunes de utilidades Tailwind
• Ejemplos de grid — patrones de layout con flexbox y grid
• Utilidades — cheatsheet de clases de utilidad principales
• Modo oscuro — modo oscuro y theming
• Utilidades personalizadas — @utility, @variant, plugins
• Configuración de shadcn — integración shadcn + Tailwind