Aller au contenu principal
Version : 2.4.0

Support TypeScript

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

Initialization

Docusaurus prend en charge l'écriture et l'utilisation de composants de thèmes TypeScript. If the init template provides a TypeScript variant, you can directly initialize a site with full TypeScript support by using the --typescript flag.

npx [email protected] my-website classic --typescript

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

Setup

To start using TypeScript, add @docusaurus/module-type-aliases and the base TS config to your project:

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

Then add tsconfig.json to your project root with the following content:

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

Docusaurus doesn't use this tsconfig.json to compile your project. It is added just for a nicer Editor experience, although you can choose to run tsc to type check your code for yourself or on CI.

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

Typing the config file

It is not possible to use a TypeScript config file in Docusaurus unless you compile it yourself to JavaScript.

We recommend using JSDoc type annotations:

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 !

The best IDEs (VS Code, WebStorm, IntelliJ...) will provide a nice auto-completion experience.

info

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

The // @ts-check comment ensures the config file is properly type-checked when running npx tsc.

Swizzling TypeScript theme components

For themes that support TypeScript theme components, you can add the --typescript flag to the end of the swizzle command to get TypeScript source code. For example, the following command will generate index.tsx and styles.module.css into src/theme/Footer.

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

All official Docusaurus themes support TypeScript theme components, including theme-classic, theme-live-codeblock, and theme-search-algolia. If you are a Docusaurus theme package author who wants to add TypeScript support, see the Lifecycle APIs docs.