TypeScript en Astro e integraciones

Astro trae TypeScript de fábrica: no necesitas configurar nada para escribir tipos, y buena parte de la seguridad la genera el propio framework a partir de tu proyecto. Entender de dónde salen esos tipos —los tsconfig que heredas, la carpeta .astro que Astro rellena, las props que declaras— convierte al editor en un copiloto que caza errores antes de que existan.

tsconfig: heredar el rigor de Astro

Astro publica tres configuraciones base de TypeScript, y tu tsconfig.json extiende una de ellas en vez de definir decenas de opciones a mano. Elegir cuál es elegir cuánto rigor quieres que el compilador te imponga.

La recomendación es empezar en strict y subir a strictest cuando el proyecto madure; bajar a base solo tiene sentido al migrar código viejo que aún no pasa las comprobaciones. Cambiar de nivel es tan simple como editar una línea:

{
  "extends": "astro/tsconfigs/strict",
  "include": [".astro/types.d.ts", "**/*"],
  "exclude": ["dist"]
}

Fíjate en el include: incorpora .astro/types.d.ts, el fichero de tipos que Astro genera. Sin esa línea, tu editor no vería los tipos del framework ni los de tu contenido. La plantilla lo pone por ti; si tocas el tsconfig, no lo borres.

Junto al tsconfig verás a veces un src/env.d.ts con una referencia a los tipos de cliente de Astro. Es el punto donde el proyecto engancha los tipos globales del framework —los de import.meta.env, los assets, los módulos virtuales—. No necesitas tocarlo, pero saber que existe explica de dónde salen tipos que nunca declaraste.

Tipos generados: astro sync y la carpeta .astro

Parte de los tipos no los escribes tú ni los trae Astro fijos: los genera el framework a partir de tu proyecto. Cuando defines una colección de contenido con su esquema, Astro deduce el tipo exacto de cada entrada; cuando declaras variables de entorno tipadas, genera su interfaz. Todo eso aterriza en la carpeta .astro, que no editas nunca y que conviene ignorar en git.

npx astro sync
# regenera los tipos en .astro/ a partir de tu contenido,
# tus esquemas y tus variables de entorno

astro sync se ejecuta solo antes de dev y build, así que casi nunca lo lanzas a mano. Lo haces cuando cambias un esquema de colección y el editor sigue mostrando el tipo viejo: un astro sync refresca .astro sin necesidad de arrancar el servidor. Es el puente que mantiene tus tipos sincronizados con la realidad de tu contenido.

El efecto se nota al consumir contenido: cuando llamas a getCollection sobre una colección, lo que recibes está tipado según su esquema. Si el esquema dice que cada entrada tiene un titulo de texto y una fecha, el editor lo sabe, autocompleta esos campos y protesta si escribes uno que no existe. No has añadido ni una anotación de tipo: la seguridad brota del esquema que ya declaraste.

import { getCollection } from 'astro:content';

// cada entrada esta tipada segun el esquema de la coleccion
const posts = await getCollection('blog');
const titulo = posts[0].data.titulo;  // string, con autocompletado

flowchart LR
SCHEMA[esquemas de coleccion] --> SYNC[astro sync]
ENV[variables de entorno] --> SYNC
SYNC --> GEN[carpeta .astro con tipos]
GEN --> ED[autocompletado en el editor]
GEN --> CHK[astro check valida]
style SYNC fill:#89b4fa,color:#11111b
style ED fill:#a6e3a1,color:#11111b

Tipar componentes: interface Props

Dentro de un componente .astro, las props que recibe se tipan declarando una interfaz llamada Props. Astro reconoce ese nombre por convención y tipa automáticamente Astro.props, de modo que quien use el componente recibe autocompletado y errores si pasa algo incorrecto.

---
interface Props {
  titulo: string;
  destacado?: boolean;
}
const { titulo, destacado = false } = Astro.props;
---
<h2 class={destacado ? 'es-destacado' : ''}>{titulo}</h2>

La interfaz declara el contrato: titulo es obligatorio y de tipo texto, destacado es opcional. Al desestructurar Astro.props puedes dar valores por defecto, como destacado = false. A partir de ahí, si otra página escribe el componente y olvida titulo, el editor y astro check lo marcan. Es la misma seguridad de un componente de React o Vue, sin salir de .astro.

El tipado se propaga hacia arriba: como Astro.props conoce la forma exacta, cualquier página que use el componente recibe autocompletado de sus props y un error si pasa un tipo incorrecto o se deja uno obligatorio. Y no se detiene en las props; dentro del frontmatter, Astro.params, Astro.request y el resto del objeto Astro están tipados, así que el editor te guía también al leer parámetros de ruta o cabeceras.

Integraciones: astro add en profundidad

Añadir una integración a mano implica tres pasos frágiles: instalar el paquete, importarlo en astro.config.mjs y registrarlo en el array integrations sin romper la sintaxis. astro add los ejecuta por ti y te enseña el diff antes de tocar nada.

npx astro add tailwind
# instala la integracion y sus dependencias
# edita astro.config.mjs anadiendo el import y la entrada en integrations
# crea o ajusta ficheros de configuracion propios de la integracion
# todo previa confirmacion, mostrando los cambios

Conviene distinguir dos conceptos que se confunden. Una integración de Astro engancha en los hooks del framework —renderizar un framework de UI, generar un sitemap, procesar estilos— y se registra en integrations. Un plugin de Vite opera una capa más abajo, sobre el bundler, y se declara en la clave vite. astro add gestiona lo primero; lo segundo lo tocas a mano cuando necesitas bajar al pipeline, como viste en la lección de configuración.

Cuando ejecutas astro add, el comando toca hasta tres sitios por ti, siempre mostrándote el diff antes:

• package.json, al instalar el paquete de la integración y sus dependencias.
• astro.config.mjs, añadiendo el import y la entrada en el array integrations.
• tsconfig.json o ficheros propios de la integración, cuando esta los necesita.