@docusaurus/tsconfig

@docusaurus/tsconfig provides a standardized TypeScript configuration for Docusaurus projects, serving as a shareable TSConfig base that other Docusaurus packages and user projects can extend. It includes sensible defaults for modern JavaScript/TypeScript development with ES2022 target, DOM type definitions, module resolution settings optimized for bundlers, JSX preservation for React components, and path mapping configuration that supports the common '@site/*' alias pattern used in Docusaurus sites.

Package Information

• Package Name: @docusaurus/tsconfig
• Package Type: npm
• Language: TypeScript
• Installation: npm install --save-dev @docusaurus/tsconfig

Core Imports

This package is used via TypeScript's extends configuration, not via import statements:

{
  "extends": "@docusaurus/tsconfig"
}

Basic Usage

Add @docusaurus/tsconfig to your project's tsconfig.json:

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

For a complete Docusaurus TypeScript setup:

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

Capabilities

TypeScript Configuration Extension

Provides a complete, pre-configured TypeScript configuration optimized for Docusaurus projects.

{
  "$schema": "https://json.schemastore.org/tsconfig",
  "display": "Docusaurus",
  "docs": "https://docusaurus.io/docs/typescript-support",
  "compilerOptions": {
    "allowJs": true,
    "esModuleInterop": true,
    "jsx": "preserve",
    "target": "ES2022",
    "lib": ["ES2022", "DOM"],
    "moduleResolution": "bundler",
    "module": "esnext",
    "noEmit": true,
    "baseUrl": ".",
    "paths": {
      "@site/*": ["./*"]
    },
    "skipLibCheck": true
  }
}

Compiler Options Configuration

JavaScript Support

• allowJs: true - Allows importing and processing JavaScript files alongside TypeScript

Module System Configuration

• esModuleInterop: true - Enables interoperability between CommonJS and ES modules
• moduleResolution: "bundler" - Uses bundler-style module resolution optimized for modern bundlers
• module: "esnext" - Uses the latest ES module syntax

JSX and React Support

• jsx: "preserve" - Preserves JSX syntax for processing by bundlers (React support)

Target and Runtime Configuration

• target: "ES2022" - Compiles to ES2022 JavaScript standard
• lib: ["ES2022", "DOM"] - Includes ES2022 and DOM type libraries

Build Configuration

• noEmit: true - Prevents TypeScript from emitting compiled files (type-checking only)

Path Resolution

• baseUrl: "." - Sets base directory for module resolution
• paths: {"@site/*": ["./*"]} - Path mapping for @site/* alias pattern (Docusaurus convention)

Performance Optimization

• skipLibCheck: true - Skips type checking of declaration files for faster compilation

Schema and Documentation Integration

{
  "$schema": "https://json.schemastore.org/tsconfig",
  "display": "Docusaurus",
  "docs": "https://docusaurus.io/docs/typescript-support"
}

• $schema: Provides JSON schema reference for IDE autocomplete and validation
• display: Human-readable display name "Docusaurus" for IDE configuration selection
• docs: Link to official Docusaurus TypeScript documentation

Usage Examples

Basic Project Setup

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

Extended Configuration

{
  "extends": "@docusaurus/tsconfig",
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@site/*": ["./src/*"],
      "@components/*": ["./src/components/*"]
    }
  },
  "include": [
    "src/**/*",
    "docs/**/*"
  ],
  "exclude": [
    "node_modules",
    "build"
  ]
}

Integration with Docusaurus TypeScript Config

// docusaurus.config.ts
import type {Config} from '@docusaurus/types';

const config: Config = {
  title: 'My Site',
  // ... rest of config
};

export default config;

Migration Notes

This package replaces the external @tsconfig/docusaurus package as of Docusaurus v3.0:

- "extends": "@tsconfig/docusaurus/tsconfig.json",
+ "extends": "@docusaurus/tsconfig",

Requirements

• TypeScript: Version 5.1 or higher
• Node.js: Compatible with Docusaurus requirements
• Usage Context: Designed for Docusaurus projects but usable in other React/TypeScript projects