TypeScript

Astro viene con soporte integrado para TypeScript. Puedes importar archivos .ts y .tsx en tu proyecto de Astro, escribir código TypeScript directamente dentro de tu componente de Astro, e incluso usar un archivo astro.config.ts para tu configuración de Astro si lo deseas.

Usando TypeScript, puedes prevenir errores en tiempo de ejecución definiendo las formas de objetos y componentes en tu código. Por ejemplo, si usas TypeScript para tipar las props de tu componente, obtendrás un error en tu editor si estableces una prop que tu componente no acepta.

No necesitas escribir código TypeScript en tus proyectos de Astro para beneficiarte de él. Astro siempre trata el código de tus componentes como TypeScript, y la extensión de VS Code de Astro inferirá tanto como pueda para proporcionar autocompletado, sugerencias y errores en tu editor.

El dev server de Astro no realizará ninguna verificación de tipos, pero puedes usar un script separado para comprobar errores de tipos desde la línea de comandos.

Configuración

Los proyectos de inicio de Astro incluyen un archivo tsconfig.json en tu proyecto. Incluso si no escribes código TypeScript, este archivo es importante para que herramientas como Astro y VS Code sepan cómo entender tu proyecto. Algunas funcionalidades (como importaciones de paquetes npm) no son totalmente compatibles en el editor sin un archivo tsconfig.json. Si instalas Astro manualmente, asegúrate de crear este archivo tú mismo.

Plantillas de TSConfig

Astro incluye tres plantillas extensibles de tsconfig.json: base, strict, y strictest. La plantilla base habilita el soporte para funcionalidades modernas de JavaScript y también se usa como base para las otras plantillas. Recomendamos usar strict o strictest si planeas escribir TypeScript en tu proyecto. Puedes ver y comparar las tres configuraciones de plantilla en astro/tsconfigs/.

Para heredar de una de las plantillas, usa el ajuste extends:

tsconfig.json

{
  "extends": "astro/tsconfigs/base"
}

Adicionalmente, recomendamos configurar include y exclude de la siguiente manera para beneficiarte de los tipos de Astro y evitar comprobar los archivos generados:

tsconfig.json

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

Plugin de TypeScript para el editor

El plugin de TypeScript de Astro puede instalarse por separado cuando no estás usando la extensión oficial de VS Code de Astro. Este plugin se instala y configura automáticamente con la extensión de VS Code, y no necesitas instalar ambos.

Este plugin se ejecuta solo en el editor. Al ejecutar tsc en la terminal, los archivos .astro se ignoran por completo. En su lugar, puedes usar el comando CLI astro check para comprobar tanto archivos .astro como .ts.

Este plugin también soporta la importación de archivos .astro desde archivos .ts (lo cual puede ser útil para re-exportar).

npm

npm install @astrojs/ts-plugin

pnpm

pnpm add @astrojs/ts-plugin

Yarn

yarn add @astrojs/ts-plugin

Luego, añade lo siguiente a tu tsconfig.json:

tsconfig.json

{
  "compilerOptions": {
    "plugins": [
      {
        "name": "@astrojs/ts-plugin"
      },
    ],
  }
}

Para comprobar que el plugin funciona, crea un archivo .ts e importa un componente de Astro en él. No deberías tener mensajes de advertencia de tu editor.

UI Frameworks

Si tu proyecto usa un UI framework, puede que se necesiten ajustes adicionales dependiendo del framework. Consulta la documentación de TypeScript de tu framework para más información. (Vue, React, Preact, Solid, Svelte)

Importaciones de tipos

Usa importaciones y exportaciones de tipos explícitas siempre que sea posible.

import { SomeType } from "./script";
import type { SomeType } from "./script";

De esta manera, evitas casos límite donde el bundler de Astro puede intentar empaquetar incorrectamente tus tipos importados como si fueran JavaScript.

Puedes configurar TypeScript para forzar las importaciones de tipos en tu archivo tsconfig.json. Establece verbatimModuleSyntax a true. TypeScript comprobará tus importaciones y te indicará cuándo debes usar import type. Este ajuste está habilitado por defecto en todos nuestros presets.

tsconfig.json

{
  "compilerOptions": {
    "verbatimModuleSyntax": true
  }
}

Aliases de importación

Astro soporta los aliases de importación que defines en la configuración de paths de tu tsconfig.json. Lee nuestra guía de importaciones para más información.

