Folder Structure

https://velog.io/@teo/folder-structure

"팀의 생산성에 기여하는 핵심은 바로 개발자의 멘탈 모델을 폴더 구조에 명확히 드러냄으로써 얻는 시너지 효과에 있습니다. "

폴더 구조

폴더 구조에는 절대적인 정답이 없다. 팀의 상황이나 규모, 서비스의 성숙도에 따라 언제든지 달라질 수 있다.

• 서비스 초기에 구조를 잡을 때 서비스의 방향성과 구조가 아직 불확실한 상태이기 때문에, 너무 빡빡하게 규칙을 정하기보다는 최소한의 규칙만 정하고 유연하게 시작하는 것이 좋음

  • 시행착오를 겪으며 불편함이 반복될 때, 그때 구조를 점차 정리해나가는 방식이 더 현실적

• 구조가 잡혀 있거나 여러 번의 시행착오를 통해 문제점을 인지하고 있다면, 좀 더 체계적이고 구체적인 폴더 구조를 구성하는 것이 좋다.

Techincal Folders

비즈니스 도메인과 무관하게, 앱의 기능을 구성하는 기술 역할 중심의 폴더 구조

src/
├── app/                 # 앱 초기 설정 (라우팅, Layout, Providers 등)
├── assets/              # 이미지, 폰트 등 정적 리소스
├── components/          # 재사용 가능한 UI 컴포넌트들 (Button, Modal 등)
├── hooks/               # 전역/범용 커스텀 훅
├── libs/                # 외부 라이브러리 래핑, API 클라이언트 등
├── styles/              # 전역 스타일, 테마, reset
├── utils/               # 유틸 함수 모음
├── config/              # 환경 설정 (env, constants, routes 등)
├── store/               # 전역 상태 관리 (Redux, Zustand, Recoil 등)
└── types/               # 글로벌 타입 정의

장점

• 기준이 간단하고 명확해서 의사결정이 쉬움

• 특정 함수나 컴포넌트가 이미 있는지 파악하기 쉬워 중복을 방지할 수 있음

• 소규모 프로젝트에 적합

단점

• 규모가 커질수록 관련된 코드들이 폴더 곳곳에 흩어져 파악하기 어려움

• 비즈니스 로직이 분산되기 때문에 전체 흐름을 파악하기 어려움

  • 하나의 기능을 완전히 파악하려면 여러 폴더를 넘나들어야 함

• 기능 단위로 리팩터링하거나 추상화하려 할 때 관계 파악이 어렵고 리스크 있음

• 시간이 지날수록 폴더가 거대해지고 뒤엉켜 관리가 어려워질 수 있음

Feature Folders

비즈니스 도메인(기능) 단위로 폴더를 구성하는 방식

src/
├── features/
│   ├── auth/
│   │   ├── components/
│   │   ├── hooks/
│   │   └── index.ts
│   ├── dashboard/
│   │   ├── components/
│   │   ├── hooks/
│   │   └── index.ts
├── shared/
│   ├── components/
│   ├── hooks/
│   └── utils/
...

장점

• 관련된 코드가 한 폴더에 모여 있어 맥락 파악과 디버깅이 쉬움

• 기능 단위로 분리되어 있으므로 기능 리팩터링, 삭제, 이관이 수월

• 로컬한 개발이 가능 (ex. 특정 기능 개발할 때 다른 코드에 거의 영향 안 줌)

• 추후 마이크로 프론트엔드(MFA) 구조로 이관하기 쉬운 형태

단점

• 공통 로직 중복이 생기기 쉬움 (비슷한 훅, 유틸 함수 등)

• 중복된 로직을 찾고 shared/로 옮기는 작업이 번거로움

• 구조가 복잡해 보일 수 있고, 팀 내 명확한 기준 없이 적용하면 폴더 지옥 가능성 있음

FSD(Feature-Sliced Design)는 Feature Folder 구조를 더 체계화하고 확장한 설계 방식