# How to Use Docusaurus with TypeScript for Development

> Learn to use Docusaurus with TypeScript for development. Write site configs in TS for compile-time safety and great autocompletion with typed APIs from @docusaurus/types.

- Repository: [Meta/docusaurus](https://github.com/facebook/docusaurus)
- Tags: how-to-guide
- Published: 2026-03-04

---

**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:

```bash
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`](https://github.com/facebook/docusaurus/blob/main/docusaurus.config.js) to [`docusaurus.config.ts`](https://github.com/facebook/docusaurus/blob/main/docusaurus.config.ts)
- Rename [`sidebars.js`](https://github.com/facebook/docusaurus/blob/main/sidebars.js) to [`sidebars.ts`](https://github.com/facebook/docusaurus/blob/main/sidebars.ts)

After renaming, import the `Config` type from `@docusaurus/types` in your configuration file. As implemented in [`examples/classic-typescript/docusaurus.config.ts`](https://github.com/facebook/docusaurus/blob/main/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`](https://github.com/facebook/docusaurus/blob/main/tsconfig.json) file to your project root to control compiler behavior. The repository provides a reference implementation in [`examples/classic-typescript/tsconfig.json`](https://github.com/facebook/docusaurus/blob/main/examples/classic-typescript/tsconfig.json) that includes optimal settings for Docusaurus development:

```json
{
  "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`](https://github.com/facebook/docusaurus/blob/main/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`](https://github.com/facebook/docusaurus/blob/main/examples/classic-typescript/docusaurus.config.ts), provides autocompletion for all site properties:

```typescript
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`](https://github.com/facebook/docusaurus/blob/main/examples/classic-typescript/sidebars.ts) file demonstrates this approach:

```typescript
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`](https://github.com/facebook/docusaurus/blob/main/docusaurus.config.ts) or [`sidebars.ts`](https://github.com/facebook/docusaurus/blob/main/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`](https://github.com/facebook/docusaurus/blob/main/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`:

```typescript
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`](https://github.com/facebook/docusaurus/blob/main/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`](https://github.com/facebook/docusaurus/blob/main/docusaurus.config.ts) and `SidebarsConfig` for [`sidebars.ts`](https://github.com/facebook/docusaurus/blob/main/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`](https://github.com/facebook/docusaurus/blob/main/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`](https://github.com/facebook/docusaurus/blob/main/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`](https://github.com/facebook/docusaurus/blob/main/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`](https://github.com/facebook/docusaurus/blob/main/packages/docusaurus-plugin-content-docs/src/types.d.ts). The `examples/classic-typescript/` directory contains reference implementations of [`docusaurus.config.ts`](https://github.com/facebook/docusaurus/blob/main/docusaurus.config.ts), [`sidebars.ts`](https://github.com/facebook/docusaurus/blob/main/sidebars.ts), and [`tsconfig.json`](https://github.com/facebook/docusaurus/blob/main/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.