src/pages/about/nate.astro

---
import HelloWorld from "@components/HelloWorld.astro";
import Layout from "@layouts/Layout.astro";
---

tsconfig.json

{
  "compilerOptions": {
    "paths": {
      "@components/*": ["./src/components/*"],
      "@layouts/*": ["./src/layouts/*"]
    }
  }
}

Extender tipos globales

Puedes crear src/env.d.ts como convención para añadir declaraciones de tipos personalizados, o para beneficiarte de los tipos de Astro si no tienes un tsconfig.json:

src/env.d.ts

// Custom types declarations
declare var myString: string;

// Astro types, not necessary if you already have a `tsconfig.json`
/// <reference path="../.astro/types.d.ts" />

window y globalThis

Puede que quieras añadir una propiedad al objeto global. Puedes hacerlo añadiendo declaraciones de nivel superior usando la palabra clave declare en tu archivo env.d.ts:

src/env.d.ts

declare var myString: string;
declare function myFunction(): boolean;

Esto proporcionará tipado a globalThis.myString y globalThis.myFunction, así como a window.myString y window.myFunction.

Ten en cuenta que window solo está disponible en código del lado del cliente. globalThis está disponible tanto en el lado del servidor como del cliente, pero su valor del lado del servidor no se compartirá con el cliente.

Si solo quieres tipar una propiedad en el objeto window, proporciona una interfaz Window en su lugar:

src/env.d.ts

interface Window {
  myFunction(): boolean;
}

Añadir atributos no estándar

Puede que quieras definir un tipo para atributos personalizados o propiedades CSS. Puedes extender las definiciones predeterminadas de JSX para añadir atributos no estándar volviendo a declarar el namespace astroHTML.JSX en un archivo .d.ts.

src/env.d.ts

declare namespace astroHTML.JSX {
  interface HTMLAttributes {
    "data-count"?: number;
    "data-label"?: string;
  }

  // Add a CSS custom property to the style object
  interface CSSProperties {
    "--theme-color"?: "black" | "white";
  }
}

Nota

astroHTML se inyecta globalmente dentro de los componentes .astro. Para usarlo en archivos TypeScript, usa una directiva triple-slash:

/// <reference types="astro/astro-jsx" />

type MyAttributes = astroHTML.JSX.ImgHTMLAttributes;

Uso de importaciones

Puede que quieras extender los tipos globales reutilizando tipos declarados en otro lugar de tu proyecto o desde una librería externa. Para hacerlo, usa importaciones dinámicas:

src/env.d.ts

type Product = {
  id: string;
  name: string;
  price: number;
};

declare namespace App {
  interface Locals {
    orders: Map<string, Product[]>
    session: import("./lib/server/session").Session | null;
    user: import("my-external-library").User;
  }
}

Un archivo .d.ts es una declaración de módulo ambiente. Aunque su sintaxis es similar a los módulos ES, estos archivos no permiten importaciones/exportaciones de nivel superior. Si TypeScript encuentra una, el archivo se considerará una augmentación de módulo y esto romperá tus tipos globales.

Props de componentes

Astro soporta el tipado de las props de tus componentes vía TypeScript. Para habilitarlo, añade una interfaz Props de TypeScript al frontmatter de tu componente. Se puede usar un statement export, pero no es necesario. La extensión de VS Code de Astro buscará automáticamente la interfaz Props y te dará el soporte adecuado de TS cuando uses ese componente dentro de otra plantilla.

src/components/HelloProps.astro

---
interface Props {
  name: string;
  greeting?: string;
}

const { greeting = "Hello", name } = Astro.props;
---
<h2>{greeting}, {name}!</h2>

Patrones comunes de tipos de props

• Si tu componente no toma props ni contenido slotted, puedes usar type Props = Record<string, never>.
• Si tu componente debe recibir children en su slot por defecto, puedes forzarlo usando type Props = { children: any; };.

Utilidades de tipos

Añadido en: astro@1.6.0

Astro viene con algunas utilidades de tipos integradas para patrones comunes de tipos de props. Estas están disponibles bajo el entrypoint astro/types.

Atributos HTML integrados

Astro proporciona el tipo HTMLAttributes para comprobar que tu markup está usando atributos HTML válidos. Puedes usar estos tipos para ayudar a construir las props de tus componentes.

