Configuración

Configuración en Tailwind 3

La configuración tradicional de Tailwind CSS versión 3 se basa en un sistema centralizado que utiliza el archivo tailwind.config.js como núcleo del proceso de personalización. Este enfoque ha sido el estándar durante años y establece las bases para comprender la evolución hacia las nuevas versiones.

El archivo tailwind.config.js

En Tailwind 3, toda la personalización del framework se gestiona a través de un archivo JavaScript de configuración ubicado en la raíz del proyecto. Este archivo actúa como el centro de control donde defines colores personalizados, breakpoints, espaciado y cualquier extensión del sistema de utilidades.

/** @type {import('tailwindcss').Config} */
module.exports = {
  content: ['./src/**/*.{html,js}'],
  theme: {
    extend: {
      colors: {
        'primary': '#3b82f6',
        'secondary': '#64748b'
      }
    }
  },
  plugins: []
}

La estructura del archivo sigue un patrón consistente donde cada sección tiene una responsabilidad específica. La propiedad content especifica qué archivos debe escanear Tailwind para detectar las clases utilizadas, mientras que theme permite personalizar el sistema de diseño.

Personalización del tema

El objeto theme representa el corazón de la personalización en Tailwind 3. Aquí defines los valores que estarán disponibles en tus clases de utilidad, desde colores hasta espaciado y tipografía.

module.exports = {
  theme: {
    colors: {
      transparent: 'transparent',
      current: 'currentColor',
      'white': '#ffffff',
      'black': '#000000',
      'gray': {
        50: '#f9fafb',
        100: '#f3f4f6',
        500: '#6b7280',
        900: '#111827'
      }
    },
    fontFamily: {
      'sans': ['Inter', 'system-ui'],
      'serif': ['Georgia', 'serif'],
      'mono': ['Fira Code', 'monospace']
    },
    spacing: {
      '72': '18rem',
      '84': '21rem',
      '96': '24rem'
    }
  }
}

La diferencia fundamental entre theme y theme.extend radica en el comportamiento de sustitución. Cuando defines valores directamente en theme, reemplazas completamente la configuración por defecto de Tailwind. En cambio, theme.extend permite agregar valores adicionales manteniendo los predeterminados.

Gestión del contenido y purga

La propiedad content en Tailwind 3 reemplaza la anterior configuración purge y especifica dónde buscar clases utilizadas para optimizar el CSS final. Esta configuración es crítica para el rendimiento, ya que determina qué clases se incluirán en la build de producción.

module.exports = {
  content: [
    './src/**/*.{html,js,ts,jsx,tsx}',
    './pages/**/*.{js,ts,jsx,tsx}',
    './components/**/*.{js,ts,jsx,tsx}'
  ],
  // ... resto de configuración
}

El sistema de detección funciona mediante análisis estático del código, buscando patrones que coincidan con las clases de Tailwind. Por esta razón, es importante evitar la construcción dinámica de nombres de clases, ya que el sistema podría no detectarlas correctamente.

Plugins y extensiones

El ecosistema de plugins de Tailwind 3 permite extender la funcionalidad base del framework mediante módulos especializados. Estos se integran directamente en la configuración y pueden agregar nuevas utilidades, componentes o modificar el comportamiento existente.

module.exports = {
  plugins: [
    require('@tailwindcss/forms'),
    require('@tailwindcss/typography'),
    function({ addUtilities }) {
      addUtilities({
        '.content-auto': {
          'content-visibility': 'auto'
        },
        '.content-hidden': {
          'content-visibility': 'hidden'
        }
      })
    }
  ]
}

Los plugins oficiales como @tailwindcss/forms y @tailwindcss/typography proporcionan estilos especializados para formularios y contenido tipográfico respectivamente. También puedes crear plugins personalizados utilizando las APIs internas de Tailwind para agregar utilidades específicas de tu proyecto.

Configuración de modo y variantes

Tailwind 3 introduce el concepto de modo JIT (Just-In-Time) como comportamiento predeterminado, generando únicamente las clases que realmente utilizas. Esta aproximación mejora significativamente los tiempos de compilación y permite utilizar valores arbitrarios directamente en las clases.

module.exports = {
  mode: 'jit', // Activado por defecto en v3
  theme: {
    extend: {
      screens: {
        'xs': '475px',
        '3xl': '1600px'
      }
    }
  }
}

Las variantes personalizadas también pueden definirse en la configuración, permitiendo crear modificadores específicos para estados o condiciones particulares de tu aplicación.

Esta aproximación basada en JavaScript para la configuración ha sido el estándar establecido en Tailwind 3, proporcionando flexibilidad y control granular sobre todos los aspectos del framework. Sin embargo, como veremos en la siguiente sección, Tailwind 4 introduce una metodología completamente diferente que simplifica y moderniza este proceso de configuración.

Configuración en Tailwind 4

La revolución más significativa de Tailwind 4 radica en su nuevo enfoque de configuración basado en CSS nativo. A diferencia del sistema tradicional que depende de archivos JavaScript, esta versión adopta una metodología CSS-first que simplifica drásticamente la personalización del framework.

