Astro

Cómo integrar Tailwind CSS en un proyecto Astro usando astro add

DUGLAS MORENO 📅 July 7, 2026 👁 15

Introducción

En los últimos años Astro se ha convertido en una de las opciones más populares para crear sitios estáticos y aplicaciones web ligeras. Su filosofía basada en "componentes sin JavaScript por defecto" permite generar páginas ultra‑rápidas, pero al mismo tiempo no sacrifica la capacidad de usar herramientas modernas de UI. Tailwind CSS es el framework de utilidades que está rompiendo los esquemas de estilos: en lugar de escribir CSS tradicional, componés la UI directamente con clases predefinidas.

Este artículo está dirigido a desarrolladores front‑end que ya tienen conocimientos básicos de Astro (estructura de proyecto, componentes .astro) y quieren añadir Tailwind de forma automática mediante el comando astro add. Verás paso a paso cómo hacerlo, cómo configurar los archivos, y tendrás ejemplos de componentes y la salida esperada en el navegador.

Al finalizar vas a poder:

Crear un proyecto Astro desde cero.
Instalar y configurar Tailwind CSS con astro add.
Usar clases de Tailwind en componentes .astro y en archivos .css.
Ver la salida renderizada y entender cómo Astro optimiza el CSS.

1. Crear el proyecto Astro

Si todavía no tenés Astro instalado, lo podés hacer con npm init astro@latest o pnpm create astro. Para este tutorial usaremos npm.

npm init astro@latest tailwind-astro-demo
cd tailwind-astro-demo
npm install

Esto genera la estructura típica:

├─ public/
├─ src/
│  ├─ components/
│  ├─ layouts/
│  └─ pages/
├─ astro.config.mjs
└─ package.json

2. Añadir Tailwind CSS con `astro add`

Astro incluye un integrador de paquetes que simplifica la instalación de herramientas comunes. Ejecutá el siguiente comando:

npm run astro add tailwind

Lo que hace este comando es:

Instalar tailwindcss, postcss y autoprefixer como dependencias dev.
Crear un archivo tailwind.config.cjs con la configuración base.
Generar src/styles/global.css que importa las directivas de Tailwind (@tailwind base; @tailwind components; @tailwind utilities;).
Modificar astro.config.mjs para que incluya el plugin de Tailwind.

Después de ejecutar, el árbol de proyecto se verá así:

├─ src/
│  ├─ styles/
│  │  └─ global.css   ← nuevo
│  └─ pages/
│     └─ index.astro
├─ tailwind.config.cjs
└─ astro.config.mjs   ← actualizado

2.1 Verificación de la configuración

Abre tailwind.config.cjs. Debería contener algo como:

/** @type {import('tailwindcss').Config} */
module.exports = {
  content: ["./src/**/*.{astro,html,js,jsx,ts,tsx}"] ,
  theme: { extend: {} },
  plugins: [],
};

La clave content le indica a Tailwind que escanee todos los archivos dentro de src con esas extensiones para generar únicamente las clases usadas (purga automática).

3. Usar Tailwind en componentes Astro

3.1 Primer componente con Tailwind

Creemos un nuevo componente src/components/Card.astro que muestra una tarjeta con título, texto y botón.

---
const { title, description } = Astro.props;
---
<div class="max-w-sm rounded overflow-hidden shadow-lg bg-white">
  <div class="px-6 py-4">
    <div class="font-bold text-xl mb-2 text-gray-800">{title}</div>
    <p class="text-gray-700 text-base">{description}</p>
  </div>
  <div class="px-6 pt-4 pb-2">
    <button class="bg-blue-500 hover:bg-blue-700 text-white font-bold py-2 px-4 rounded">
      Saber más
    </button>
  </div>
</div>

3.2 Incluir el componente en la página principal

Editá src/pages/index.astro para importar y usar la tarjeta.

---
import Card from "../components/Card.astro";
---
<html lang="es">
  <head>
    <meta charset="UTF-8" />
    <title>Demo Tailwind + Astro</title>
    <link rel="stylesheet" href="/src/styles/global.css" />
  </head>
  <body class="bg-gray-100 flex items-center justify-center min-h-screen">
    <Card
      title="Hola Mundo"
      description="Esta es una tarjeta estilizada con Tailwind CSS dentro de Astro."
    />
  </body>
</html>

3.3 Salida esperada

Al levantar el servidor con npm run dev y abrir http://localhost:3000, deberías ver una tarjeta centrada, con sombra, título en negrita y un botón azul. El HTML que el navegador recibe (simplificado) es:

<div class="max-w-sm rounded overflow-hidden shadow-lg bg-white">
  <div class="px-6 py-4">
    <div class="font-bold text-xl mb-2 text-gray-800">Hola Mundo</div>
    <p class="text-gray-700 text-base">Esta es una tarjeta estilizada con Tailwind CSS dentro de Astro.</p>
  </div>
  <div class="px-6 pt-4 pb-2">
    <button class="bg-blue-500 hover:bg-blue-700 text-white font-bold py-2 px-4 rounded">Saber más</button>
  </div>
</div>

