Astro

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

DUGLAS MORENO 📅 July 5, 2026 👁 16

Tutorial: Configurar Astro con TypeScript y Tailwind CSS

Introducción

Astro es un framework moderno para crear sitios web rápidos mediante la generación de contenido estático y la posibilidad de usar componentes de React, Vue, Svelte o sólido. Cuando lo combinamos con TypeScript obtenemos tipado estático que ayuda a detectar errores temprano y mejora la experiencia de desarrollo. Tailwind CSS, por su parte, brinda una utilidad‑first approach que permite construir interfaces sin salir del HTML.

Este tutorial está pensado para desarrolladores que ya manejan la línea de comandos, tienen Node.js (>=18) y npm o yarn instalados, y quieren iniciar un proyecto Astro con tipado y estilos Tailwind de forma rápida y sin sorpresas. Al finalizar, tendrás un proyecto listo para desarrollar, construir y desplegar, además de conocer las mejores prácticas y los errores más comunes que suelen aparecer en esta combinación.

Requisitos previos

Antes de comenzar, verificá que tengas instalado lo siguiente:

Node.js versión 18 o superior (node -v).
npm (que viene con Node) o yarn.
Git (opcional, pero útil para versionar).

Si necesitás actualizar Node, podés usar nvm:

nvm install 18
nvm use 18

La salida esperada es algo como:

Now using node v18.18.0 (npm v9.8.1)

Paso 1: Crear el proyecto Astro con plantilla TypeScript

Astro provee un comando interactivo que crea la estructura base. Vamos a usar la plantilla oficial de TypeScript.

npm create astro@latest mi-sitio-astro -- --template typescript

La salida que deberías ver es similar a:

✔ Creating a new Astro project in /ruta/al/proyecto/mi-sitio-astro
✔ Installing dependencies
✔ Initializing git repository
✔ Project ready! 🎉

Next steps:
  cd mi-sitio-astro
  npm run dev

Ingresá al directorio y levantá el servidor de desarrollo para comprobar que todo funciona:

cd mi-sitio-astro
npm run dev

Deberías ver en la terminal:

  🚀  Astro v2.x.x ready in 1200ms
  ➜  Local:   http://localhost:4321/
  ➜  Network: http://192.168.1.10:4321/
  ➜  Press h to open help

Abrí tu navegador en http://localhost:4321 y verificá que aparezca la página de bienvenida de Astro.

Paso 2: Estructura básica del proyecto

Una vez creado, el proyecto tiene la siguiente estructura (los archivos más relevantes):

mi-sitio-astro/
├─ public/          # assets estáticos
├─ src/
│  ├─ components/   # componentes reutilizables
│  ├─ layouts/      # layouts de página
│  ├─ pages/        # rutas del sitio (cada .astro se convierte en una ruta)
│  └─ styles/       # hojas de estilo globales
├─ astro.config.mjs # configuración de Astro
├─ package.json
├─ tsconfig.json    # configuración de TypeScript
└─ ...

Fijate que ya existe un tsconfig.json gracias a la plantilla TypeScript. Este archivo permite que Astro entienda la sintaxis .ts y .tsx dentro de los componentes.

Paso 3: Instalar Tailwind CSS y sus dependencias

Ahora vamos a agregar Tailwind. Necesitamos los paquetes tailwindcss, postcss y autoprefixer. Además, como vamos a usar el modo JIT (Just‑In‑Time) que viene por defecto en Tailwind 3+, no se necesita nada extra.

Ejecutá:

npm i -D tailwindcss@latest postcss@latest autoprefixer@latest

La salida esperada incluye algo como:

added 3 packages, and audited 1234 packages in 2s

Inicializar la configuración de Tailwind

Tailwind necesita un archivo tailwind.config.cjs (o .js) y un archivo de PostCSS. Vamos a generar ambos con el comando init:

npx tailwindcss init -p

Esto crea dos archivos:

tailwind.config.cjs – configuración de Tailwind.
postcss.config.cjs – configuración de PostCSS que le indica a PostCSS usar Autoprefixer y Tailwind.

La salida será similar a:

Created tailwind.config.cjs
Created postcss.config.cjs

Configurar el contenido que Tailwind debe escanear

