2026-03-20

프론트엔드 프로젝트 구조 종류

기능 중심 구조 (Feature-based / Domain-based)

저는 기능 단위로 파일을 구성해 도메인 중심 구조를 사용했습니다. 관련 컴포넌트와 API, 상태 로직을 함께 묶어 응집도를 높이고 유지보수를 쉽게 했습니다.

Feature-based 구조는 auth, product 같은 기능 단위로 폴더를 나누고 그 안에 UI, hooks, API, 상태관리 코드를 함께 배치하는 방식입니다. 기능 관련 코드가 한 곳에 모여 응집도가 높고 협업과 확장에 유리해서 실무에서 가장 많이 사용하는 구조입니다.

src/
 ├─ features/
 │   ├─ auth/
 │   │   ├─ Login.tsx
 │   │   ├─ authAPI.ts
 │   │   └─ authStore.ts
 │   ├─ product/
 │   │   ├─ ProductList.tsx
 │   │   └─ productAPI.ts

• 특징
  • 기능(도메인) 단위로 묶음
  • 관련된 컴포넌트, API, 상태를 한 폴더에 배치
• 장점
  • 응집도 높음
  • 유지보수 쉬움
  • 대규모 프로젝트에 적합
• 단점
  • 초기 설계가 필요

타입 중심 구조 (Type-based)

가장 기본적인 구조는 파일의 역할 기준으로 나누는 Type-based 구조입니다. components, hooks, utils처럼 파일 종류별로 폴더를 분리하는 방식입니다. 작은 프로젝트나 MVP 단계에서 빠르게 개발할 때 적합하지만, 규모가 커지면 기능 관련 코드가 여러 폴더에 흩어져 유지보수가 어려워지는 단점이 있습니다.

src/
 ├─ components/
 ├─ pages/
 ├─ hooks/
 ├─ api/
 ├── styles/
 ├─ utils/

• 특징
  • 역할별로 폴더 구분
  • 초보 프로젝트에서 흔함
• 장점
  • 직관적
  • 소규모 프로젝트에 적합
• 단점
  • 기능이 커지면 파일이 분산됨
  • props drilling 구조 복잡해질 수 있음

Atomic Design 구조

Atomic Design은 UI를 atoms, molecules, organisms 같은 단계로 나누어 구성하는 방식입니다. 재사용성과 디자인 일관성을 높일 수 있어 디자인 시스템이나 공통 UI 라이브러리를 만들 때 주로 사용합니다.

components/
 ├─ atoms/
 ├─ molecules/
 ├─ organisms/
 ├─ templates/
 ├─ pages/

• 특징
  • UI 단위를 계층적으로 구성
  • 디자인 시스템에 적합
• 장점
  • 재사용성 높음
  • UI 체계적 관리 가능
• 단점
  • 비즈니스 로직과는 별개
  • 구조 복잡해질 수 있음

FSD (Feature-Sliced Design)

FSD는 Feature-Sliced Design의 약자로, 기능 중심 구조에 계층(layer) 개념과 의존성 규칙을 적용한 프론트엔드 아키텍처입니다. 프로젝트를 app, pages, widgets, features, entities, shared 같은 레이어로 나누고, 상위 레이어가 하위 레이어만 의존하도록 설계해 유지보수성과 확장성을 높이는 구조입니다.

프로젝트 규모가 커질수록 코드 의존성이 복잡해지는데, FSD는 레이어 간 책임을 명확히 나누고 import 방향을 제한해서 구조가 무너지지 않도록 하기 위해 사용합니다.

src/
 ├─ app/
 ├─ pages/
 ├─ widgets/
 ├─ features/
 ├─ entities/
 ├─ shared/

• 특징
  • 계층적 아키텍처
  • 의존성 방향이 명확
  • 대규모 서비스에 적합
• 장점
  • 유지보수성 우수
  • 확장성 좋음
  • 의존성 관리 용이

MVC 패턴

React는 View 중심이라 완전 MVC는 아님.

• Model
• View
• Controller

참고자료

• https://velog.io/@teo/folder-structure
• https://llddang-blog.tistory.com/71