第19章 Docusaurus TypeScript 支持指南

版本：2.xTypeScript 支持 Docusaurus 使用 TypeScript 编写，对 TypeScript 提供一流支持。 初始化​ Docusaurus 支持编写和使用 TypeScript 主题组件。如果 init 模板提供了 TypeScript 变体，你可以通过 --typescript 标志直接初始化一个完全支持 TypeScript 的站点。 npx create-docusaurus@latest my-website classic --typescript
下面是一些将现有项目迁移到 TypeScript 的指南。 配置​ 要开始使用 TypeScript，请在项目中添加 @docusaurus/module-type-aliases 和基础 TS 配置： npmYarnpnpmBunnpm 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
bun add --dev typescript @docusaurus/module-type-aliases @tsconfig/docusaurus
然后在项目根目录添加内容如下的 tsconfig.json： tsconfig.json{
"extends": "@tsconfig/docusaurus/tsconfig.json",
"compilerOptions": {
"baseUrl": "."
}
}
Docusaurus 不会用这个 tsconfig.json 来编译你的项目，它只是为了让编辑器体验更好。当然，你也可以选择在本地或 CI 上运行 tsc 来做类型检查。 现在就可以开始编写 TypeScript 主题组件了。 为配置文件添加类型​ Docusaurus 无法直接使用 TypeScript 配置文件，除非你自己先把它编译成 JavaScript。 我们推荐使用 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: 'Build optimized websites quickly, focus on your content',
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} */
```typescript module.exports = config; ``` 在配置对象上使用 tipType 注解非常有用，它能帮助 IDE 识别配置对象的类型。主流 IDE（如 VS Code、WebStorm、IntelliJ）会因此提供出色的自动补全体验。 默认情况下，Docusaurus 的 TypeScript 配置不对 JavaScript 文件进行类型检查。`// @ts-check` 注释可确保在运行 `npx tsc` 时对配置文件进行正确的类型检查。 “Swizzling” TypeScript 主题组件 对于支持 TypeScript 主题组件的主题，可在 `swizzle` 命令末尾添加 `--typescript` 标志以生成 TypeScript 源码。例如，以下命令会在 `src/theme/Footer` 目录下生成 `index.tsx` 和 `styles.module.css`： ```bash npm run swizzle @docusaurus/theme-classic Footer -- --typescript yarn swizzle @docusaurus/theme-classic Footer --typescript pnpm run swizzle @docusaurus/theme-classic Footer --typescript bun run swizzle @docusaurus/theme-classic Footer --typescript ``` Docusaurus 的所有官方主题均支持 TypeScript 主题组件，包括 `theme-classic`、`theme-live-codeblock` 和 `theme-search-algolia`。如果你是 Docusaurus 主题包作者并希望添加 TypeScript 支持，请参阅生命周期 API 文档。