본문으로 건너뛰기
버전: Canary 🚧

타입스크립트 지원

도큐사우루스는 타입스크립트로 작성됐으며 최고 수준의 타입스크립트 지원을 제공합니다.

The minimum required version is TypeScript 5.0.

초기화

도큐사우루스는 타입스크립트 테마 컴포넌트를 작성하고 사용하는 것을 지원합니다. 초기화 템플릿에서 타입스크립트 변형을 사용하는 경우 --typescript 플래그를 사용하면 타입스크립트를 지원하도록 사이트를 직접 초기화할 수 있습니다.

npx create-docusaurus@latest my-website classic --typescript

아래 내용은 기존 프로젝트를 타입스크립트로 마이그레이션하는 방법에 대한 가이드입니다.

설치하기

Add the following packages to your project:

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

프로젝트 루트에 아래와 같은 내용으로 작성한 tsconfig.json 파일을 추가합니다.

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

도큐사우루스에서는 프로젝트 컴파일 시 tsconfig.json 파일을 사용하지는 않습니다. 파일을 추가하면 좀 더 나은 개발 경험을 더할 수 있습니다. 물론 코드를 작성하거나 CI 동작 시 tsc 타입 체크를 할 수 있도록 직접 선택할 수도 있습니다.

이제 타입스크립트 테마 컴포넌트를 작성할 수 있습니다.

설정 파일 작성하기

It is possible to use a TypeScript config file in Docusaurus.

docusaurus.config.ts
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:

기본적으로 도큐사우루스의 타입스크립트 설정은 자바스크립트 파일에 대한 타입 체크는 하지 않습니다.

// @ts-check 주석을 명시하면 npx tsc 명령 실행 시 설정 파일이 올바르게 타입 체크를 하고 있는지 확인합니다.

docusaurus.config.js
// @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;

타입 어노테이션은 매우 유용하며 IDE에서 설정 오브젝트 타입을 이해하는데 도움이 됩니다!

최고의 IDE(VS Code, 웹스톰, 인텔리제이...)에서 멋진 자동 완성 경험을 제공합니다.

타입스크립트 테마 컴포넌트 활용하기

테마에서 타입스크립트 테마 컴포넌트를 지원하기 위해서는 타입스크립트 소스 코드를 얻기 위한 swizzle 명령어 끝부분에 --typescript 플래그를 추가하기만 하면 됩니다. 예를 들어 다음 명령은 src/theme/Footer 디렉터리 안에 index.tsx, styles.module.css 파일을 생성합니다.

npm run swizzle @docusaurus/theme-classic Footer -- --typescript

공식적으로 지원하는 도큐사우루스 테마는 theme-classic, theme-live-codeblock, theme-search-algolia입니다. 여러분이 만든 도큐사우루스 테마 패키지에서 타입스크립트를 지원하고자 한다면 Lifecycle APIs docs 문서를 참고하세요.