TypeScript Support
Docusaurus is written in TypeScript and provides first-class TypeScript support.
The minimum required version is TypeScript 5.1.
Initialization
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
Below are some guides on how to migrate an existing project to TypeScript.
Setup
Add the following packages to your project:
- npm
- Yarn
- pnpm
npm install --save-dev typescript @docusaurus/module-type-aliases @docusaurus/tsconfig @docusaurus/types
yarn add --dev typescript @docusaurus/module-type-aliases @docusaurus/tsconfig @docusaurus/types
pnpm add --save-dev typescript @docusaurus/module-type-aliases @docusaurus/tsconfig @docusaurus/types
Then add tsconfig.json
to your project root with the following content:
{
"extends": "@docusaurus/tsconfig",
"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.
Now you can start writing TypeScript theme components.
Typing the config file
It is possible to use a TypeScript config file in Docusaurus.
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;
It is also possible to use JSDoc type annotations within a .js
file:
By default, the Docusaurus TypeScript config does not type-check JavaScript files.
The // @ts-check
comment ensures the config file is properly type-checked when running npx tsc
.
// @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;
Type annotations are very useful and help your IDE understand the type of config objects!
The best IDEs (VS Code, WebStorm, IntelliJ...) will provide a nice auto-completion experience.
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
- 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
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.