BOFIT FE 팀 기술 스택 선정과정 A to Z

[gwagjiug]

저희 BOFIT 팀은 기술 스택을 선정할 때, 유명하거나 유행하는 기술이 아니라 우리 서비스에 가장 fit 한 선택이 무엇인지에 집중하고자 했습니다.

"이게 요즘 트렌드니까"

라는 막연한 선택이 아니라, 우리 팀의 현재 역량과 앞으로의 러닝커브와, WEBJAM 이라는 독특한 환경 등을 고려하여 실제로 우리가 만드는 서비스에 가장 잘 맞는 기술이 무엇인지 근거를 가지고 따져보았습니다.

기술 스택 선정은 늘 여러 선택지가 공존하고, 답이 존재하는 문제 가 아닙니다. 단지 이 글에선 BOFIT 팀이 어떤 기준을 세웠고, 수많은 선택지 중에서 왜 그 길을 택했는지 그 과정을 하나씩 풀어보고자 합니다.

🚀 모노레포(터보레포) : 디자인 시스템의 존재 이유와 Headless UI

출처: Turborepo 공식홈페이지

BOFIT 팀은 이번 프로젝트를 설계하면서 단순히 클라이언트 레포 하나에 컴포넌트들을 모아두는 방식이 아니라,
디자인 시스템을 별도의 패키지로 분리하고 모노레포 구조로 관리하기로 결정했습니다.

왜 굳이 분리할까요?

좋은 컴포넌트를 만드는 것만으로는 훌륭한 UI를 만들 수 없다고 생각했기 때문입니다.
우리는 기능을 먼저 만들고 그 위에 UI를 덧붙이는 방식이 아니라,
UI의 구조와 일관성을 먼저 설계하고 그 위에 기능을 얹는 방식으로 접근하고자 했습니다.

디자인 시스템을 하나의 독립된 패키지로 관리하면,

• 컴포넌트 설계 단계부터 일관성 있는 사고방식을 팀원 모두가 공유할 수 있습니다.
• 실제 구현 단계에서 재사용성과 확장성을 극대화할 수 있습니다.
• 각 서비스 모듈이 디자인 시스템을 가져다 쓰기만 하면 되기 때문에, 브랜드 톤앤매너와 UI 일관성을 쉽게 유지할 수 있습니다.

Headless UI 패턴과의 연결고리

우리가 지향하는 디자인 시스템은 Headless UI 패턴과도 닮아있습니다.

Headless UI는 스타일과 레이아웃을 포함하지 않고, 순수 기능 로직만 제공하는 UI 컴포넌트 라이브러리를 뜻합니다.

예를 들어 캘린더를 만든다고 할 때,

• 날짜 선택, 달력 페이지 전환 같은 핵심 기능만 제공하고,
• 실제 달력의 스타일링은 **사용자(개발자)**가 직접 정의합니다.

이렇게 하면 관심사 분리(Separation of Concerns) 가 이루어집니다.

• 로직은 디자인 시스템 패키지에서 관리하고,
• 스타일링은 각 서비스나 팀에서 자유롭게 적용합니다.

덕분에:

• 각 팀원은 공통 로직에 의존해 일관성을 유지하면서도,
• 자신이 맡은 화면이나 서비스에 맞게 자유롭게 커스터마이즈할 수 있습니다.
• 스타일을 바꾸거나 브랜드 톤을 변경해도 핵심 기능에는 영향이 없습니다.

즉, Headless UI는 우리의 디자인 시스템이 확장성과 유지보수성을 동시에 확보할 수 있는 강력한 무기입니다.

모노레포 + 터보레포의 역할

BOFIT 팀은 TurboRepo를 활용해 모노레포 환경에서

• 디자인 시스템 패키지(bds-ui, bds-icon)
• 클라이언트 앱

여러 패키지를 하나의 저장소에서 버전과 빌드 흐름을 관리합니다.

이렇게 하면:

• 디자인 시스템을 수정하면 즉시 클라이언트 앱에도 반영할 수 있고,
• 컴포넌트 개발과 문서화(스토리북)도 한 흐름으로 관리할 수 있으며,
• 중복 빌드와 불필요한 작업을 캐싱으로 최소화할 수 있습니다.

오버 엔지니어링? 하지만 더 중요한 목표

물론 아직은 프로젝트를 대규모로 확장할 계획이 없는데,
“이게 혹시 오버 엔지니어링 아닌가?”라는 의문이 있을 수도 있습니다.

