🏠 Backstage 프로젝트 구조 파헤치기: 브라우저용 웹 앱은 어디에 있을까?

안녕하세요! 오늘은 Backstage를 커스터마이징하거나 플러그인을 추가할 때 가장 먼저 파악해야 할 핵심 정보, 바로 프로젝트 구조에 대해 상세히 알아보겠습니다. 🚀

Backstage는 수많은 패키지가 하나로 묶인 모노레포(Monorepo) 구조를 가지고 있습니다. 처음 프로젝트를 생성하고 나면 수많은 폴더 사이에서 "도대체 사용자가 접속했을 때 보는 화면(웹 앱) 코드는 어디에 있는 거지?"라는 의문이 생기기 마련이죠. 오늘 그 궁금증을 완벽히 해결해 드립니다! 💡

---

📍 정답: 웹 앱의 보금자리, packages/app

Backstage 기본 프로젝트 구조에서 사용자의 브라우저에 표시되는 프론트엔드 웹 앱은 바로 다음 경로에 위치합니다.

📂 /packages/app

 

Backstage는 백엔드(packages/backend)와 프론트엔드(packages/app)가 명확히 분리된 구조를 가지고 있습니다. 우리가 브라우저를 통해 접속하는 모든 UI와 페이지 구성은 이 app 폴더 내에서 이루어집니다.

---

🔍 packages/app 폴더 내부 들여다보기 🕵️‍♂️

단순히 위치만 아는 것으로는 부족하겠죠? packages/app 폴더 안이 어떻게 구성되어 있는지 상세히 살펴봅시다.

1. src/App.tsx (메인 관문) 🚪

이 파일은 Backstage 프론트엔드의 심장입니다.

• 모든 라우팅(Routing) 설정이 이곳에서 관리됩니다.
• 어떤 플러그인이 어떤 URL 경로(/catalog, /docs 등)에 표시될지를 정의합니다.
• 사이드바 메뉴 구성과 앱의 전체적인 테마를 연결하는 곳이기도 합니다.

2. src/components/ (UI 조립 블록) 🧩

이곳에는 앱 전반에서 사용되는 UI 구성 요소들이 들어 있습니다.

• Root.tsx: 사이드바(Sidebar)의 로고나 메뉴 구성을 변경하고 싶다면 이 파일을 수정해야 합니다.
• catalog/EntityPage.tsx: 서비스 상세 페이지의 레이아웃(어떤 카드를 배치할지 등)을 결정하는 매우 중요한 파일입니다.

3. public/ (정적 자원) 🖼️

브라우저에서 직접 접근할 수 있는 정적 파일들이 보관됩니다.

• favicon.ico, index.html, 그리고 로고 이미지 파일 등이 위치합니다.

---

🏗️ 왜 하필 packages/ 아래에 있나요? (모노레포의 마법)

Backstage가 packages/app과 packages/backend로 나누어진 이유는 확장성 때문입니다.

• 관심사의 분리: 프론트엔드 개발자는 app 폴더 내의 React 코드에만 집중하고, 백엔드 개발자는 backend 폴더 내의 Node.js 로직에 집중할 수 있습니다. 🛠️
• 플러그인 아키텍처: Backstage는 수많은 외부 플러그인을 조립하여 완성됩니다. app 패키지는 이러한 플러그인들의 UI를 한데 모아 보여주는 컨테이너 역할을 합니다. 📦
• 독립적 빌드: 필요에 따라 프론트엔드와 백엔드를 독립적으로 빌드하거나 배포할 수 있는 유연성을 제공합니다. 🏎️

---

💡 실전 팁: UI를 수정하고 싶을 때의 체크리스트

만약 여러분이 Backstage의 화면을 바꾸고 싶다면 다음 순서를 기억하세요!

1. 사이드바 아이콘이나 메뉴를 바꾸고 싶다? ➡️ packages/app/src/components/Root.tsx
2. 새로운 플러그인 페이지를 추가하고 싶다? ➡️ packages/app/src/App.tsx에서 Route 추가
3. 카탈로그 상세 화면의 탭을 조정하고 싶다? ➡️ packages/app/src/components/catalog/EntityPage.tsx
4. 브라우저 탭의 이름이나 아이콘을 바꾸고 싶다? ➡️ packages/app/public/index.html

---

🏁 결론: 모든 UI의 시작은 packages/app

Backstage라는 거대한 시스템에서 사용자와 만나는 최전선은 바로 **packages/app**입니다. 이 구조를 이해하는 것만으로도 여러분은 Backstage 커스터마이징의 50%는 성공한 것이나 다름없습니다! 🚀

이제 망설이지 말고 packages/app 폴더를 열어 여러분만의 멋진 개발자 포털을 그려보세요. 🎨

---