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;
  --color-destructive: #ef4444;
  --color-muted: #f1f5f9;
  --color-border: #e2e8f0;
 
  /* Espaciado */
  --spacing-18: 4.5rem;
  --spacing-128: 32rem;
 
  /* Tipografía */
  --font-family-sans: "Inter", ui-sans-serif, system-ui, sans-serif;
  --font-family-mono: "JetBrains Mono", ui-monospace, monospace;
 
  /* Radio del borde */
  --radius-DEFAULT: 0.5rem;
  --radius-lg: 0.75rem;
 
  /* Sombras */
  --shadow-soft: 0 2px 8px rgb(0 0 0 / 0.08);
 
  /* Animaciones */
  --animate-fade-in: fade-in 0.3s ease-out;
}
 
@keyframes fade-in {
  from { opacity: 0; transform: translateY(-4px); }
  to { opacity: 1; transform: translateY(0); }
}
 
/* Utilidades personalizadas */
@utility container-narrow {
  max-width: 42rem;
  margin-inline: auto;
  padding-inline: 1rem;
}
 
/* Variante personalizada */
@variant hocus (&:hover, &:focus-visible);
 
/* Overrides de capas */
@layer base {
  html {
    font-family: var(--font-family-sans);
    color: var(--color-foreground, #0f172a);
  }
 
  h1, h2, h3 {
    font-family: var(--font-family-heading, var(--font-family-sans));
  }
}

// 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>
      <button className="mt-6 rounded-lg bg-primary px-6 py-3 text-primary-foreground shadow-soft hocus:bg-primary-dark">
        Comenzar
      </button>
    </section>
  );
}

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

Alternativa	Cuándo usarla	Cuándo no usarla
Tailwind v3	Proyecto legacy que no está listo para migrar	Al iniciar un proyecto nuevo (v4 es más simple)
CSS Modules	Necesitas CSS con alcance local sin clases de utilidad	Quieres prototipado rápido con utilidades
Vanilla Extract	Quieres CSS-in-TS type-safe con cero runtime	Prefieres desarrollo utility-first
UnoCSS	Quieres un motor de utilidades ultrarrápido y configurable	Quieres el ecosistema y la comunidad de Tailwind

FAQs

¿Qué importación única reemplaza las tres directivas @tailwind de v3?

@import "tailwindcss" reemplaza @tailwind base, @tailwind components y @tailwind utilities.

¿Dónde vive toda la configuración en Tailwind CSS v4?

En tu archivo CSS dentro de bloques @theme { }. No hay tailwind.config.js por defecto.

¿Cómo mapea la convención de nombres de @theme a las clases de utilidad?

--color-brand se convierte en text-brand, bg-brand, border-brand
--spacing-18 se convierte en p-18, m-18, gap-18
--font-family-sans se convierte en font-sans

¿Cuándo necesitas usar @source en v4?

Solo cuando la detección automática de Tailwind no encuentra tus archivos. Agrega @source "../path/**/*.tsx" para ubicaciones de archivos no estándar.

¿Cómo migras un proyecto v3 existente a v4?

Ejecuta npx @tailwindcss/upgrade. Convierte los valores de tu tailwind.config.js en bloques CSS @theme.

¿Cómo eliminas todos los colores por defecto y defines solo los tuyos?

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

¿Cuál es el nombre correcto del plugin de PostCSS para v4?

@tailwindcss/postcss, no tailwindcss. Usar el nombre antiguo fallará silenciosamente.

Trampa: ¿Por qué --brand-color no genera ninguna clase de utilidad?

Los valores de tema deben seguir el patrón --category-name. --color-brand funciona, pero --brand-color no coincide con ninguna categoría de utilidad.

Trampa: Agregaste valores @theme pero aún ves un tailwind.config.js — ¿entrarán en conflicto?

Pueden hacerlo. Usa @config "./tailwind.config.js" en CSS solo cuando necesites plugins basados en JS. Mueve todos los valores de tema a @theme para evitar conflictos.

¿Cómo puedes verificar tipos del uso de tokens de tema en TypeScript?

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

Tailwind en sí es solo CSS, pero puedes crear un mapa de búsqueda tipado para consistencia.

¿Cómo defines una utilidad personalizada y una variante personalizada en v4?

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

¿Puedes dividir @theme en varios archivos CSS?

Sí. Importa un archivo de tema separado después de @import "tailwindcss":