하지만 우리는 이 구조를 단지 지금의 효율만을 위해 선택한 것이 아닙니다.
무엇보다 팀원 모두가 컴포넌트 설계와 구현을 디자인 시스템 중심 사고로 접근해 보는 경험을 쌓는 것이 중요하다고 판단했습니다.

이 경험은 웹잼 기간 동안에 그치지 않고,
팀원들이 앞으로 다른 프로젝트를 진행하거나 더 큰 규모의 협업을 할 때에도
역할 분리와 UI 일관성 유지라는 기본 원칙을 자연스럽게 체득할 수 있는 소중한 학습 기회가 될 것이라 믿습니다.

또한 BOFIT 팀은 향후 프로젝트가 확장될 가능성이 있다고 판단했습니다.
처음부터 모노레포로 세팅해 두면, 새로운 서비스나 패키지가 추가될 때에도
구조적 부담 없이 효율적으로 관리할 수 있습니다.

만약 디자인 시스템을 별도의 레포로 분리해 두면,
장기적으로는 독립성과 배포 측면에서 장점이 있겠지만,
웹잼이라는 짧은 기간 동안에는 여러 레포를 오가며 관리해야 하는 불편함과 오버헤드가 더 클 수 있다고 판단했습니다.
그래서 현재는 하나의 모노레포로 모든 흐름을 집중 관리해 개발 효율성을 극대화하기로 했습니다.

---

🍦CSS 라이브러리

저희는 회의 끝에 Runtime 스타일링을 배제하기로 결정했습니다. 물론 buldtime 과 runtime 스타일링의 장단점을 분석한 이후에요.

CSS-in-JS 방식은 빠르게 개발하고, 유연하게 커스터마이징 할 수 있다는 장점이 있어요. 하지만 디자인 시스템이 존재하는 BOFIT 프로젝트에서는 단점이 더 크게 느껴졌어요.

• 런타임 성능 오버헤드 : 컴포넌트를 사용할 때 마다 JS가 스타일을 처리하는 방식은 처음부터 스타일이 정적일 수 있는 시스템에서는 과하다고 판단했어요. 무엇보다 초기에는 프로젝트의 확장성을 고려했어야 했거든요.
• 번들 사이즈 : 사용하지 않는 스타일도 JS로 포함되기에, 원하지 않는 추가 비용이 발생할 수 있어요
• 예측 가능성 : 클래스 명이 동적으로 생성되는 부분도 디버깅 혹은 스타일 충돌 가능성을 유발할 수 있어요

그래서 후보는? : Vanila-extract , tailwind V4 , Panda CSS

빌드 타임 스타일링 라이브러리중에서 두 가지 기준을 가지고 비교하며 검토했어요

• 러닝커브 : 웹잼(장기 해커톤)이라는 독특한 환경 속에서 개발을 진행하기에 팀원 모두가 라이브러리 사용 경험이 있거나, 없더라도 러닝커브가 높지 않아야 한다고 판단했어요
• 가독성 : 라이브러리 선택에서 생산성, 성능 , 가독성 등등의 요소들의 우선순위를 정하였는데, 저희 팀의 1순위 가치는 가독성 이었어요.

출처 Tailwind css

그래서 처음에는 Tailwind CSS 도 후보군에 올려두고 고민했습니다.
Tailwind는 독자적인 CSS 문법(mt-10과 같은 유틸리티 클래스)을 사용하여 생산성을 극대화할 수 있다는 점이 가장 큰 장점입니다.
하지만 우리 팀원 모두가 Tailwind를 실제로 사용해본 경험이 없었고, 웹잼이라는 장기 해커톤 환경에서는 새 문법에 적응하는 학습 비용이 오히려 단점이 될 수 있다고 판단했어요.

무엇보다 팀원 모두가 인라인 형태의 Tailwind 문법을 선호하지 않았고, 스타일 파일과 TSX 파일을 분리해 관리하는 방식을 더 가치 있게 봤습니다.
Tailwind의 최대 강점인 생산성을 저희 팀 상황에서는 100% 발휘하기 어렵다고 판단했고, 결국 가독성과 유지보수성을 위해 제외하기로 결정했습니다.

🐼 Panda CSS

출처 Panda CSS

