import Since from '/components/Since.astro' import PackageManagerTabs from '/components/tabs/PackageManagerTabs.astro'

Astro est livré avec une prise en charge intégrée pour TypeScript. Vous pouvez importer des fichiers .ts et .tsx dans votre projet Astro, écrire du code TypeScript directement dans votre composant Astro, et même utiliser un fichier astro.config.ts pour la configuration d'Astro si vous le souhaitez.

En utilisant TypeScript, vous pouvez éviter les erreurs à l'exécution en définissant les formes des objets et des composants dans votre code. Par exemple, si vous utilisez TypeScript pour définir le typage des props de votre composant, vous obtiendrez une erreur dans votre éditeur si vous définissez une option que votre composant n'accepte pas.

Vous n'avez pas besoin d'écrire du code TypeScript dans vos projets Astro pour en bénéficier. Astro traite toujours le code de vos composants comme du TypeScript, et l'extension Astro pour VS Code en déduira autant que possible pour fournir une autocomplétion, des astuces et des erreurs dans votre éditeur.

Le serveur de développement d'Astro n'effectue aucune vérification des types, mais vous pouvez utiliser un script séparé pour vérifier les erreurs de type à partir de la ligne de commande.

Configuration

Les projets de démarrage d'Astro incluent un fichier tsconfig.json dans votre projet. Même si vous n'écrivez pas de code TypeScript, ce fichier est important pour que des outils comme Astro et VS Code sachent comment comprendre votre projet. Certaines fonctionnalités (comme les importations de paquets npm) ne sont pas entièrement prises en charge par l'éditeur sans un fichier tsconfig.json. Si vous installez Astro manuellement, assurez-vous de créer ce fichier vous-même.

Modèles TSConfig

