메인 컨텐츠로 이동
버전: Canary 🚧

타입스크립트 지원

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

초기화​

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

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

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

설치하기​

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

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

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

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

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

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

설정 파일 작성하기​

직접 자바스크립트로 컴파일하지 않는 한 도큐사우루스에서 타입스크립트 설정 파일을 사용하는 것은 불가능합니다.

아래와 같이 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;
팁

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

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

정보

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

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

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

테마에서 타입스크립트 테마 컴포넌트를 지원하기 위해서는 타입스크립트 소스 코드를 얻기 위한 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 문서를 참고하세요.