---

name: setup-tailwind-typescript description: > Configurar Tailwind CSS con TypeScript en un proyecto Next.js o React. Cubre la instalación, configuración, extensiones de tema personalizadas, patrones de componentes y utilidades de estilos con seguridad de tipos. Úsalo al añadir Tailwind CSS a un proyecto TypeScript existente, al personalizar el tema de Tailwind para el sistema de diseño de un proyecto, al configurar patrones de estilos de componentes con seguridad de tipos, o al configurar plugins y extensiones de Tailwind. locale: es source_locale: en source_commit: 6f65f316 translator: claude-opus-4-6 translation_date: 2026-03-16 license: MIT allowed-tools: Read Write Edit Bash Grep Glob metadata: author: Philipp Thoss version: "1.0" domain: web-dev complexity: basic language: TypeScript tags: tailwind, typescript, css, styling, configuration

Set Up Tailwind CSS with TypeScript

Configurar Tailwind CSS en un proyecto TypeScript con tema personalizado, utilidades y patrones con seguridad de tipos.

Cuándo Usar

• Al añadir Tailwind CSS a un proyecto TypeScript existente
• Al personalizar el tema de Tailwind para el sistema de diseño de un proyecto
• Al configurar patrones de estilos de componentes con seguridad de tipos
• Al configurar plugins y extensiones de Tailwind

Entradas

• Requerido: Proyecto TypeScript (Next.js, Vite o React independiente)
• Opcional: Tokens del sistema de diseño (colores, espaciado, fuentes)
• Opcional: Plugins de Tailwind a incluir

Procedimiento

Paso 1: Instalar Tailwind CSS

npm install -D tailwindcss @tailwindcss/postcss postcss

Para Next.js (si no está incluido ya):

npm install -D tailwindcss postcss autoprefixer
npx tailwindcss init -p

Esperado: tailwindcss, postcss y autoprefixer instalados como dependencias de desarrollo. Para Next.js, tailwind.config.ts y postcss.config.js son generados por npx tailwindcss init -p.

En caso de fallo: Si npx tailwindcss init falla, instala Tailwind primero con npm install -D tailwindcss y vuelve a intentarlo. Si usas un monorepo, ejecuta el comando desde el directorio raíz de la aplicación, no desde la raíz del workspace.

Paso 2: Configurar tailwind.config.ts

import type { Config } from "tailwindcss";

const config: Config = {
  content: [
    "./src/pages/**/*.{js,ts,jsx,tsx,mdx}",
    "./src/components/**/*.{js,ts,jsx,tsx,mdx}",
    "./src/app/**/*.{js,ts,jsx,tsx,mdx}",
  ],
  theme: {
    extend: {
      colors: {
        primary: {
          50: "#eff6ff",
          100: "#dbeafe",
          500: "#3b82f6",
          600: "#2563eb",
          700: "#1d4ed8",
          900: "#1e3a5f",
        },
        secondary: {
          500: "#6366f1",
          600: "#4f46e5",
        },
      },
      fontFamily: {
        sans: ["Inter", "system-ui", "sans-serif"],
        mono: ["JetBrains Mono", "monospace"],
      },
      spacing: {
        "18": "4.5rem",
        "88": "22rem",
      },
    },
  },
  plugins: [],
};

export default config;

Esperado: tailwind.config.ts tiene un array content que coincide con las ubicaciones de archivos del proyecto, colores y fuentes personalizados bajo theme.extend, y tipado TypeScript correcto con la importación de Config.

En caso de fallo: Si las clases personalizadas no se renderizan, verifica que las rutas de content coincidan con tu estructura de directorios real. Las rutas son patrones glob relativos a la raíz del proyecto. Las rutas faltantes significan que Tailwind no escaneará esos archivos para detectar el uso de clases.

Paso 3: Configurar los Estilos Globales

Edita src/app/globals.css:

@tailwind base;
@tailwind components;
@tailwind utilities;

@layer base {
  html {
    @apply antialiased;
  }

  body {
    @apply bg-white text-gray-900 dark:bg-gray-950 dark:text-gray-100;
  }
}

@layer components {
  .btn-primary {
    @apply bg-primary-600 text-white px-4 py-2 rounded-lg
           hover:bg-primary-700 focus:outline-none focus:ring-2
           focus:ring-primary-500 focus:ring-offset-2
           transition-colors duration-200;
  }
}

Esperado: globals.css contiene las tres directivas de Tailwind (@tailwind base, @tailwind components, @tailwind utilities) más cualquier estilo personalizado de las capas base y de componentes. El archivo está importado en el layout raíz.

