docusaurus로 우리 팀만의 문서 사이트 만들기 (1)

발단

회사에서 업무를 하던 중,팀의 공통 컴포넌트나 코드 컨벤션애 대해서 tailwind css나 vite 처럼 보기 쉬운 docs가 있으면 좋겠다고 생각했다.팀에는 디자인 시스템을 storybook으로 문서를 만들어놓아서 편하게 쓰고 있다.하지만 디자인시스템에 들어가지 않는 프론트엔트 팀 내부에서 쓰는 common 컴포넌트 라든지 다양한 규칙들이 해당 프로젝트를 주되게 한 사람이 아니면 히스토리 파악이 어려운 문제가 있었다.
이때 메타에서 개발한 Docusaurus 를 발견했다. Docusaurus에 대한 설명은 다른 포스팅에서 하고 여기서는 개발 일지를 써보도록 하겠다.

목표

내가 하려는 것은 아래와 같다.

turbo repo를 사용하고 있는 프로젝트에
packages에 common이라는 패키지가 있는데
docusaurus에 common 패키지에 있는 컴포넌트를 import 하여 컴포넌트를 보여주고
상세 설명을 넣어 docs를 만든다.
그리고 된다면 누구나 코드를 수정하지 않고 직접 글쓰기를 하여 docs를 만들 수 있도록 하는 기능도 추가하고 싶다.
기능을 쉽게 찾을 수 있게 search 기능도 추가하고 싶다.

시작

1. apps 안에 새로운 docusaurus앱 만들기

npx create-docusaurus@latest component-docs classic

2. 실행해보기

일단 먼저 yarn start로 실행을 해보았다.

이런 에러가 났다. 이 에러는 react-router-dom 6버전에서 나는 에러로,"@docusaurus/core” 내부 코드를 보니 5.3.4 버전을 쓰고 있어서 생긴 문제이다. 이 경우 root의 버전을 지우고 common-docs안에서 라우트를 설치하면 실행은 이제 정상적으로 된다.

-> 근데 이 부분은 root 버전을 지우면 다른 프로젝트에 영향이 가기 때문에 다른 방법을 생각해봐야하는데 일단 급한 불만 껐다.

이런 페이지가 나오면 정상적으로 작동된 것이다.

3. common package에서 컴포넌트 import 하기

  "dependencies": {
	"@myTurboRepo/common": "workspace:*",
    ...
    }

package.json에 dependencies에 팀에서 만든 패키지를 넣어주고 index.tsx파일에 import 한다.

테스트로 만든 컴포넌트가 잘 노출되는 것을 확인했다.

4. react-live설치

react-live는 코드와 데모를 한눈에 보여줄 수 있는 라이브러리이다.

//src/components/live-demo.tsx

import { SsmTestText } from '@myTurboRepo/common';
import { themes } from 'prism-react-renderer';
import React from 'react';
import { LiveProvider, LiveEditor, LiveError, LivePreview } from 'react-live';

const code = `<SsmTestText/>`;

const scope = { React, SsmTestText };

export default function LiveDemo() {
	return (
		<div style={{ border: '1px solid #ddd', borderRadius: 8, padding: 16 }}>
			<LiveProvider
				code={code}
				scope={scope}
				language="tsx"
				theme={themes.nightOwl}>
				<LiveEditor
					style={{ fontSize: 14, backgroundColor: '#282c34', color: '#fff' }}
				/>
				<LiveError style={{ color: 'red' }} />
				<div style={{ marginTop: 16 }}>
					<LivePreview />
				</div>
			</LiveProvider>
		</div>
	);
}

이렇게 LiveDemo 코드를 만들고

//docs/common/test.mdx
import LiveDemo from '@site/src/components/live-demo';

# MyButton 컴포넌트 예시

<LiveDemo />

이런식으로 만들면 화면에서 확인할 수 있다. 이제 기본적으로 세팅은 끝났으니 다음 포스팅부터 구체적으로 어떻게 docusaurus를 사용해야하는지와 docs를 구성할 것인지 알아보자!