그 다음 후보는 Panda CSS였어요.
Panda CSS는 Tailwind처럼 유틸리티 기반 스타일링을 제공하면서도, TypeScript 기반으로 동작하여 디자인 토큰 관리에 강점이 있다는 점에서 후보군에 올랐습니다.

실제로 저희는 Panda CSS를 직접 적용해보고자 초기 세팅까지 진행했어요.
다만 많은 팀원들이 Panda CSS의 초기 세팅이 어렵다는 피드백을 주었습니다.
하지만 개인적인 체감으로는 세팅 자체가 복잡하다기보다는 레퍼런스 자료가 부족한 것이 원인이라고 생각했습니다. 즉, 커뮤니티가 아직 활성화 되지 않은 것이죠.

그렇게 Panda CSS에서 디자인 토큰 정의를 마치고 빌드를 실행했는데, styled-system 덕분에 Tailwind와 유사한 유틸리티 클래스가 굉장히 많이 생성되더라고요.

하지만 저희 팀은 처음부터 유틸리티 클래스 사용을 배제하기로 했고, 특히 인라인 스타일링에 대한 거부감이 강했어요.
그래서 config 파일에서 유틸리티 클래스 생성을 막는 옵션을 추가한 뒤 다시 빌드를 진행했습니다.

그러나 이렇게 Panda CSS를 사용한다면, Panda CSS의 핵심 장점인 유틸리티 기반 스타일링을 제대로 활용하지 못한다는 결론에 도달했습니다.
결국 Panda CSS는 저희 팀의 스타일링 방향성과는 맞지 않는다고 판단했습니다.

🍦 Vanilla Extract

출처 : Vanila-extract css

저희는 다양한 스타일링 라이브러리를 비교하고, 실제 디자인 시스템 요구사항에 맞춰 실험한 끝에 Vanilla Extract를 최종 선택했습니다.

선택 이유

유틸리티와 타입 안전성
Vanilla Extract는 styleVariants, recipes, sprinkles, createThemeContract 등 디자인 시스템 구축에 필요한 강력한 유틸리티를 제공합니다.
또한 TypeScript와의 긴밀한 통합 덕분에 디자인 토큰과 테마를 타입 안전하게 관리할 수 있어, 확장성이 높고 실수를 줄일 수 있었습니다.

CSS 변수 기반 디자인 토큰 관리
예를 들어 Emotion 기반 런타임 테마는 테마 전환 시 리렌더링과 복잡한 상태 동기화가 필요했고, 깜빡임(FOUC) 문제가 있었습니다.
Vanilla Extract에서는 createGlobalThemeContract와 createGlobalTheme API를 통해 CSS 변수 기반으로 토큰을 선언하고 브라우저 레벨에서 관리하여,
런타임 오버헤드 없이도 일관된 디자인 토큰 관리가 가능해졌습니다.

정적 빌드 + 제로 런타임
스타일을 런타임이 아니라 빌드 시점에 추출하기 때문에 불필요한 번들 크기나 성능 부담이 없습니다.
필요하다면 가벼운 런타임 스타일도 지원하므로, 상황에 따라 유연한 적용이 가능합니다.

프레임워크 무관 + 직관적 구조
Vanilla Extract는 프레임워크에 종속되지 않기 때문에, Next.js / Vite 등 다양한 환경에서 일관되게 사용 가능합니다.
또한 CSS 파일을 직접 다루듯 작성할 수 있어 기존 CSS/SCSS 문법과 크게 다르지 않아 팀 전체가 빠르게 적응할 수 있었습니다.

디자인 시스템과의 높은 시너지
CSS 변수로 테마를 관리하면서, 디자인 토큰의 가독성과 유지보수성을 크게 높였습니다.
개발자 도구에서 변수명을 바로 확인할 수 있어 디자이너와 원활하게 협업할 수 있었고, 오타나 잘못된 참조를 사전에 방지할 수 있었습니다.

---

결과적으로, Vanilla Extract는 타입 안전성과 디자인 토큰 관리, 제로 런타임의 장점을 동시에 제공하며,
디자인 시스템을 지속적으로 고도화할 수 있는 가장 적합한 선택지였습니다.

📕 Storybook

출처: Storybook 공식 홈페이지

좋은 디자인 시스템은 좋은 컴포넌트를 만드는 것에 그치면 안된다고 생각합니다. 이 컴포넌트를 어떻게 보여주고, 테스트하고, 협업하는 팀원들과 함께 소통할지가 중요한 포인트죠.