Tailwind necesita saber en qué archivos buscar clases para generar el CSS. Editá tailwind.config.cjs y reemplazá su contenido por:

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

Guarde los cambios. La configuración le indica a Tailwind que escanee todos los archivos dentro de src/ con las extensiones indicadas, incluyendo los componentes .astro.

Crear la hoja de estilo global

Astro permite importar CSS globalmente desde un archivo dentro de src/styles/. Creamos (o editamos) el archivo src/styles/global.css y le agregamos las directivas de Tailwind:

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

Si el archivo no existía, créalo así:

mkdir -p src/styles
 echo '@tailwind base;
@tailwind components;
@tailwind utilities;' > src/styles/global.css

La salida del echo será simplemente el contenido escrito al archivo.

Importar la hoja de estilo en el layout raíz

Para que las clases de Tailwind estén disponibles en todo el sitio, importamos global.css en el layout principal. El layout por defecto se encuentra en src/layouts/Layout.astro. Abrí ese archivo y añadí la importación al inicio del frontmatter:

---
import '../styles/global.css';
---

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <link rel="icon" type="image/png" href=\favicon.png" />
    <meta name="viewport" content="width=device-width" />
    <title>Astro</title>
  </head>
  <body>
    <slot />
  </body>
</html>

Guardá el archivo. Ahora cualquier componente que use clases de Tailwind tendrá el CSS aplicado.

Paso 4: Verificar que Tailwind funciona

Creemos un componente simple para probar que las clases se aplican correctamente. Vamos a generar un archivo src/components/Welcome.astro:

mkdir -p src/components
 echo '---
---

<h1 class="text-4xl font-bold text-indigo-600">
  ¡Hola desde Astro + Tailwind!
</h1>

<p class="mt-4 text-gray-600">
  Este componente usa Tailwind para sus estilos.
</p>' > src/components/Welcome.astro

La salida del echo mostrará el contenido del archivo.

Ahora lo incluimos en la página principal. Editá src/pages/index.astro y reemplazá su contenido por:

---
import Welcome from '../components/Welcome.astro';
---

<main class="container mx-auto py-8">
  <Welcome />
</main>

Guardá los cambios y, si el servidor de desarrollo aún está corriendo, debería recargarse automáticamente. En la terminal verás algo como:

  ✅  src/pages/index.astro updated
  🔄  HMR updated

En el navegador deberías ver un título grande en color índigo y un párrafo gris, todo con el espaciado propio de Tailwind. Si no ves los estilos, revisá que el archivo global.css esté importado en el layout y que la configuración de content en tailwind.config.cjs incluya la ruta correcta.

Paso 5: Usar TypeScript dentro de los componentes Astro

Astro permite escribir lógica en TypeScript dentro del bloque de script (---) de un componente. Vamos a crear un componente que muestre la fecha actual usando TypeScript.

Creá src/components/DateTime.astro:

 echo '---
import { format } from "date-fns\); // Vamos a instalar date-fns luego

const ahora = new Date();
const fechaFormateada = format(ahora, "PPP ppp");
---

<div class="border p-4 rounded mt-6">
  <h2 class="text-lg font-semibold">Fecha y hora actual</h2>
  <p class="text-sm text-gray-500"> {fechaFormateada} </p>
</div>' > src/components/DateTime.astro

Nota: el bloque anterior muestra una barra invertida escapada para evitar que el string JSON la interprete como escape. En el archivo real la línea será import { format } from "date-fns\);.

Instalemos date-fns como dependencia (no es de desarrollo):

npm i date-fns

Salida esperada:

added 1 package, and audited 1235 packages in 1s

Ahora importá este componente en la página principal, debajo del Welcome:

---
import Welcome from '../components/Welcome.astro';
import DateTime from '../components/DateTime.astro';
---

<main class="container mx-auto py-8">
  <Welcome />
  <DateTime />
</main>

Guardá y recargá la página. Deberías ver debajo del mensaje de bienvenida un cuadro con la fecha y hora formateada. Si abrí la consola del navegador no verás errores de TypeScript porque Astro lo compila en tiempo de build.

Paso 6: Build y preview de producción

Cuando el sitio esté listo para producción, Astro genera un sitio estático optimizado. Ejecutá:

npm run build

