Backstage 플러그인 개발 최적화! 프론트와 백엔드 사이의 '코드 공유' 완벽 전략

Backstage 플러그인을 개발하다 보면 "프론트엔드에서 쓰는 이 TypeScript 인터페이스, 백엔드에서도 똑같이 필요한데 어떡하지?"라는 고민에 빠지게 됩니다.

 

두 패키지 사이에 코드를 중복해서 작성하는 것은 DRY(Don't Repeat Yourself) 원칙에 어긋날 뿐만 아니라, 한쪽만 수정했을 때 발생하는 런타임 에러의 주범이 되기도 하죠. Backstage 유지보수 팀이 권장하는 '공통 라이브러리 패키지' 접근법을 지금 바로 공개합니다! 🛠️

 

---

1. 권장 솔루션: common 패키지 분리 📦

Backstage 아키텍처에서 프론트엔드(-frontend)와 백엔드(-backend) 모두가 참조해야 하는 코드가 있다면, 별도의 **공통 패키지(Common Package)**를 만드는 것이 정석입니다.

보통 다음과 같은 명명 규칙을 사용합니다:

• 프론트엔드: plugins/my-plugin
• 백엔드: plugins/my-plugin-backend
• 공통: plugins/my-plugin-common ✨

---

2. 왜 이렇게 해야 할까요? (이점 분석) 💡

1. 타입 안전성(Type Safety): API 요청/응답 구조를 인터페이스로 정의하여 공유하면, 프론트와 백엔드 간의 데이터 규격이 항상 일치함을 보장할 수 있습니다.
2. 번들 크기 최적화: 백엔드 전용 라이브러리가 프론트엔드 번들에 포함되는 것을 방지합니다.
3. 순환 참조 방지: 프론트엔드가 백엔드를 참조하거나 그 반대의 상황이 발생하지 않도록 의존성 구조를 깔끔하게 유지합니다. 🛡️

---

3. 공통 패키지에 담아야 할 내용들 📂

보통 다음과 같은 코드들이 common 패키지의 단골 손님입니다.

• API 엔터티 및 인터페이스: 서버와 클라이언트가 주고받는 JSON 데이터의 형태.
• 권한 정의 (Permissions): Backstage 권한 시스템에서 사용하는 권한 객체들.
• 상수(Constants): 플러그인 ID, 특정 에러 코드, 라우팅 경로 등.
• 범용 유틸리티: 날짜 계산, 문자열 처리 등 환경(Node.js vs Browser)에 구애받지 않는 순수 함수들.

---

4. 실전! 단계별 구축 가이드 🛠️

1단계: 패키지 생성

Backstage CLI를 사용하여 새로운 공통 패키지를 생성하거나, 기존 구조를 본떠 plugins/my-plugin-common 디렉토리를 만듭니다.

2단계: package.json 설정

이 패키지는 어디서든 임포트할 수 있도록 적절한 이름과 메타데이터를 가져야 합니다.

3단계: 의존성 추가 (Dependency)

프론트엔드와 백엔드의 package.json에 우리가 만든 공통 패키지를 추가합니다.

JSON

// plugins/my-plugin/package.json (Frontend)
"dependencies": {
  "@internal/backstage-plugin-my-plugin-common": "workspace:^"
}

// plugins/my-plugin-backend/package.json (Backend)
"dependencies": {
  "@internal/backstage-plugin-my-plugin-common": "workspace:^"
}

---

5. 주의사항: 브라우저와 노드 사이의 균형 ⚖️

공통 패키지를 작성할 때 가장 주의해야 할 점은 **"환경 중립성"**입니다.

• 금지: fs, path 같은 Node.js 전용 모듈 사용 (프론트엔드에서 에러 발생)
• 금지: window, document 같은 브라우저 전용 API 사용 (백엔드에서 에러 발생)
• 권장: 순수 TypeScript 코드와 환경을 타지 않는 범용 라이브러리만 사용하세요.

---

🏁 마무리하며

Backstage 플러그인의 복잡도가 높아질수록 common 패키지의 가치는 빛을 발합니다. 코드 중복은 줄이고, 타입 안전성은 높이는 이 전략은 대규모 플랫폼 팀이 Backstage를 안정적으로 운영하는 핵심 비결이기도 하죠. 🌟

지금 개발 중인 플러그인이 있다면, 오늘 바로 common 패키지를 도입해 보는 건 어떨까요?

---

태그: Backstage, PluginDevelopment, CodeSharing, TypeScript, Architecture, Frontend, Backend, SoftwareEngineering