El nuevo paradigma CSS-first

Tailwind 4 elimina la dependencia del archivo tailwind.config.js y traslada toda la configuración directamente al CSS. Este cambio fundamental permite una integración más natural con el flujo de trabajo de CSS y reduce la fricción entre la configuración y la aplicación de estilos.

@import "tailwindcss";

@config {
  --color-primary: #3b82f6;
  --color-secondary: #64748b;
  --font-sans: "Inter", system-ui, sans-serif;
  --spacing-18: 4.5rem;
}

Esta aproximación declarativa permite definir variables CSS personalizadas que Tailwind 4 utiliza automáticamente para generar las clases de utilidad correspondientes. El resultado es una configuración más intuitiva y alineada con los estándares web modernos.

Directivas de configuración

La directiva @config actúa como el núcleo del sistema de configuración en Tailwind 4. Dentro de este bloque, defines todas las personalizaciones utilizando la sintaxis de propiedades CSS personalizadas (custom properties).

@import "tailwindcss";

@config {
  /* Colores personalizados */
  --color-brand-50: #eff6ff;
  --color-brand-500: #3b82f6;
  --color-brand-900: #1e3a8a;
  
  /* Espaciado personalizado */
  --spacing-18: 4.5rem;
  --spacing-72: 18rem;
  
  /* Breakpoints responsivos */
  --breakpoint-xs: 475px;
  --breakpoint-3xl: 1600px;
}

Las variables CSS personalizadas siguen una nomenclatura específica que Tailwind 4 reconoce automáticamente. Por ejemplo, --color-primary-500 se convierte en la clase bg-primary-500 o text-primary-500, manteniendo la consistencia del sistema de utilidades.

Personalización de temas

La personalización del tema en Tailwind 4 se realiza mediante la directiva @theme, que permite definir tokens de diseño de forma más granular y organizada.

@import "tailwindcss";

@theme {
  --color-primary: #3b82f6;
  --color-secondary: #64748b;
  --color-success: #10b981;
  --color-warning: #f59e0b;
  --color-danger: #ef4444;
}

@config {
  --font-display: "Playfair Display", serif;
  --font-body: "Inter", system-ui, sans-serif;
}

Esta separación de responsabilidades entre @theme y @config permite una mejor organización del código CSS y facilita el mantenimiento de proyectos complejos.

Valores arbitrarios nativos

Una de las ventajas más destacadas de Tailwind 4 es su soporte mejorado para valores arbitrarios. Al trabajar directamente con CSS, el framework puede procesar valores personalizados de forma más eficiente y flexible.

@import "tailwindcss";

@config {
  --shadow-glow: 0 0 20px rgba(59, 130, 246, 0.5);
  --gradient-sunset: linear-gradient(45deg, #ff6b6b, #ffd93d);
}

<!-- Uso directo de las variables personalizadas -->
<div class="shadow-glow bg-gradient-sunset p-6">
  <h2 class="text-xl font-bold">Contenido personalizado</h2>
</div>

Los valores arbitrarios definidos en la configuración se integran perfectamente con el sistema de clases existente, eliminando la necesidad de CSS personalizado adicional en muchos casos.

Migración desde la configuración JavaScript

Para proyectos que migran desde Tailwind 3, el proceso de transición implica convertir la configuración JavaScript a la nueva sintaxis CSS. Esta migración, aunque requiere refactorización, resulta en un código más mantenible y performante.

/* Equivalente CSS de configuración JavaScript */
@import "tailwindcss";

@config {
  /* Antes: theme.colors.primary */
  --color-primary: #3b82f6;
  
  /* Antes: theme.fontFamily.sans */
  --font-sans: "Inter", system-ui, sans-serif;
  
  /* Antes: theme.spacing[18] */
  --spacing-18: 4.5rem;
}

La eliminación del archivo de configuración JavaScript simplifica la estructura del proyecto y reduce las dependencias de build, especialmente beneficioso en entornos donde la velocidad de compilación es crítica.

Configuración contextual

Tailwind 4 introduce la capacidad de aplicar configuración contextual mediante el uso de media queries y selectores CSS dentro de las directivas de configuración.

@import "tailwindcss";

@config {
  --color-background: #ffffff;
  --color-text: #1f2937;
}

@media (prefers-color-scheme: dark) {
  @config {
    --color-background: #1f2937;
    --color-text: #f9fafb;
  }
}

Esta funcionalidad contextual permite configuraciones dinámicas que responden automáticamente a las preferencias del usuario o condiciones específicas del entorno, sin necesidad de JavaScript adicional.

Ventajas del nuevo sistema

El enfoque CSS-first de Tailwind 4 aporta beneficios significativos en términos de rendimiento y experiencia de desarrollo. La eliminación de la fase de procesamiento JavaScript reduce los tiempos de build y simplifica la integración con herramientas de desarrollo modernas.

La compatibilidad nativa con CSS permite mejor integración con editores de código, proporcionando autocompletado, validación de sintaxis y herramientas de debugging directamente en el contexto de CSS. Además, la configuración queda más cerca del código donde se aplica, mejorando la mantenibilidad y comprensión del proyecto.