La salida será algo como:

> astro build

  ✅  Compiled 3 modules
  ✅  Generated 2 pages
  ✅  Written to dist/

  Build completed in 1.23s

La carpeta dist/ contiene los archivos HTML, CSS y JavaScript listos para servir. Para previewar el build localmente, usá:

npm run preview

Verás en la terminal:

> astro preview

  🚀  Astro v2.x.x ready in 800ms
  ➜  Local:   http://localhost:4321/
  ➜  Network: http://192.168.1.10:4321/

Abrí esa URL y confirmá que el sitio se ve idéntico al de desarrollo, pero ahora los archivos son estáticos y mucho más ligeros.

Paso 7: Buenas prácticas y errores comunes

Buenas prácticas

Mantener el content de Tailwind actualizado – Cada vez que creés una nueva carpeta de componentes o rutas, agregala al array content de tailwind.config.cjs para que Tailwind incluya esas clases en el CSS generado.
Usar el modo JIT – Tailwind 3+ lo tiene activado por defecto; evita generar un CSS gigantesco.
Separar estilos globales de los de componente – Pon en src/styles/global.css solo las directivas @tailwind base; @tailwind components; @tailwind utilities;. Los estilos específicos de un componente pueden ir en clases de Tailwind directamente o en un bloque <style> dentro del componente si necesitás CSS arbitrario.

Aprovechar el TypeScript de Astro – Tipá las props de tus componentes usando la interfaz Props dentro del frontmatter. Ejemplo:

---
interface Props {
  titulo: string;
  subtitulo?: string;
}
const { titulo, subtitulo } = Astro.props;
---
<h1 class="text-2xl" >{titulo}</h1>
{subtitulo && <p class="mt-2" >{subtitul o}</p>}

Utilizar astro:assets para importar imágenes – Así evitas que las imágenes queden fuera del proceso de build y obtienes optimización automática.

Errores comunes

Olvidar reiniciar el servidor de desarrollo después de modificar tailwind.config.cjs – Los cambios en la configuración no se aplican hasta que el proceso de Vite se reinicia. Detená con Ctrl+C y volvé a correr npm run dev.
No incluir la extensión correcta en el content – Si usas .astro pero te olvidas de agregarlo, Tailwind no encontrará las clases y tu CSS quedará vacío.
Importar el CSS global en un componente en vez del layout – Si lo importás solo en un componente, las clases de Tailwind no estarán disponibles en otras páginas.
Usar class en vez de class: en Astro – En Astro, para aplicar clases condicionales se usa la sintaxis class:. Por ejemplo: `<p class: {activo}" class=

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

Tutorial: Configurar Astro con TypeScript y Tailwind CSS

Introducción

Requisitos previos

Paso 1: Crear el proyecto Astro con plantilla TypeScript

Paso 2: Estructura básica del proyecto

Paso 3: Instalar Tailwind CSS y sus dependencias

Inicializar la configuración de Tailwind

Configurar el contenido que Tailwind debe escanear

Crear la hoja de estilo global

Importar la hoja de estilo en el layout raíz

Paso 4: Verificar que Tailwind funciona

Paso 5: Usar TypeScript dentro de los componentes Astro

Paso 6: Build y preview de producción

Paso 7: Buenas prácticas y errores comunes

Buenas prácticas

Errores comunes

Comentarios (0)

Dejá tu comentario

Tutorial: Configurar Astro con TypeScript y Tailwind CSS

Introducción

Requisitos previos

Paso 1: Crear el proyecto Astro con plantilla TypeScript

Paso 2: Estructura básica del proyecto

Paso 3: Instalar Tailwind CSS y sus dependencias

Inicializar la configuración de Tailwind

Configurar el contenido que Tailwind debe escanear

Crear la hoja de estilo global

Importar la hoja de estilo en el layout raíz

Paso 4: Verificar que Tailwind funciona

Paso 5: Usar TypeScript dentro de los componentes Astro

Paso 6: Build y preview de producción

Paso 7: Buenas prácticas y errores comunes

Buenas prácticas

Errores comunes

Posts relacionados

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

Dominando los Layouts en Astro: Cómo usar Slots y Props para crear páginas consistentes

Comentarios (0)

Dejá tu comentario

Suscribite