Aller au contenu principal
Version: 2.0.0-beta.9 🚧

Support TypeScript

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

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.

npm init [email protected] my-website classic -- --typescript

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

Configuration

Pour commencer à utiliser TypeScript, ajoutez @docusaurus/module-type-aliases et la configuration de base TS à votre projet :

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

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

tsconfig.json
{
"extends": "@tsconfig/docusaurus/tsconfig.json",
"include": ["src/"]
}

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 n'est pas possible d'utiliser un fichier de configuration TypeScript dans Docusaurus, sauf si vous le compilez vous-même en JavaScript.

Nous recommandons d'utiliser des annotations de type JSDoc :

docusaurus.config.js
// @ts-check

/** @type {import('@docusaurus/types').Plugin} */
function MyPlugin(context, options) {
return {
name: 'my-plugin',
};
}

/** @type {import('@docusaurus/types').Config} */
const config = {
title: 'Docusaurus',
tagline: 'Créez rapidement des sites Web optimisés et concentrez-vous sur votre contenu',
organizationName: 'facebook',
projectName: 'docusaurus',
plugins: [MyPlugin],
presets: [
[
'@docusaurus/preset-classic',
/** @type {import('@docusaurus/preset-classic').Options} */
({
docs: {
path: 'docs',
sidebarPath: 'sidebars.js',
},
blog: {
path: 'blog',
postsPerPage: 5,
},
}),
],
],
themeConfig:
/** @type {import('@docusaurus/preset-classic').ThemeConfig} */
({
colorMode: {
defaultMode: 'dark',
},
navbar: {
hideOnScroll: true,
title: 'Docusaurus',
logo: {
alt: 'Docusaurus Logo',
src: 'img/docusaurus.svg',
srcDark: 'img/docusaurus_keytar.svg',
},
},
}),
};

module.exports = config;
astuce

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

Les meilleurs IDEs (VSCode, WebStorm, Intellij...) fourniront une agréable auto-complétion.

info

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 :

npm run tsc

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 swizzling 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

Pour le moment, le seul thème officiel de Docusaurus supportant les composants de thèmes TypeScript est @docusaurus/theme-classic. Si vous êtes un auteur de package de thème Docusaurus voulant ajouter le support TypeScript, consulter la documentation des API du cycle de vie.