@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

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;
  --color-destructive: #ef4444;
  --color-muted: #f1f5f9;
  --color-border: #e2e8f0;
 
  /* Espaciado */
  --spacing-18: 4.5rem;
  --spacing-128: 32rem;
 
  /* Tipografía */
  --font-family-sans: "Inter", ui-sans-serif, system-ui, sans-serif;
  --font-family-mono: "JetBrains Mono", ui-monospace, monospace;
 
  /* Radio del borde */
  --radius-DEFAULT: 0.5rem;
  --radius-lg: 0.75rem;
 
  /* Sombras */
  --shadow-soft: 0 2px 8px rgb(0 0 0 / 0.08);
 
  /* Animaciones */
  --animate-fade-in: fade-in 0.3s ease-out;
}
 
@keyframes fade-in {
  from { opacity: 0; transform: translateY(-4px); }
  to { opacity: 1; transform: translateY(0); }
}
 
/* Utilidades personalizadas */
@utility container-narrow {
  max-width: 42rem;
  margin-inline: auto;
  padding-inline: 1rem;
}
 
/* Variante personalizada */
@variant hocus (&:hover, &:focus-visible);
 
/* Overrides de capas */
@layer base {
  html {
    font-family: var(--font-family-sans);
    color: var(--color-foreground, #0f172a);
  }
 
  h1, h2, h3 {
    font-family: var(--font-family-heading, var(--font-family-sans));
  }
}

// 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>
      <button className="mt-6 rounded-lg bg-primary px-6 py-3 text-primary-foreground shadow-soft hocus:bg-primary-dark">
        Comenzar
      </button>
    </section>
  );
}

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

Alternativa	Cuándo usarla	Cuándo no usarla
Tailwind v3	Proyecto legacy que no está listo para migrar	Al iniciar un proyecto nuevo (v4 es más simple)
CSS Modules	Necesitas CSS con alcance local sin clases de utilidad	Quieres prototipado rápido con utilidades
Vanilla Extract	Quieres CSS-in-TS type-safe con cero runtime	Prefieres desarrollo utility-first
UnoCSS	Quieres un motor de utilidades ultrarrápido y configurable	Quieres el ecosistema y la comunidad de Tailwind

FAQs

¿Qué importación única reemplaza las tres directivas @tailwind de v3?

@import "tailwindcss" reemplaza @tailwind base, @tailwind components y @tailwind utilities.

¿Dónde vive toda la configuración en Tailwind CSS v4?

En tu archivo CSS dentro de bloques @theme { }. No hay tailwind.config.js por defecto.

¿Cómo mapea la convención de nombres de @theme a las clases de utilidad?

--color-brand se convierte en text-brand, bg-brand, border-brand
--spacing-18 se convierte en p-18, m-18, gap-18
--font-family-sans se convierte en font-sans

¿Cuándo necesitas usar @source en v4?

Solo cuando la detección automática de Tailwind no encuentra tus archivos. Agrega @source "../path/**/*.tsx" para ubicaciones de archivos no estándar.

¿Cómo migras un proyecto v3 existente a v4?

Ejecuta npx @tailwindcss/upgrade. Convierte los valores de tu tailwind.config.js en bloques CSS @theme.

¿Cómo eliminas todos los colores por defecto y defines solo los tuyos?

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

¿Cuál es el nombre correcto del plugin de PostCSS para v4?

@tailwindcss/postcss, no tailwindcss. Usar el nombre antiguo fallará silenciosamente.

Trampa: ¿Por qué --brand-color no genera ninguna clase de utilidad?

Los valores de tema deben seguir el patrón --category-name. --color-brand funciona, pero --brand-color no coincide con ninguna categoría de utilidad.

Trampa: Agregaste valores @theme pero aún ves un tailwind.config.js — ¿entrarán en conflicto?

Pueden hacerlo. Usa @config "./tailwind.config.js" en CSS solo cuando necesites plugins basados en JS. Mueve todos los valores de tema a @theme para evitar conflictos.

¿Cómo puedes verificar tipos del uso de tokens de tema en TypeScript?

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

Tailwind en sí es solo CSS, pero puedes crear un mapa de búsqueda tipado para consistencia.

¿Cómo defines una utilidad personalizada y una variante personalizada en v4?

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

¿Puedes dividir @theme en varios archivos CSS?

Sí. Importa un archivo de tema separado después de @import "tailwindcss":

@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

Configuración de Tailwind CSS v4

Buscar en la documentación

Configuración de Tailwind CSS v4