BOFIT 팀은 스토리북을 다음과 같은 이유로 도입하였습니다.

• 컴포넌트 기반 개발 : 각 컴포넌트를 개별적으로 개발하고, 시각적으로 개발자 뿐만 아니라 디자이너도 즉시 확인할 수 있게 해주는 도구로 사용합니다.
• 컴포넌트 문서화 : 컴포넌트의 다양한 Props 와 상태와 사용법 등등을 직접 별도의 공간에서 인터랙션하며 이해할 수 있는 테스트 도구이자. 컴포넌트 그 자체에 대한 문서가 되어줍니다.

Addon 활용으로 확장된 Storybook

저희는 기본 Storybook 환경에 다음과 같은 Addon을 적극 활용하고 있습니다.

• @storybook/addon-essentials : Storybook을 구성하는 데 필수적인 기능 모음입니다.
  Controls, Docs, Actions, Viewport 등 컴포넌트의 상태를 실시간으로 조작하거나, 문서를 자동으로 생성하는 기능을 통해 개발자와 디자이너가 동일한 화면에서 피드백하고 소통할 수 있도록 돕습니다.

• @storybook/addon-a11y : 접근성 검사 도구를 스토리북에 통합합니다.
  이 Addon을 통해 각 컴포넌트가 WCAG 가이드라인에 맞게 충분히 접근성을 고려하고 있는지 실시간으로 점검하며 개발합니다.
  개발 단계부터 접근성을 기본값으로 가져가려는 저희 팀의 목표와 잘 맞아떨어집니다.

• @storybook/addon-onboarding : 스토리북을 처음 사용하는 팀원도 쉽게 이해하고, 사용 흐름을 빠르게 익힐 수 있도록 가이드를 제공합니다.
  특히 새로운 팀원이 합류하거나, 디자인 시스템을 확장할 때에도 학습 장벽을 낮출 수 있었습니다.

무엇보다 저희는 단순한 개발에 그치지 않고, 웹잼(Web Jam) 기간 동안에도 문서화를 체계적으로 관리하고 공유하는 것을 목표로 하고 있습니다.
Storybook은 이러한 목적의식과 잘 맞아떨어지는 협업 도구로써, 개발-디자인 간 경계를 허물고 더 나은 디자인 시스템 품질을 유지하는 데 중요한 역할을 합니다.

---

⚙️ 상태 관리 라이브러리

출처: Zustand 공식 홈페이지

BOFIT 팀은 다양한 선택지(Redux, Recoil, Zustand 등)를 충분히 검토했지만, 최종적으로는 별도의 전역 상태 관리 라이브러리를 사용하지 않기로 결정했습니다.

이유는 명확했습니다.
과거에는 Redux 같은 라이브러리가 없으면 복잡한 상태 흐름을 관리하기 어렵던 시절이 있었지만, 지금은 상황이 다릅니다.

• Tanstack Query가 자동으로 캐싱과 서버 상태 관리(로딩, 오류, 페치 등)를 처리해줍니다.
• 인증 정보나 간단한 글로벌 상태는 Context + useReducer 조합으로 충분히 안전하게 관리할 수 있습니다.
• 모달 상태나 드롭다운, 간단한 UI 상태는 컴포넌트 단위의 useState로도 무리가 없습니다.
• 복잡한 워크플로우나 상태 전이가 필요한 경우에는 XState와 같은 유한 상태 머신 라이브러리를 필요에 따라 함께 활용할 수 있습니다.

오히려 불필요한 전역 상태는 복잡성을 만들고, 흐름을 추적하기 어렵게 하며 디버깅 비용을 높입니다.
저희는 실제 서비스에서 전역으로 공유해야 할 상태가 거의 없다고 판단했고, 필요하다면 컴포넌트 구조를 리팩토링해 Context만으로도 충분히 해결할 수 있다고 결론지었습니다.

따라서 BOFIT 팀은 전역 상태 관리 도구 대신 React의 기본 기능과 Context, React Query를 중심으로 상태를 관리하고,
필요 이상으로 복잡성을 키우지 않는 가벼운 설계를 선택했습니다.

---

📁 폴더구조 : 기능 중심 사고를 담은 구조

프로젝트의 폴더 구조를 설계하기 앞서, 우리 팀이 추구하는 목표와 방향성을 명확히 하는 것이 중요했습니다.

