Skip to main content
Version: 3.0.1

TypeScript 支持


Docusaurus 用 TypeScript 编写，并提供一流的 TypeScript 支持。

英Docusaurus is written in TypeScript and provides first-class TypeScript support.

所需的最低版本是 TypeScript 5.0。

英The minimum required version is TypeScript 5.0.

初始化​

Docusaurus 支持编写和使用 TypeScript 主题组件。 如果 init 模板提供 TypeScript 变体，你可以使用 --typescript 标志直接初始化具有完整 TypeScript 支持的站点。

英Docusaurus supports writing and using TypeScript theme components. If the init template provides a TypeScript variant, you can directly initialize a site with full TypeScript support by using the --typescript flag.

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

以下是有关如何将现有项目迁移到 TypeScript 的一些指南。

英Below are some guides on how to migrate an existing project to TypeScript.

设置​

将以下包添加到你的项目中：

英Add the following packages to your project:

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

然后将 tsconfig.json 添加到项目根目录，内容如下：

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

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

Docusaurus 不使用此 tsconfig.json 来编译你的项目。 添加它只是为了获得更好的编辑器体验，尽管你可以选择运行 tsc 来为自己或在 CI 上类型检查你的代码。

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

现在你可以开始编写 TypeScript 主题组件。

英Now you can start writing TypeScript theme components.

键入配置文件​

可以在 Docusaurus 中使用 TypeScript 配置文件。

英It is possible to use a TypeScript config file in Docusaurus.

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

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

  /* Your site config here */

  presets: [
    [
      'classic',
      {
        /* Your preset config here */
      } satisfies Preset.Options,
    ],
  ],

  themeConfig: {
    /* Your theme config here */
  } satisfies Preset.ThemeConfig,
};

export default config;
也可以在 .js 文件中使用 JSDoc 类型注释：

默认情况下，Docusaurus TypeScript 配置不会对 JavaScript 文件进行类型检查。

英By default, the Docusaurus TypeScript config does not type-check JavaScript files.

// @ts-check 注释确保在运行 npx tsc 时对配置文件进行正确的类型检查。

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

docusaurus.config.js
// @ts-check

/** @type {import('@docusaurus/types').Config} */
const config = {
  tagline: 'Dinosaurs are cool',
  favicon: 'img/favicon.ico',

  /* Your site config here */

  presets: [
    [
      '@docusaurus/preset-classic',
      /** @type {import('@docusaurus/preset-classic').Options} */
      (
        {
          /* Your preset config here */
        }
      ),
    ],
  ],
  themeConfig:
    /** @type {import('@docusaurus/preset-classic').ThemeConfig} */
    (
      {
        /* Your theme config here */
      }
    ),
};

export default config;
提示

类型注释非常有用，可以帮助你的 IDE 了解配置对象的类型！

英Type annotations are very useful and help your IDE understand the type of config objects!

最好的 IDE（VS Code、WebStorm、IntelliJ...）将提供良好的自动补齐体验。

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

Swizzling TypeScript 主题组件​

对于支持 TypeScript 主题组件的主题，你可以在 swizzle 命令末尾添加 --typescript 标志来获取 TypeScript 源代码。 例如，以下命令将把 index.tsx 和 styles.module.css 生成为 src/theme/Footer。

英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

所有官方 Docusaurus 主题都支持 TypeScript 主题组件，包括 theme-classic、theme-live-codeblock 和 theme-search-algolia。 如果你是 Docusaurus 主题包作者，想要添加 TypeScript 支持，请参阅 生命周期 API 文档。

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