Aller au contenu principal
Version : Canary 🚧

Support TypeScript

Docusaurus est écrit en TypeScript et fournit un support TypeScript de première classe.

The minimum required version is TypeScript 5.1.

Initialisation​

Docusaurus prend en charge l'écriture et l'utilisation de composants de thèmes TypeScript. Si le modèle d'initialisation fournit une variante TypeScript, vous pouvez directement initialiser un site avec une prise en charge complète de TypeScript en utilisant l'option --typescript.

npx create-docusaurus@latest my-website classic --typescript

Voici quelques guides sur la façon de migrer un projet existant vers TypeScript.

Configuration​

Ajoutez les paquets suivants à votre projet :

npm install --save-dev typescript @docusaurus/module-type-aliases @docusaurus/tsconfig @docusaurus/types

Ensuite, ajoutez tsconfig.json à la racine de votre projet avec le contenu suivant :

tsconfig.json
{
  "extends": "@docusaurus/tsconfig",
  "compilerOptions": {
    "baseUrl": "."
  }
}

Docusaurus n'utilise pas ce tsconfig.json pour compiler votre projet. Il est ajouté juste pour une expérience plus agréable de l'éditeur, bien que vous puissiez choisir d'exécuter tsc pour vérifier votre code pour vous-même ou sur le CI.

Maintenant vous pouvez commencer à écrire des composants de thèmes TypeScript.

Saisir le fichier de configuration​

Il est possible d'utiliser un fichier de config TypeScript dans Docusaurus.

docusaurus.config.ts
import type {Config} from '@docusaurus/types';
import type * as Preset from '@docusaurus/preset-classic';

const config: Config = {
  title: 'Mon Site',
  favicon: 'img/favicon.ico',

  /* Votre config de site ici */

  presets: [
    [
      'classic',
      {
        /* Votre config de preset ici */
      } satisfies Preset.Options,
    ],
  ],

  themeConfig: {
    /* Votre config de thème ici */
  } satisfies Preset.ThemeConfig,
};

export default config;
Il est également possible d'utiliser des annotations de type JSDoc dans un fichier .js :

Par défaut, la configuration de Docusaurus TypeScript ne vérifie pas les fichiers JavaScript.

Le commentaire // @ts-check garantit que le fichier de configuration est correctement vérifié lors de l'exécution de npx tsc.

docusaurus.config.js
// @ts-check

/** @type {import('@docusaurus/types').Config} */
const config = {
  tagline: 'Les dinosaures sont sympas',
  favicon: 'img/favicon.ico',

  /* Votre config de site ici */

  presets: [
    [
      '@docusaurus/preset-classic',
      /** @type {import('@docusaurus/preset-classic').Options} */
      (
        {
          /* Votre config de preset ici */
        }
      ),
    ],
  ],
  themeConfig:
    /** @type {import('@docusaurus/preset-classic').ThemeConfig} */
    (
      {
        /* Votre config de thème ici */
      }
    ),
};

export default config;
astuce

Les annotations de type sont très utiles et aident votre IDE à comprendre le type d'objets de configuration !

Les meilleurs IDEs (VS Code, WebStorm, IntelliJ...) fourniront une agréable auto-complétion.

Swizzler les composants de thème TypeScript​

Pour les thèmes supportant les composants de thèmes TypeScript, vous pouvez ajouter le paramètre --typescript à la fin de la commande swizzle pour obtenir le code source TypeScript. Par exemple, la commande suivante générera index.tsx et styles.module.css dans src/theme/Footer.

npm run swizzle @docusaurus/theme-classic Footer -- --typescript

Tous les thèmes officiels de Docusaurus prennent en charge les composants de thème TypeScript, notamment theme-classic, theme-live-codeblock, et theme-search-algolia. Si vous êtes un auteur de package de thème Docusaurus et que vous souhaitez ajouter la prise en charge de TypeScript, consultez la docs Lifecycle APIs.