우리의 목표 설정

단기 목표: 기능 구현 우선

웹잼 기간 동안 BOFIT 팀의 핵심 목표는 **기능 구현(Function Implement)**입니다.
팀원 모두가 명확한 기능 목표를 달성하며, 사용자에게 실제로 동작하는 결과물을 제공하는 것이 최우선입니다.

물론 Clean Code를 함께 추구하는 것이 이상적이지만, 현실적으로 개발 초기 단계에서부터 완벽한 아키텍처를 설계하는 것은 쉽지 않습니다.
그래서 단기적으로는 기능 구현에 집중하고, 장기적으로는 코드 품질과 아키텍처 정교화로 이어지는 방향을 설정했습니다.

장기 목표: Clean Code 지향

장기적으로는 **확장성(Extensibility), 재사용성(Reusability), 유지보수성(Maintainability), 가독성(Readability)**을 갖춘 Clean Code가 핵심 목표입니다.

관심사 분리: 인지 부하를 줄이는 핵심 원칙

관심사 분리는 개발자 입장에서 인지 부하(Cognitive Load)를 줄이는 데 매우 효과적입니다.

시각적 비유로 이해하기

복잡한 그림에서 특정 도형을 찾는 상황을 생각해보세요.

• 모든 도형이 같은 색이라면 빨간 사각형을 찾기 쉽습니다.
• 하지만 빨간 원과 파란 사각형이 섞여있다면? 찾는 시간이 길어집니다.
• 더 많은 종류의 도형이 무질서하게 섞여있다면? 인지 소모량이 급격히 증가합니다.

코드도 마찬가지입니다.
여러 관심사가 한 파일에 혼재되어 있으면 조건과 맥락이 뒤섞여 혼란이 극대화됩니다.
따라서 하나의 명확한 역할만 수행하는 단위로 코드를 나누어야 합니다.

프론트엔드에서의 관심사 분리 발전사

웹 프론트엔드는 그 자체로 관심사 분리를 지향하는 발전의 역사였습니다.

1. 수평적 계층 구조: HTML, CSS, JavaScript, API 등 여러 계층으로 나누어 관심사를 분리

2. 컴포넌트의 등장: 수평적 계층 구조를 수직으로 관통하는 새로운 분류 방식

   • UI 요소와 관련 로직이 결합되어 재사용성 증가
   • 독립적인 개발과 테스트가 가능
   • 역할이 아닌 기능 중심의 모듈화

3. HTML-CSS 의존성 해결: CSS Modules, CSS-in-JS 등을 통한 단방향 의존 구조

4. 비즈니스 로직과 뷰 로직 분리:

   • 화면 그리기 & 사용자 이벤트 처리 → 컴포넌트
   • 상태 관리 & API 요청 처리 → Service Layer 또는 Store

5. 서버 상태 관리: API 호출, 캐싱, 페이지네이션, 에러 처리 등을 별도 계층으로 분리

기존 폴더 구조의 한계

보편적인 "역할별 구조"의 문제점

현재 가장 보편적인 폴더 구조는 다음과 같습니다:

└── src/
    ├── assets/      # 사용되는 에셋 파일
    ├── api/         # 백엔드와의 통신을 담당하는 코드
    ├── config/      # 애플리케이션의 설정 파일들
    ├── components/  # 공통으로 쓰이는 컴포넌트
    ├── hooks/       # 컴포넌트에서 사용되는 hook 파일들
    ├── services/    # 비즈니스 로직을 처리하는 서비스 레이어
    ├── styles/      # 전역 스타일이나 스타일 관련 설정
    ├── pages/       # 실제 라우팅되는 페이지 컴포넌트들을 포함
    └── utils/       # 공통으로 사용되는 유틸리티 함수들

이 구조는 **역할별로 나뉜 구조(Role-Sliced Design)**로, 다음과 같은 장점이 있습니다:

• 코드가 하는 역할에 따라 분류되어 일관된 기준이 생김
• 역할별로 찾아가기 쉬워 정돈된 느낌을 줌
• 팀 프로젝트를 위한 구조로 충분히 효율적

하지만 규모가 커지면서 드러나는 한계

프로젝트 규모가 커지면 이 구조의 한계가 드러납니다:

1. 컴포넌트 폴더의 폭발적 증가: 수십, 수백 개의 컴포넌트가 생기면 다시 분리해야 함
2. 분류 기준의 혼재: UI로 나눌지, pages로 나눌지, domain별로 나눌지 고민
3. 도메인별 파편화: 특정 기능(예: cart 도메인)을 제거하려면 여러 폴더를 거쳐야 함

예를 들어 cart 도메인을 완전히 제거해야 한다면:

• /components에서 cart 관련 컴포넌트들
• /hooks에서 cart 관련 훅들
• /services에서 cart 관련 서비스들
• /api에서 cart 관련 API들

모든 폴더를 뒤져서 관련 파일들을 찾아 제거해야 합니다. 이는 지우기 어려운 코드를 만듭니다.

FSD(Feature-Sliced Design) 구조의 도입

FSD란?

Feature-Sliced Design은 기능(Feature)을 기준으로 코드를 분리하는 아키텍처입니다.
기존에는 역할에 따라 파일과 폴더가 분리되었지만, 이제는 하나의 기능 단위로 모든 파일을 같은 폴더에 모아 관리합니다.

FSD의 핵심 개념

Layers (계층)

• App: 앱을 실행하는 모든 것 (라우팅, 진입점, 전역 스타일, 프로바이더)
• Pages: 전체 페이지 또는 중첩 라우팅에서 페이지의 주요 부분
• Widgets: 독립적으로 작동하는 대규모 기능 또는 UI 컴포넌트
• Features: 제품 전반에 걸쳐 재사용되는 기능 구현체
• Entities: 프로젝트가 다루는 비즈니스 엔티티 (user, product 등)
• Shared: 재사용 가능한 기능, 프로젝트/비즈니스 특성과 분리된 것

Slices (슬라이스)
비즈니스 도메인별로 코드를 분할하며, 같은 레이어 안에서 다른 슬라이스를 참조할 수 없습니다.

Segments (세그먼트)
목적에 따라 코드를 그룹화합니다:

• ui: UI 컴포넌트, 스타일 등
• api: 백엔드 상호작용
• model: 데이터 모델, 스키마, 비즈니스 로직
• lib: 라이브러리 코드
• config: 설정 파일과 기능 플래그

FSD의 장점

1. 높은 응집도, 낮은 결합도: 관련된 모든 파일이 한 곳에 모여 있음
2. 삭제 용이성: 특정 기능을 제거할 때 해당 폴더만 삭제하면 됨
3. 독립적 개발: 각 기능이 독립적으로 관리됨
4. 확장성: 새로운 기능 추가가 쉬움

BOFIT 팀의 변형된 FSD 구조

왜 변형했을까?

표준 FSD는 대규모 프로젝트에 최적화되어 있어, 초기 프로젝트에는 다소 복잡할 수 있습니다.
FSD 공식 문서에서도 "모든 레이어를 사용할 필요는 없다"고 언급하고 있어, 우리 프로젝트에 맞게 단순화했습니다.

우리가 선택한 구조

└── src/
    ├── app/                     // route VIEW
    │   ├── index.html 
    │   └── App.tsx
    ├── pages/                   // VIEW -> 화면의 구조를 파악
    │   ├── home/ 
    │   │   └── page.tsx
    │   ├── report/
    │   ├── landing/
    │   ├── onboarding/
    │   ├── mypage/
    │   └── community/
    │       ├── detail/
    │       │    └── page.tsx
    │       ├── write/
    │       │    └── page.tsx
    │       └── page.tsx
    ├── widgets/                  // 뷰 내부 로직, 컴포넌트의 기능 
    │   ├── home/
    │   ├── report/
    │   │   ├── configs/          // 상수
    │   │   ├── components/       // 해당 도메인 내 components, section
    │   │   ├── hooks/
    │   │   └── utils/
    │   ├── landing/
    │   ├── onboarding/
    │   ├── mypage/
    │   └── community/
    └── shared/
        ├── configs/
        ├── components/
        ├── hooks/
        ├── api/           
        │    ├── domain/
        │    │    ├── home/
        │    │    │    └── queries.ts
        │    │    ├── report/
        │    │    │    └── queries.ts
        │    │    ├── landing/
        │    │    ├── onboarding/
        │    │    ├── mypage/
        │    │    └── community/
        │    ├── query.keys.ts            // 모든 쿼리 키는 shared 에서 관리
        │    └── types.ts                 // 모든 api type는 shared 에서 관리
        └── utils/

각 레이어의 역할