En caso de fallo: Si los estilos no se aplican, verifica que globals.css esté importado en layout.tsx (o _app.tsx para Pages Router). Comprueba que las directivas de Tailwind estén presentes y no estén comentadas.

Paso 4: Crear Helpers de Utilidad con Seguridad de Tipos

Crea src/lib/cn.ts:

import { type ClassValue, clsx } from "clsx";
import { twMerge } from "tailwind-merge";

export function cn(...inputs: ClassValue[]) {
  return twMerge(clsx(inputs));
}

Instala las dependencias:

npm install clsx tailwind-merge

Uso en componentes:

import { cn } from "@/lib/cn";

interface ButtonProps extends React.ButtonHTMLAttributes<HTMLButtonElement> {
  variant?: "primary" | "secondary" | "outline";
}

export function Button({ className, variant = "primary", ...props }: ButtonProps) {
  return (
    <button
      className={cn(
        "px-4 py-2 rounded-lg font-medium transition-colors",
        variant === "primary" && "bg-primary-600 text-white hover:bg-primary-700",
        variant === "secondary" && "bg-secondary-500 text-white hover:bg-secondary-600",
        variant === "outline" && "border border-gray-300 hover:bg-gray-50",
        className
      )}
      {...props}
    />
  );
}

Esperado: src/lib/cn.ts exporta una función cn(). clsx y tailwind-merge están instalados como dependencias. Los componentes usan cn() para combinar nombres de clases sin conflictos.

En caso de fallo: Si clsx o tailwind-merge no se encuentran, ejecuta npm install clsx tailwind-merge. Si TypeScript reporta errores de tipo en cn.ts, verifica que el tipo ClassValue esté importado desde clsx.

Paso 5: Añadir Soporte para Modo Oscuro

Actualiza tailwind.config.ts:

const config: Config = {
  darkMode: "class", // o "media" para la preferencia del sistema
  // ... resto de la configuración
};

Implementación del interruptor de tema:

"use client";
import { useEffect, useState } from "react";

export function ThemeToggle() {
  const [dark, setDark] = useState(false);

  useEffect(() => {
    document.documentElement.classList.toggle("dark", dark);
  }, [dark]);

  return (
    <button onClick={() => setDark(!dark)}>
      {dark ? "Light" : "Dark"} Mode
    </button>
  );
}

Esperado: El modo oscuro se activa correctamente entre temas claro y oscuro. La clase dark se aplica al elemento <html>, y las clases de utilidad con prefijo dark: responden de manera correspondiente.

En caso de fallo: Si el modo oscuro no se activa, verifica que darkMode: "class" esté configurado en tailwind.config.ts. Asegúrate de que la clase dark se alterna en el elemento <html> (no en <body>). Para el modo de preferencia del sistema, usa darkMode: "media" en su lugar.

Paso 6: Añadir Plugins (Opcional)

npm install -D @tailwindcss/typography @tailwindcss/forms

// tailwind.config.ts
import typography from "@tailwindcss/typography";
import forms from "@tailwindcss/forms";

const config: Config = {
  // ...
  plugins: [typography, forms],
};

Esperado: Los plugins instalados como dependencias de desarrollo y registrados en el array plugins de tailwind.config.ts. Las clases proporcionadas por los plugins (p.ej., prose de typography, elementos de formulario estilizados de forms) están disponibles en los componentes.

En caso de fallo: Si las clases del plugin no se renderizan, verifica que el plugin esté instalado (npm ls @tailwindcss/typography) y añadido al array plugins. Reinicia el servidor de desarrollo después de cambios en la configuración.

Validación

• Las clases de Tailwind se renderizan correctamente en el navegador
• Los valores de tema personalizados (colores, fuentes, espaciado) funcionan
• La utilidad cn() combina clases sin conflictos
• El modo oscuro se activa correctamente
• TypeScript no muestra errores en la configuración ni en los componentes
• La compilación de producción elimina los estilos no utilizados

Errores Comunes

• Rutas de contenido faltantes: Si las clases no se renderizan, verifica que el array content de la configuración coincida con las ubicaciones de tus archivos
• Conflictos de clases: Usa tailwind-merge (a través de cn()) para prevenir clases de utilidad conflictivas
• Valores personalizados que no funcionan: Asegúrate de que los valores personalizados estén bajo extend (para añadir) y no en la raíz del tema (que reemplaza los valores predeterminados)
• Modo oscuro sin activar: Verifica la configuración de darkMode y que la clase dark esté en <html> y no en <body>

Habilidades Relacionadas

• scaffold-nextjs-app — configuración del proyecto antes de la configuración de Tailwind
• deploy-to-vercel — desplegar la aplicación con estilos