跳到主要内容

TypeScript 支持

道格龙（Docusaurus） 本身就是用 TypeScript 编写的，并提供了一流的 TypeScript 支持。

所需的最低版本为 TypeScript 5.1。

初始化​

道格龙（Docusaurus） 支持编写和使用 TypeScript 主题组件。如果初始化模板提供了 TypeScript 版本，您可以通过添加 --typescript 标志，直接初始化一个具备完整 TypeScript 支持的网站。

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

下文将指导您如何将一个现有项目迁移到 TypeScript。

环境配置​

请将以下依赖包添加到您的项目中：

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

然后，在您的项目根目录下创建一个 tsconfig.json 文件，并填入以下内容：

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

道格龙（Docusaurus） 并不会使用这个 tsconfig.json 文件来编译您的项目，添加它主要是为了获得更好的编辑器体验（例如代码提示和类型检查）。当然，您也可以自己运行 tsc 命令来对代码进行类型检查，或是在 CI 流程中加入这个步骤。

现在，您可以开始编写 TypeScript 主题组件了。

为配置文件添加类型​

在 道格龙（Docusaurus） 中，您可以使用 TypeScript 格式的配置文件。

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',

  /* 在此配置您的网站 */

  presets: [
    [
      'classic',
      {
        /* 在此配置您的预设 */
      } satisfies Preset.Options,
    ],
  ],

  themeConfig: {
    /* 在此配置您的主题 */
  } satisfies Preset.ThemeConfig,
};

export default config;
您也可以在一个 .js 文件中使用 JSDoc 类型注解

默认情况下，道格龙（Docusaurus） 的 TypeScript 配置不会对 JavaScript 文件进行类型检查。

通过添加 // @ts-check 注释，可以确保在运行 npx tsc 命令时，该配置文件也能被正确地进行类型检查。

docusaurus.config.js
// @ts-check

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

  /* 在此配置您的网站 */

  presets: [
    [
      '@docusaurus/preset-classic',
      /** @type {import('@docusaurus/preset-classic').Options} */
      (
        {
          /* 在此配置您的预设 */
        }
      ),
    ],
  ],
  themeConfig:
    /** @type {import('@docusaurus/preset-classic').ThemeConfig} */
    (
      {
        /* 在此配置您的主题 */
      }
    ),
};

export default config;
提示

类型注解非常有用，它可以帮助您的 IDE 理解配置对象的结构，从而提供强大的自动补全体验。主流的 IDE（如 VS Code、WebStorm、IntelliJ...）都能很好地支持这一点。

Swizzling TypeScript 主题组件​

对于支持 TypeScript 主题组件的主题，您可以在 swizzle 命令的末尾添加 --typescript 标志来获取 TypeScript 源码。例如，下面的命令会在 src/theme/Footer 目录下生成 index.tsx 和 styles.module.css 两个文件。

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

所有官方的 道格龙（Docusaurus） 主题，从 theme-classic、theme-live-codeblock 到 theme-search-algolia，都支持 TypeScript 主题组件。如果您是一位主题包的作者，并希望为您的主题添加 TypeScript 支持，请参阅生命周期 API 文档。