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
.
npx create-docusaurus@latest 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
- Yarn
- pnpm
npm install --save-dev typescript @docusaurus/module-type-aliases @tsconfig/docusaurus
yarn add --dev typescript @docusaurus/module-type-aliases @tsconfig/docusaurus
pnpm add --save-dev typescript @docusaurus/module-type-aliases @tsconfig/docusaurus
Ensuite, ajoutez tsconfig.json
à la racine de votre projet avec le contenu suivant :
{
"extends": "@tsconfig/docusaurus/tsconfig.json",
"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.
Saisie du fichier de config
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 vous recommandons d'utiliser des annotations de type JSDoc :
// @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;
Les annotations de type sont très utiles et aident votre IDE à comprendre le type d'objets de configuration !
Les meilleurs IDE (Code VS, WebStorm, IntelliJ...) vous offriront une belle expérience d'auto-complétion.
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
.
Swizzle des 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
- Yarn
- pnpm
npm run swizzle @docusaurus/theme-classic Footer -- --typescript
yarn swizzle @docusaurus/theme-classic Footer --typescript
pnpm run swizzle @docusaurus/theme-classic Footer --typescript
Tous les thèmes officiels de Docusaurus prennent en charge les composants de thème TypeScript, y compris 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 les docs de l'API du cycle de vie.