FE 디렉토리 구조(FE 아키텍쳐)

1. 디렉토리 구조가 중요할까?

• 유지보수성: 기능이 늘어나고 팀원이 많아질수록, 구조가 엉키면 유지보수가 어렵다.
• 코드 탐색 속도: 파일을 빠르게 찾을 수 있어 생산성 향상.
• 협업 명확성: 역할별/기능별 책임이 명확해져 코드 충돌 줄어듦.
• 확장성: 구조가 잘 짜여 있으면 기능을 확장하기 쉬움.

애플리케이션이 복잡할수록 더 중요.

---

2. "나눈다"는 건 무엇을 기준으로?

• 디렉토리를 나누는 개념은 결국 모듈화를 어떻게 적용할 것인가에 대한 고민.
• ESM과 같은 모듈 시스템이 부족했던 시절에는?
  • 전역 객체(namespace)를 이용해 계층을 흉내내기도 함.

과거 방식: Namespace 패턴 (ESM 이전)

(와 전역변수 하나라니...)

const naver = {}
naver.auth = {}
naver.auth.login = function() {}
naver.store = {}
naver.store.product = {}
naver.store.product.list = function() {}

현재 방식: ESM (ES Modules) 기반 구조화

• ESM 덕분에 React를 비롯한 SPA 구조에서 파일 단위 모듈화 → 디렉토리 구조화 → 명확한 책임 분리가 가능해짐

→ 결과적으로 오늘날 우리가 디렉토리 구조를 신경 쓰는 이유는,
모듈 시스템(ESM)이 코드를 역할/기능 단위로 안전하게 나눌 수 있는 환경을 제공해주기 때문

• "나눈다"는 건 역할, 기능, 책임을 기준으로 코드를 그룹화한다는 뜻.
• ESM 구조라면?

src/
├── auth/
│   └── login.ts
├── store/
│   └── product/
│       └── list.ts

이렇게 구조화된 코드는 탐색이 쉽고, 의도 파악도 빠르다.

---

3. 주요 디렉토리 구조 패턴 비교

3.1 Atomic Design 구조

https://atomicdesign.bradfrost.com/chapter-2/

'화학 개념을 UI에 응용해‘작게 쪼개서 조립하자' by Brad Frost.

src/
├── components/
│   ├── atoms/
│   ├── molecules/
│   ├── organisms/
│   └── templates/

• UI 복잡도 기준으로 컴포넌트를 계층화
• 디자인 시스템 중심의 프로젝트에 적합

Atomic의 구성 의미

• Atoms(원자): 가장 기본적인 UI 요소
  • Button, Input 등
• Molecules(분자): 간단한 요소들의 조합
  • SearchForm 등
• Organisms(유기체): 의미 있는 섹션 단위 UI
  • Header, ProductList 등
  • 커지기 쉬움. 다시 분해.
• Templates: 페이지 구성 레이아웃 구조
  • Sidebar + Header + Content 영역
  • 구조만 담당하자.. Pages랑 구분잘해야함
• Pages: 실제 데이터를 적용한 완전한 페이지
  • 보통 API가 들어감ㄷ

장점: 시각적으로 명확, 컴포넌트 재사용 구조에 좋음
단점: 도메인/기능 중심 설계와는 다소 거리가 있음

warning

• 역참조 금지
• 과도한 분해 의심
• 도메인 구조를 믹스 할 수도 있음.
• 나누는것이 목표는 아니다.
• 유연한 적용이 중요

---

3.2. Layered Architecture 구조 (계층형)

src/
├── components/
├── pages/
├── services/
├── hooks/
├── utils/

• 역할별로 디렉토리를 나누는 가장 무난한 방식이다.

장점: 직관적, 익숙함
단점: 기능이 흩어져 있어 응집도 낮음, 유지보수 어려움

---

3.3 Layered + Atomic 구조

src/
├── components/
│   ├── atoms/
│   ├── molecules/
├── pages/
├── services/

• LA 구조에 Atomic을 결합 → UI는 Atomic 방식으로, 나머지는 역할 중심으로 분리

장점: 디자인 시스템과 앱 구조 공존 가능
단점: 복잡한 구조에서는 경계가 애매해질 수 있음

---

3.4 Layered + Colocation 구조

• 역할 단위로 구조를 유지하면서, 내부는 기능 단위로 인접 배치

src/
├── components/
│   └── ProductCard/
│       ├── ProductCard.tsx
│       ├── ProductCard.module.css
│       └── ProductCard.test.tsx

장점: 유지보수 편함, 코드 집중도 높음
단점: 일관성 없이 섞이면 복잡해질 수 있음

---

4. Feature-Sliced Design (FSD) 구조

FSD는 기능 중심으로 분리되면서도 각 계층의 책임이 명확하게 나뉘는 구조.

도메인, 기능, 표현을 적절히 분리하여 유지보수성과 협업 효율을 극대화할 수 있다.

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

• app: 앱의 진입점과 전역 설정을 담당.
  • 예: App.tsx, store.ts, 라우터 설정 등.
  • 전역 프로바이더, 에러 바운더리, 초기 로딩 로직 등
• entities: 핵심 도메인 단위. 상태, 모델, UI 분리.
• features: 사용자 기능 단위. 액션 중심.
• shared: 범용 UI 및 도구.
• widgets: 여러 feature와 entity를 조합한 UI 블록.
• pages: 라우트 단위 화면.

장점: 역할 + 기능 + 도메인 분리가 명확, 대규모 앱에 적합

단점: 러닝커브 있음, 초기 도입 진입장벽 존재. 호미로 쓸건 호미로 쓰자..

---

5. FSD 적용 예시

5.1 카운터 앱

src/
├── entities/Counter/
│   ├── model/store.ts
│   └── ui/CounterDisplay.tsx
├── features/counterControl/
│   └── ui/CounterControls.tsx
├── widgets/CounterBox/
│   └── CounterBox.tsx

• 상태 관리 (store.ts)는 entity에 위치
• +, - 버튼은 feature에서 기능 담당
• 전체 박스는 widget에서 조립

카운터 앱 예시코드.

entities/Counter/model/store.ts

• Store(state)에 집중. 상태관리 라이브러리로 구현할 수도 있음.

import { useState } from 'react'

export function useCounterStore() {
  const [count, setCount] = useState(0)
  const increment = () => setCount((c) => c + 1)
  const decrement = () => setCount((c) => c - 1)
  return { count, increment, decrement }
}

---

entities/Counter/ui/CounterDisplay.tsx

import React from 'react'

export const CounterDisplay = ({ count }: { count: number }) => {
  return <h1>현재 카운트: {count}</h1>
}

---

features/counterControl/ui/CounterControls.tsx

import React from 'react'

export const CounterControls = ({
  onIncrement,
  onDecrement,
}: {
  onIncrement: () => void
  onDecrement: () => void
}) => {
  return (
    <div>
      <button onClick={onDecrement}>-</button>
      <button onClick={onIncrement}>+</button>
    </div>
  )
}

---

widgets/CounterBox/CounterBox.tsx

import { useCounterStore } from '@/entities/Counter/model/store'
import { CounterDisplay } from '@/entities/Counter/ui/CounterDisplay'
import { CounterControls } from '@/features/counterControl/ui/CounterControls'

export const CounterBox = () => {
  const { count, increment, decrement } = useCounterStore()

  return (
    <div>
      <CounterDisplay count={count} />
      <CounterControls onIncrement={increment} onDecrement={decrement} />
    </div>
  )
}