Por ejemplo, si estuvieras construyendo un componente <Link>, podrías hacer lo siguiente para reflejar los atributos HTML por defecto de las etiquetas <a> en los tipos de props de tu componente.

src/components/Link.astro

---
import type { HTMLAttributes } from "astro/types";

// use a `type`
type Props = HTMLAttributes<"a">;

// or extend with an `interface`
interface Props extends HTMLAttributes<"a"> {
  myProp?: boolean;
}

const { href, ...attrs } = Astro.props;
---
<a href={href} {...attrs}>
  <slot />
</a>

Tipo ComponentProps

Añadido en: astro@4.3.0

Esta exportación de tipo te permite referenciar las Props aceptadas por otro componente, incluso si ese componente no exporta ese tipo Props directamente.

El siguiente ejemplo muestra el uso de la utilidad ComponentProps de astro/types para referenciar los tipos de Props de un componente <Button />:

src/pages/index.astro

---
import type { ComponentProps } from "astro/types";
import Button from "./Button.astro";

type ButtonProps = ComponentProps<typeof Button>;
---

Tipo polimórfico

Añadido en: astro@2.5.0

Astro incluye un helper para facilitar la construcción de componentes que pueden renderizarse como diferentes elementos HTML con total seguridad de tipos. Esto es útil para componentes como <Link> que pueden renderizarse como <a> o <button> dependiendo de las props que se le pasen.

El siguiente ejemplo implementa un componente polimórfico totalmente tipado que puede renderizarse como cualquier elemento HTML. El tipo HTMLTag se usa para asegurar que la prop as sea un elemento HTML válido.

---
import type { HTMLTag, Polymorphic } from "astro/types";

type Props<Tag extends HTMLTag> = Polymorphic<{ as: Tag }>;

const { as: Tag, ...props } = Astro.props;
---
<Tag {...props} />

Inferir tipos de getStaticPaths()

Añadido en: astro@2.1.0

Astro incluye helpers para trabajar con los tipos devueltos por tu función getStaticPaths() para rutas dinámicas.

Puedes obtener el tipo de Astro.params con InferGetStaticParamsType y el tipo de Astro.props con InferGetStaticPropsType o puedes usar GetStaticPaths para inferir ambos a la vez:

src/pages/posts/[...id].astro

---
import type {
  InferGetStaticParamsType,
  InferGetStaticPropsType,
  GetStaticPaths,
} from "astro";

export const getStaticPaths = (async () => {
  const posts = await getCollection("blog");
  return posts.map((post) => {
    return {
      params: { id: post.id },
      props: { draft: post.data.draft, title: post.data.title },
    };
  });
}) satisfies GetStaticPaths;

type Params = InferGetStaticParamsType<typeof getStaticPaths>;
type Props = InferGetStaticPropsType<typeof getStaticPaths>;

const { id } = Astro.params as Params;
//                   ^? { id: string; }

const { title } = Astro.props;
//                      ^? { draft: boolean; title: string; }
---

Verificación de tipos

Para ver errores de tipos en tu editor, asegúrate de tener la extensión de VS Code de Astro instalada. Ten en cuenta que los comandos astro start y astro build transpilarán el código con esbuild, pero no ejecutarán ninguna verificación de tipos. Para evitar que tu código se compile si contiene errores de TypeScript, cambia tu script "build" en package.json a lo siguiente:

package.json

{
  "scripts": {
    "build": "astro build",
    "build": "astro check && astro build",
  },
}

Nota

astro check comprueba todos los archivos incluidos en tu proyecto de TypeScript. Para comprobar tipos dentro de archivos Svelte y Vue, puedes usar los paquetes svelte-check y vue-tsc respectivamente.

Lee más sobre importaciones de archivos .ts en Astro.

Lee más sobre la Configuración de TypeScript.

Resolución de problemas

Errores al tipar múltiples frameworks JSX al mismo tiempo

Puede surgir un problema al usar múltiples frameworks JSX en el mismo proyecto, ya que cada framework requiere ajustes diferentes y a veces conflictivos dentro de tsconfig.json.

Solución: Establece el ajuste jsxImportSource a react (por defecto), preact o solid-js dependiendo del framework que más uses. Luego, usa un comentario pragma dentro de cualquier archivo conflictivo de un framework diferente.

Para el ajuste por defecto de jsxImportSource: react, usarías:

// For Preact
/** @jsxImportSource preact */

// For Solid
/** @jsxImportSource solid-js */