Backstage에 활력을! TechDocs 완벽 설치 및 Yarn 워크스페이스 설정 가이드

안녕하세요! 오늘은 Backstage의 핵심 기능 중 하나이자 개발자 경험(DevEx)의 꽃이라 불리는 TechDocs(테크독스)를 설치하는 방법에 대해 아주 상세히 알아보겠습니다. 🚀

새로운 Backstage 모노레포를 구축한 뒤, "문서를 코드로(Documentation as Code)" 관리하기 위해 TechDocs를 추가하려고 할 때 어떤 명령어를 어떤 순서로 입력해야 할지 막막하셨죠? Yarn 워크스페이스 환경에서 프론트엔드와 백엔드 패키지를 완벽하게 설치하는 '정석 가이드'를 공개합니다! 💡

---

🏗️ TechDocs 설치, 왜 Yarn 워크스페이스 방식인가요?

Backstage는 기본적으로 모노레포(Monorepo) 구조를 채택하고 있습니다. 프론트엔드(packages/app)와 백엔드(packages/backend)가 분리되어 있기 때문에, 새로운 기능을 추가할 때는 각 패키지의 영역에 맞는 라이브러리를 각각 설치해 주어야 합니다.

이때 Yarn Workspaces 기능을 사용하면 루트 디렉토리에서 각 하위 패키지로 이동하지 않고도 간편하게 설치를 관리할 수 있습니다. 🛠️

---

🌟 TechDocs 설치를 위한 '골든 커맨드' 순서

TechDocs를 활성화하려면 프론트엔드용 플러그인과 백엔드용 플러그인, 이 두 가지를 모두 설치해야 합니다.

1단계: 프론트엔드 패키지 설치 (app) 🎨

먼저 사용자들이 문서를 읽을 수 있는 UI 화면을 구성하기 위한 패키지를 설치합니다.

Bash

yarn workspace app add @backstage/plugin-techdocs

• 의미: app이라는 워크스페이스(packages/app)에 TechDocs 프론트엔드 라이브러리를 추가합니다.

2단계: 백엔드 패키지 설치 (backend) ⚙️

다음으로 문서 데이터를 처리하고 생성하며 제공하는 로직을 담당할 백엔드 패키지를 설치합니다.

Bash

yarn workspace backend add @backstage/plugin-techdocs-backend

• 의미: backend라는 워크스페이스(packages/backend)에 TechDocs 백엔드 처리 로직을 추가합니다.

---

🔍 설치 후 무엇을 해야 하나요? (추가 설정 가이드)

패키지를 설치했다고 해서 바로 문서가 짠! 하고 나타나지는 않습니다. 몇 가지 코드 연결 작업이 필요합니다. 🕵️‍♂️

🛠️ 프론트엔드 연결 (packages/app/src/App.tsx)

설치한 @backstage/plugin-techdocs를 앱의 라우팅에 등록해야 합니다.

TypeScript

// App.tsx 내부 예시
import { TechdocsPage } from '@backstage/plugin-techdocs';

// ... routes 정의 부분
<Route path="/docs" element={<TechdocsPage />} />

🛠️ 백엔드 연결 (packages/backend/src/plugins/techdocs.ts)

최신 Backstage 버전에서는 New Backend System을 사용하는 경우가 많습니다. 이 경우 index.ts 파일에 아래와 같은 한 줄을 추가하는 것만으로 충분합니다.

TypeScript

// packages/backend/src/index.ts
backend.add(import('@backstage/plugin-techdocs-backend/alpha'));

---

💡 실전 팁: TechDocs 작동 원리 이해하기

TechDocs는 내부적으로 MkDocs라는 정적 사이트 생성기를 사용합니다. 📖

1. Preparation: 소스 코드 레포지토리에 있는 Markdown 파일을 긁어옵니다.
2. Generation: MkDocs를 실행하여 HTML로 변환합니다.
3. Storage: 변환된 HTML을 S3나 GCS, 혹은 로컬 파일 시스템에 저장합니다.
4. Visualization: Backstage UI(프론트엔드)가 이 저장된 내용을 불러와서 사용자에게 보여줍니다.

이 과정을 원활하게 하려면 로컬 환경에 Python과 mkdocs-techdocs-core 패키지가 설치되어 있어야 한다는 점, 잊지 마세요! 🐍

---

🏁 결론: 깔끔한 설치가 유지보수의 시작입니다!

Backstage 모노레포에서 TechDocs를 추가할 때는 다음 명령어를 기억하세요.

1. yarn workspace app add @backstage/plugin-techdocs 🎨
2. yarn workspace backend add @backstage/plugin-techdocs-backend ⚙️

이 두 단계를 거치면 여러분의 팀은 이제 코드와 문서를 한곳에서 관리하는 진정한 DevOps 문화에 한 발짝 더 다가서게 됩니다! 🚀

---