메인 컨텐츠로 이동
Version: 2.0.0-beta.17 🚧

타입스크립트 지원

Docusaurus is written in TypeScript and provides first-class TypeScript support.

초기화

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

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

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

설치하기

타입스크립트를 사용하기 위해서는 프로젝트에 @docusaurus/module-type-aliases와 기본 TS 설정을 추가해주어야 합니다.

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

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

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

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

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

설정 파일 작성하기

It is not possible to use a TypeScript config file in Docusaurus unless you compile it yourself to JavaScript.

아래와 같이 JSDoc 타입 어노테이션을 사용하는 것을 권장합니다.

docusaurus.config.js
// @ts-check

/** @type {import('@docusaurus/types').Plugin} */
function MyPlugin(context, options) {
return {
name: 'my-plugin',
};
}

/** @type {import('@docusaurus/types').Config} */
const config = {
title: 'Docusaurus',
tagline: 'Build optimized websites quickly, focus on your content',
organizationName: 'facebook',
projectName: 'docusaurus',
plugins: [MyPlugin],
presets: [
[
'@docusaurus/preset-classic',
/** @type {import('@docusaurus/preset-classic').Options} */
({
docs: {
path: 'docs',
sidebarPath: 'sidebars.js',
},
blog: {
path: 'blog',
postsPerPage: 5,
},
}),
],
],
themeConfig:
/** @type {import('@docusaurus/preset-classic').ThemeConfig} */
({
colorMode: {
defaultMode: 'dark',
},
navbar: {
hideOnScroll: true,
title: 'Docusaurus',
logo: {
alt: 'Docusaurus Logo',
src: 'img/docusaurus.svg',
srcDark: 'img/docusaurus_keytar.svg',
},
},
}),
};

module.exports = config;
tip

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

The best IDEs (VSCode, WebStorm, IntelliJ...) will provide a nice auto-completion experience.

info

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

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

npm run tsc

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

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. 예를 들어 다음 명령은 src/theme/Footer 디렉터리 안에 index.tsx, styles.module.css 파일을 생성합니다.

npm 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.