App 레이어
애플리케이션의 진입점과 전역 설정을 담당합니다.

Pages 레이어
실제 라우팅되는 페이지들을 관리하며, 화면의 전체 구조를 파악할 수 있습니다.

Widgets 레이어
각 도메인별로 해당 페이지에서 사용되는 모든 로직과 컴포넌트를 관리합니다.
이는 기능 중심의 관심사 분리를 실현하는 핵심 레이어입니다.

Shared 레이어
여러 도메인에서 공통으로 사용되는 컴포넌트, 훅, 유틸리티, API 등을 관리합니다.

이 구조의 장점

1. 직관적인 도메인 탐색: 특정 기능에 대한 모든 파일이 한 곳에 모여 있음
2. 효율적인 협업: 팀원들이 각자 담당하는 도메인 폴더에서 독립적으로 작업 가능
3. 유지보수성: 특정 기능의 수정이나 삭제가 해당 폴더 내에서만 이루어짐
4. 확장 가능성: 새로운 도메인 추가가 간단하고 체계적
5. 테스트 용이성: 각 위젯별로 독립적인 테스트 작성 가능

결론적으로, BOFIT 팀은 기능 중심의 사고방식을 코드 구조에 반영하여
개발 효율성과 유지보수성을 동시에 확보할 수 있는 BOFIT 팀 만의 폴더 구조를 선택했습니다.

우리가 설계한 이 폴더 구조가 정답일 수는 없습니다.  
프로젝트마다, 팀마다 상황과 요구가 다르기 때문입니다.  

다만, BOFIT 팀은  
기존의 전형적인 템플릿이나 표준을 단순히 따라가기보다,  
우리 서비스와 팀 환경에 맞는 최적의 구조를 찾기 위해  
많은 고민과 실험을 거쳤다는 점에 큰 의미를 두고 있습니다.  

---

🏃🏻‍➡️ 빠르고 효율적인 Vite + Pnpm

좋은 프로젝트를 만들기 위해서는 빠른 개발 환경과 안정적인 의존성 관리가 필수라고 판단했습니다.
느린 빌드 시간이나 의존성 설치 시간은 특히 장기 해커톤 같은 환경에서 생산성을 크게 떨어뜨릴 수 있기 때문입니다.

그래서 BOFIT 팀은 빌드 도구와 개발 서버로 Vite, 패키지 매니저로는 Pnpm을 선택했습니다.

출처: vite 공식 홈페이지

Vite의 장점

• 즉각적인 HMR(Hot Module Replacement)
  코드 수정 시 변경된 부분만 빠르게 반영되어 개발 속도가 크게 향상됩니다.
• 번들링 최적화
  개발 서버에서는 ESM 기반의 Native Module로 동작하고, 빌드시에는 Rollup을 사용해 최적화된 결과물을 제공합니다.
• 빠른 초기 구동 속도
  서버 시작 시간이 매우 짧아 반복적인 실행에 부담이 없습니다.
• 최신 생태계와의 호환성
  React, TypeScript, Vanilla Extract 등 최신 라이브러리와의 호환성이 매우 좋습니다.

Pnpm의 장점

• 중복 없는 의존성 설치
  Pnpm은 하드 링크 기반의 고유한 저장 구조를 사용하여 의존성을 한 번만 다운로드하고 여러 프로젝트에서 공유할 수 있습니다.
• 빠른 설치 속도와 카탈로그(store)
  Pnpm은 전역에 공유 저장소(store) 를 유지하여 동일한 패키지를 다시 다운로드하지 않고도 여러 프로젝트에서 재사용할 수 있습니다.
  이를 통해 디스크 사용량은 줄고, 설치 속도는 빨라집니다.
• Strict 설치 정책
  의존성 트리를 엄격하게 관리해 잘못된 중복 참조나 숨겨진 의존성 버그를 방지할 수 있습니다.
• 워크스페이스 지원
  모노레포 환경에서 여러 패키지를 효율적으로 관리할 수 있고, Vite와 연계하여 빠른 빌드와 의존성 동기화를 할 수 있습니다.

---

[jaine-p]

개발 무지랭이여서 기술적인 내용까진 이해하지 못했지만, 합숙 때 들리던 바닐라익스트랙, panda css가 어떤 꼼꼼한 논리 과정을 거쳐 선택됐는지 이해할 수 있었어요 ! 글을 엄청 잘 쓰시네요 bb