TypeScript

Astro est livré avec un support intégré 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’Astro VSCode Extension en déduit autant qu’elle le peut pour fournir une autocomplétion, des astuces et des erreurs dans votre éditeur.

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

Configuration

Titre de la section Configuration

Les projets de démarrage 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 supportées 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

Titre de la section Modèles TSConfig

Trois modèles extensibles tsconfig.json sont inclus dans Astro : base, strict, et strictest. Le modèle base permet le support 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 à [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 :

tsconfig.json

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

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

tsconfig.json

{
  "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 Astro si vous n’avez pas de tsconfig.json :

src/env.d.ts

// Déclarations de types personnalisés
declare var myString: string;

// Types d'Astro, non nécessaire si vous avez déjà un tsconfig.json
/// <reference path="../.astro/types.d.ts" />

Plugin Typescript pour les éditeurs

Titre de la section Plugin Typescript pour les éditeurs

Le plugin d’Astro pour TypeScript peut être installé séparément si vous n’utilisez pas l’extension officielle d’Astro sur VSCode. Ce plugin est automatiquement installé et configuré par l’extension VSCode, et vous n’avez pas besoin d’installer les deux. Ce plugin 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 plugin supporte également l’importation de fichiers .astro à partir de fichiers .ts (ce qui peut être utile pour la réexportation).

npm

npm install @astrojs/ts-plugin

pnpm

pnpm add @astrojs/ts-plugin

Yarn

yarn add @astrojs/ts-plugin

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

tsconfig.json

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

Pour vérifier que le plugin 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

Titre de la section 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

Titre de la section 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 bundler d’Astro peut essayer de bundler 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. Mettez verbatimModuleSyntax à 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 presets.

tsconfig.json

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

Alias d’importation

Titre de la section Alias d’importation

Astro supporte 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.

src/pages/about/nate.astro

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

tsconfig.json

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

Extension de window et de globalThis

Titre de la section 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 :

src/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 :

src/env.d.ts

interface Window {
  myFunction(): boolean;
}

Les props de composants

Titre de la section 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 VSCode recherchera automatiquement l’interface Props et vous fournira le support TS approprié lorsque vous utiliserez ce composant dans un autre template.

src/components/HelloProps.astro

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

Modèles courants de typage des props

Titre de la section Modèles courants de typage des props

• Si votre composant ne prend pas de propriété ou de contenu slotté, 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

Titre de la section Utilitaires de type

Ajouté à la version : astro@1.6.0

Astro est livré avec quelques types d’utilitaires 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

Titre de la section 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.

src/components/Link.astro

---
import type { HTMLAttributes } from 'astro/types';
// utilisez 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.

src/custom-attributes.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

Titre de la section Type ComponentProps

Ajouté à la version : astro@4.3.0

Cette exportation de type vous permet de référencer les Props acceptés par un autre composant, même si ce composant n’exporte pas directement ce type de 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 /> :

src/pages/index.astro

---
import type { ComponentProps } from 'astro/types';

import Button from "./Button.astro";

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

Type polymorphe

Titre de la section Type polymorphe

Ajouté à la version : astro@2.5.0

Astro inclut une aide pour faciliter la construction de composants qui peuvent être rendus comme différents éléments HTML avec une sécurité de type 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 getStaticPaths().

Titre de la section Inférer les types getStaticPaths().

Ajouté à la version : astro@2.1.0

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

Vous pouvez obtenir le type de Astro.params avec InferGetStaticParamsType et le type de Astro.props avec InferGetStaticPropsType :

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

Vérification des types

Titre de la section Vérification des types

Pour voir les erreurs de type dans votre éditeur, assurez-vous que vous avez installé l’extension [Astro VS Code] (/fr/editor-setup/). 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, changez votre script “build” dans package.json par ce qui suit :

package.json

  "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.

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

En savoir plus sur la configuration de TypeScript.

Résolution des problèmes

Titre de la section Résolution des problèmes

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

Titre de la section 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 à react (par défaut), preact ou solid-js en fonction du framework que vous utilisez le plus. Ensuite, utilisez un pragma comment à l’intérieur de tout fichier conflictuel provenant d’un framework différent.

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

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

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