Trois modèles extensibles tsconfig.json sont inclus dans Astro : base, strict, et strictest. Le modèle base active la prise en charge des fonctionnalités modernes de JavaScript et est également utilisé comme base pour les autres modèles. Nous recommandons d'utiliser strict ou strictest si vous prévoyez d'écrire du TypeScript dans votre projet. Vous pouvez voir et comparer les trois configurations de modèles dans [astro/tsconfigs/] (https://github.com/withastro/astro/blob/main/packages/astro/tsconfigs/).

Pour hériter d'un des modèles, utilisez le paramètre extends :

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

En complément, nous vous recommandons de définir include et exclude comme suit pour bénéficier des types d'Astro et éviter de vérifier les fichiers créés :

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

Vous pouvez créer le fichier src/env.d.ts comme convention pour ajouter des déclarations de types personnalisés, ou pour bénéficier des types d'Astro si vous n'avez pas de tsconfig.json :

// Déclarations de types personnalisésdeclare var myString: string;// Types d'Astro, non nécessaire si vous avez déjà un fichier `tsconfig.json`/// <reference path="../.astro/types.d.ts" />

Module d'extension Typescript pour les éditeurs

Le module d'extension d'Astro pour TypeScript peut être installé séparément si vous n'utilisez pas l'extension officielle d'Astro dans VS Code. Ce module d'extension est automatiquement installé et configuré par l'extension VS Code, et vous n'avez pas besoin d'installer les deux.

Ce module d'extension ne fonctionne que dans l'éditeur. Lorsque vous exécutez tsc dans le terminal, les fichiers .astro sont entièrement ignorés. À la place, vous pouvez utiliser la commande CLI astro check pour vérifier à la fois les fichiers .astro et .ts.

Ce module d'extension prend également en charge l'importation de fichiers .astro à partir de fichiers .ts (ce qui peut être utile pour la réexportation).

Ensuite, ajoutez ce qui suit à votre tsconfig.json :

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

Pour vérifier que le module d'extension fonctionne, créez un fichier .ts et importez-y un composant Astro. Vous ne devriez pas avoir de messages d'avertissement dans votre éditeur.

Frameworks UI

Si votre projet utilise un framework UI, des paramètres supplémentaires dépendant du framework peuvent être nécessaires. Veuillez consulter la documentation TypeScript de votre framework pour plus d'informations. (Vue, React, Preact, Solid)

Importations de types

Utilisez autant que possible des importations et des exportations de types explicites.

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

De cette façon, vous évitez les cas où le regroupeur d'Astro pourrait essayer de regrouper incorrectement vos types importés comme s'il s'agissait de JavaScript.

Vous pouvez configurer TypeScript pour qu'il applique les importations de types dans votre fichier tsconfig.json. Définissez verbatimModuleSyntax sur true. TypeScript vérifiera vos importations et vous dira quand import type doit être utilisé. Ce paramètre est activé par défaut dans tous nos préréglages.

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

Alias d'importation

Astro prend en charge les alias d'importation que vous définissez dans la propriété paths de votre configuration tsconfig.json. Consultez notre guide pour en savoir plus.

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

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

Extension de window et de globalThis

Vous pouvez vouloir ajouter une propriété à l'objet global. Vous pouvez le faire en ajoutant des déclarations de haut niveau en utilisant le mot-clé declare dans votre fichier env.d.ts :

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

Ceci fournira le typage à globalThis.myString et globalThis.myFunction, ainsi qu'à window.myString et window.myFunction.

Notez que window n'est disponible que dans le code côté client. globalThis est disponible à la fois côté serveur et côté client, mais sa valeur côté serveur ne sera pas partagée avec le client.

Si vous voulez seulement définir le type d'une propriété de l'objet window, fournissez une interface Window à la place :

interface Window {	myFunction(): boolean;}

Les props de composants

Astro prend en charge le typage des props de vos composants via TypeScript. Pour l'activer, ajoutez une interface TypeScript Props au frontmatter de votre composant. Une déclaration export peut être utilisée, mais n'est pas nécessaire. L'extension Astro pour VS Code recherchera automatiquement l'interface Props et vous fournira la prise en charge TS appropriée lorsque vous utiliserez ce composant dans un autre modèle.

---interface Props {  name: string;  greeting?: string;}const { greeting = "Hello", name } = Astro.props;---<h2>{greeting}, {name}!</h2>

Modèles courants de typage des props

• Si votre composant n'accepte ni props ni slot, vous pouvez utiliser type Props = Record<string, never>.
• Si votre composant doit recevoir des enfants dans son slot par défaut, vous pouvez l'imposer en utilisant type Props = { children: any; };.

Utilitaires de type

Astro est livré avec quelques utilitaires de type intégrés pour les modèles courants de typage de propriété. Ceux-ci sont disponibles sous le point d'entrée astro/types.

Attributs HTML intégrés

Astro fournit le type HTMLAttributes pour vérifier que votre balisage utilise des attributs HTML valides. Vous pouvez utiliser ces types pour vous aider à construire des props de composants.

Par exemple, si vous construisiez un composant <Link>, vous pouvez procéder comme suit pour refléter les attributs HTML par défaut pour les balises <a> dans le typage des props de votre composant.

---import type { HTMLAttributes } from "astro/types";// utiliser un `type`type Props = HTMLAttributes<"a">;// ou étendre avec une `interface`interface Props extends HTMLAttributes<"a"> {  myProp?: boolean;}const { href, ...attrs } = Astro.props;---<a href={href} {...attrs}>  <slot /></a>

Il est également possible d'étendre les définitions JSX par défaut pour ajouter des attributs non standard en redéclarant l'espace de noms astroHTML.JSX dans un fichier .d.ts.

declare namespace astroHTML.JSX {  interface HTMLAttributes {    "data-count"?: number;    "data-label"?: string;  }  // Ajouter une propriété CSS personnalisée à l'objet style  interface CSSProperties {    "--theme-color"?: "black" | "white";  }}

:::note astroHTML est injecté globalement dans les composants .astro. Pour l'utiliser dans les fichiers TypeScript, utilisez une directive triple barre oblique :

/// <reference types="astro/astro-jsx" />type MyAttributes = astroHTML.JSX.ImgHTMLAttributes;

:::

Type ComponentProps

Cette exportation de type vous permet de référencer les Props acceptées par un autre composant, même si ce composant n'exporte pas directement son type Props.

L'exemple suivant montre l'utilisation de l'utilitaire ComponentProps de astro/types pour référencer les types Props d'un composant <Button /> :

---import type { ComponentProps } from "astro/types";import Button from "./Button.astro";type ButtonProps = ComponentProps<typeof Button>;---

Type polymorphe

Astro inclut une aide pour faciliter la création de composants qui peuvent être rendus comme différents éléments HTML avec une sûreté du typage complète. Ceci est utile pour les composants comme <Link> qui peuvent être rendus comme <a> ou <button> en fonction des props qui lui sont passées.

L'exemple ci-dessous implémente un composant entièrement typé et polymorphe qui peut être rendu comme n'importe quel élément HTML. Le type HTMLTag est utilisé pour s'assurer que la propriété as est un élément HTML valide.

---import type { HTMLTag, Polymorphic } from "astro/types";type Props<Tag extends HTMLTag> = Polymorphic<{ as: Tag }>;const { as: Tag, ...props } = Astro.props;---<Tag {...props} />

Inférer les types de getStaticPaths()

Astro inclut des aides pour travailler avec les types retournés par votre fonction getStaticPaths() pour les routes dynamiques.

Vous pouvez obtenir le type de Astro.params avec InferGetStaticParamsType et le type de Astro.props avec InferGetStaticPropsType ou vous pouvez utiliser GetStaticPaths pour déduire les deux à la fois :

---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; }---

Vérification des types

Pour voir les erreurs de type dans votre éditeur, assurez-vous que vous avez installé l'extension Astro pour VS Code. Veuillez noter que les commandes astro start et astro build transpileront le code avec esbuild, mais n'effectueront aucune vérification de type. Pour éviter que votre code ne soit compilé s'il contient des erreurs TypeScript, remplacez votre script « build » dans package.json par ce qui suit :

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

:::note astro check vérifie tous les fichiers inclus dans votre projet TypeScript. Pour vérifier les types dans les fichiers Svelte et Vue, vous pouvez utiliser les paquets svelte-check et vue-tsc respectivement. :::

import ReadMore from '~/components/ReadMore.astro'

En savoir plus sur les importations de fichiers.ts dans Astro.

En savoir plus sur la configuration de TypeScript.

Résolution des problèmes

Erreurs de typage de plusieurs frameworks JSX en même temps

Un problème peut survenir lors de l'utilisation de plusieurs frameworks JSX dans le même projet, car chaque framework requiert des paramètres différents, parfois contradictoires, dans tsconfig.json.

Solution : Définissez le paramètre jsxImportSource sur react (par défaut), preact ou solid-js en fonction du framework que vous utilisez le plus. Ensuite, utilisez un commentaire pragma à l'intérieur de tout fichier conflictuel provenant d'un framework différent.

Pour le réglage par défaut de jsxImportSource: react, vous utiliseriez :

// Pour Preact/** @jsxImportSource preact */// Pour Solid/** @jsxImportSource solid-js */