How to Use Docusaurus with TypeScript for Development

Docusaurus provides first-class TypeScript support that allows you to write your entire site configuration in .ts files, importing typed APIs from @docusaurus/types for compile-time safety and enhanced IDE autocompletion.

The facebook/docusaurus repository ships with native TypeScript capabilities, enabling developers to build documentation sites with strict type checking. By using Docusaurus with TypeScript, you can leverage typed configuration files, catch errors during development, and improve maintainability across your project.

Setting Up a TypeScript Docusaurus Project

Converting a Docusaurus site to TypeScript requires minimal changes. The framework automatically detects and compiles TypeScript sources without additional build configuration.

Initialize the Site

Start by creating a new site using the classic template. Run the following command to generate the JavaScript skeleton:

yarn create docusaurus@latest my-site classic

This creates a standard project structure with .js configuration files that you will convert to TypeScript in the next steps.

Convert Configuration Files to TypeScript

Rename the core configuration files to use the .ts extension. This enables the TypeScript compiler to check your configuration for type errors.

• Rename docusaurus.config.js to docusaurus.config.ts
• Rename sidebars.js to sidebars.ts

After renaming, import the Config type from @docusaurus/types in your configuration file. As implemented in examples/classic-typescript/docusaurus.config.ts, this type validates your site structure against the framework's expected schema.

Configure the TypeScript Compiler

Add a tsconfig.json file to your project root to control compiler behavior. The repository provides a reference implementation in examples/classic-typescript/tsconfig.json that includes optimal settings for Docusaurus development:

{
  "compilerOptions": {
    "target": "ES2020",
    "module": "CommonJS",
    "lib": ["DOM", "ES2020"],
    "allowJs": true,
    "checkJs": false,
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true,
    "resolveJsonModule": true,
    "noEmit": true,
    "jsx": "react"
  },
  "include": ["src", "docusaurus.config.ts", "sidebars.ts"]
}

The skipLibCheck option silences duplicate type errors from bundled typings, while strict mode ensures maximum type safety across your codebase.

Writing Typed Configuration Files

With TypeScript enabled, you can replace untyped JavaScript objects with strictly typed configurations that catch misspelled fields and invalid values before build time.

Typed Site Configuration

In docusaurus.config.ts, import the Config type from @docusaurus/types and the ThemeConfig type from @docusaurus/theme-common. This pattern, demonstrated in examples/classic-typescript/docusaurus.config.ts, provides autocompletion for all site properties:

import type {Config} from '@docusaurus/types';
import type {ThemeConfig} from '@docusaurus/theme-common';

const config: Config = {
  title: 'My TypeScript Docusaurus Site',
  tagline: 'Typed documentation made easy',
  url: 'https://example.com',
  baseUrl: '/',
  favicon: 'img/favicon.ico',
  organizationName: 'my-org',
  projectName: 'my-site',

  themeConfig: {
    navbar: {
      title: 'My Site',
      logo: {src: 'img/logo.svg'},
      items: [
        {to: '/docs/intro', label: 'Docs', position: 'left'},
        {href: 'https://github.com/my-org/my-site', label: 'GitHub', position: 'right'},
      ],
    },
    footer: {
      style: 'dark',
      links: [],
      copyright: `© ${new Date().getFullYear()} My Org`,
    },
  } as ThemeConfig,

  presets: [
    [
      'classic',
      {
        docs: {
          sidebarPath: require.resolve('./sidebars.ts'),
        },
        blog: false,
        theme: {
          customCss: require.resolve('./src/css/custom.css'),
        },
      },
    ],
  ],
};

export default config;

The Config type ensures required fields like url and baseUrl are present, while ThemeConfig validates nested theme-specific properties.

Typed Sidebar Configuration

For documentation sidebars, use the SidebarsConfig type exported from @docusaurus/plugin-content-docs. The examples/classic-typescript/sidebars.ts file demonstrates this approach:

import type {SidebarsConfig} from '@docusaurus/plugin-content-docs';

export const sidebars: SidebarsConfig = {
  tutorialSidebar: [
    {
      type: 'category',
      label: 'Getting Started',
      items: ['intro', 'setup'],
    },
    {
      type: 'category',
      label: 'Guides',
      items: ['guides/usage', 'guides/deployment'],
    },
  ],
};

This type definition prevents invalid sidebar item structures and ensures your items arrays contain valid document IDs.

Development Workflow with TypeScript

Once your files are converted, the standard Docusaurus CLI commands handle TypeScript compilation transparently.

Running the Development Server

Execute yarn start (or npm start) to launch the development server. The framework runs the TypeScript compiler under the hood, displaying type errors in the terminal while maintaining hot-reload functionality. Errors in docusaurus.config.ts or sidebars.ts will prevent the site from starting, catching configuration mistakes immediately.

Building for Production

Run yarn build to compile TypeScript sources, bundle them with Webpack/Rspack, and generate static assets in the build/ directory. The build process references global type declarations in packages/docusaurus/src/common.d.ts to ensure internal consistency across the framework.

Extending with Typed Plugins and Themes

Docusaurus plugins and themes ship with their own TypeScript definitions. When customizing plugin options, import the specific option types to maintain type safety.

For example, when configuring the docs plugin, import PluginOptions from @docusaurus/plugin-content-docs:

import type {PluginOptions as DocsPluginOptions} from '@docusaurus/plugin-content-docs';

These type definitions are maintained in packages/docusaurus-plugin-content-docs/src/types.d.ts, ensuring your plugin configuration matches the expected schema.

Summary

• Docusaurus supports TypeScript natively by recognizing .ts extensions in configuration files and automatically compiling them during development and production builds.
• Type definitions are available in @docusaurus/types, @docusaurus/theme-common, and individual plugin packages for comprehensive IDE support.
• Configuration files require specific types: Use Config for docusaurus.config.ts and SidebarsConfig for sidebars.ts to validate your site structure.
• Reference implementations are located in examples/classic-typescript/ within the facebook/docusaurus repository, providing battle-tested tsconfig.json settings and configuration patterns.
• No manual compilation is necessary—the standard yarn start and yarn build commands handle TypeScript processing transparently.

Frequently Asked Questions

Does Docusaurus require TypeScript to build a site?

No. TypeScript is entirely optional. Docusaurus works out of the box with JavaScript configuration files. However, switching to TypeScript provides compile-time error checking and better autocompletion, which is why the framework exposes first-class types in @docusaurus/types for developers who choose to adopt it.

Can I mix JavaScript and TypeScript files in the same Docusaurus project?

Yes. Docusaurus supports mixed codebases. You can write your configuration files in TypeScript (.ts) while keeping documentation components or pages in JavaScript (.js or .jsx). The tsconfig.json setting "allowJs": true permits JavaScript files to coexist during the TypeScript compilation process.

Where are the TypeScript type definitions located in the Docusaurus repository?

Core type definitions reside in packages/docusaurus/src/common.d.ts, while plugin-specific types are distributed within their respective packages, such as packages/docusaurus-plugin-content-docs/src/types.d.ts. The examples/classic-typescript/ directory contains reference implementations of docusaurus.config.ts, sidebars.ts, and tsconfig.json that demonstrate proper type usage.

Do I need to manually compile TypeScript before running docusaurus build?

No. The Docusaurus CLI handles TypeScript compilation automatically when you run yarn build or yarn start. The framework uses Webpack/Rspack loaders to transpile TypeScript sources on demand during development and as part of the static site generation process for production builds.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}