Observá cómo no hay clases generadas a mano, solo utilidades de Tailwind. Además, como Astro hace tree‑shaking del CSS, en la hoja final sólo estarán presentes las clases usadas arriba.

4. Optimización y modo producción

Cuando ejecutás npm run build, Astro compila la app y Tailwind procesa global.css. El resultado es un archivo /_astro/_base.css que contiene menos de 2 KB (gzip) gracias a la purga de clases no utilizadas.

Puedes comprobarlo mirando el bundle con npm run preview o inspeccionando la red en DevTools.

5. Buenas prácticas y errores comunes

5.1 Buenas prácticas

Mantener la configuración de content actualizada: si añadís carpetas externas (por ejemplo src/lib), incluílas en el array.
Usar @apply con moderación: si necesitás un conjunto de utilidades repetidas, crea una clase en global.css con @apply para mantener el HTML limpio.
Aprovechar los plugins de Tailwind: por ejemplo @tailwindcss/forms para estilizar formularios sin escribir CSS extra.
Habilitar darkMode: 'class' en tailwind.config.cjs si planeás soportar modo oscuro y controlarlo desde Astro.

5.2 Errores frecuentes

Error	Por qué ocurre	Cómo solucionarlo
Las clases de Tailwind no aparecen en la página	`content` no incluye la ruta del archivo que usa la clase	Añadir la ruta correcta o usar `./src/*/.{astro,js,ts}`
El CSS sigue siendo muy grande en producción	No se ejecutó el build o faltó `purge`	Ejecutar `npm run build` y asegurarse de que `NODE_ENV=production`
El botón no cambia de color al hacer hover	Falta `hover:` en la clase o el archivo CSS no está importado	Verificar que `<link rel="stylesheet" href="/src/styles/global.css"/>` está en `<head>`
Conflict entre Tailwind y estilos globales	Ambas reglas usan la misma especificidad	Usar `!important` o estructurar los estilos con capas (`@layer utilities`)

6. Extender Tailwind en Astro

Puedes personalizar la paleta de colores, fuentes y breakpoints editando tailwind.config.cjs.

module.exports = {
  content: ["./src/**/*.{astro,js,ts,jsx,tsx}"] ,
  theme: {
    extend: {
      colors: {
        primary: "#1e40af",
        secondary: "#64748b",
      },
      fontFamily: {
        sans: ["Inter", "system-ui"],
      },
    },
  },
  plugins: [],
};

Luego podés usar bg-primary o font-sans en cualquier componente.

Conclusión

Integrar Tailwind CSS en Astro mediante astro add tailwind es extremadamente sencillo y te brinda una hoja de estilos mínima y altamente optimizada. En el recorrido cubrimos:

Creación del proyecto Astro.
Instalación automática con astro add.
Configuración y verificación de tailwind.config.cjs.
Uso de utilidades de Tailwind en componentes .astro.
Observación de la salida HTML y del bundle final.
Buenas prácticas y solución de errores típicos.

Con esta base, podés seguir explorando la enorme colección de plugins de Tailwind (typography, forms, aspect‑ratio) y combinarlo con la potencia de Astro para construir sitios rápidos, modernos y altamente mantenibles.

Próximos pasos recomendados:

Añadir @tailwindcss/typography para mejorar la presentación de contenido markdown.
Configurar modo oscuro y usar la clase dark en el html root.
Implementar un sistema de diseño (design system) usando @apply y capas de Tailwind.

¡Manos a la obra y feliz codificación!

Cómo integrar Tailwind CSS en un proyecto Astro usando astro add

Introducción

1. Crear el proyecto Astro

2. Añadir Tailwind CSS con `astro add`

2.1 Verificación de la configuración

3. Usar Tailwind en componentes Astro

3.1 Primer componente con Tailwind

3.2 Incluir el componente en la página principal

3.3 Salida esperada

4. Optimización y modo producción

5. Buenas prácticas y errores comunes

5.1 Buenas prácticas

5.2 Errores frecuentes

6. Extender Tailwind en Astro

Conclusión

Comentarios (0)

Dejá tu comentario

Introducción

1. Crear el proyecto Astro

2. Añadir Tailwind CSS con astro add

2.1 Verificación de la configuración

3. Usar Tailwind en componentes Astro

3.1 Primer componente con Tailwind

3.2 Incluir el componente en la página principal

3.3 Salida esperada

4. Optimización y modo producción

5. Buenas prácticas y errores comunes

5.1 Buenas prácticas

5.2 Errores frecuentes

6. Extender Tailwind en Astro

Conclusión

Posts relacionados

Cómo instalar y configurar Astro con TypeScript y Tailwind CSS paso a paso

Entendiendo la estructura de un proyecto Astro: src/pages, src/components, src/layouts y public

Entendiendo la sintaxis de los archivos .astro: frontmatter, HTML y expresiones JS

Entendiendo el frontmatter en Astro: sintaxis, usos y ejemplos prácticos

Cómo los componentes Astro generan HTML puro sin JavaScript en el cliente

Cómo tipar props en Astro con TypeScript usando interfaces

Comentarios (0)

Dejá tu comentario

Suscribite

2. Añadir Tailwind CSS con `astro add`