🧱 프론트엔드 구조 설계 가이드

프론트엔드 개발은 단순히 UI를 그리는 것을 넘어, 유지보수성과 확장성까지 고려한 구조 설계가 중요하다.

오늘은 실제 프로젝트를 시작할 때 고민해야 할
FE 구조 설계의 핵심 포인트와 디렉토리 설계 방법에 대해 정리해본다.

---

📌 구조 설계의 중요성

• 협업 생산성 향상: 누구나 빠르게 코드를 이해하고 기여할 수 있도록
• 유지보수 용이: 기능 추가나 수정 시 최소한의 영향으로 작업 가능
• 재사용성 확보: 공통 컴포넌트, 유틸 함수 등을 잘 정리해 반복 개발 방지

---

📁 기본 디렉토리 구조 예시 (React 기준)

src/
├── assets/         # 이미지, 폰트 등 정적 자원
├── components/     # 재사용 가능한 UI 컴포넌트
├── pages/          # 라우트 단위 페이지 컴포넌트
├── hooks/          # 커스텀 훅
├── utils/          # 유틸 함수, 헬퍼 모음
├── services/       # API 호출 함수
├── store/          # 전역 상태 관리 (Redux, Zustand 등)
├── constants/      # 상수, Enum, 설정 값
├── types/          # TypeScript 타입 선언
├── layouts/        # 공통 레이아웃 컴포넌트
└── App.tsx         # 앱 진입점

---

🧩 폴더별 역할 정리

1. components/

• 최소 단위 UI 단위 (Button, Modal 등)
• 재사용성과 캡슐화 고려하여 분리

2. pages/

• 라우팅과 밀접한 페이지 단위 컴포넌트
• 각 페이지별 폴더 생성 후 index.tsx로 구성

3. services/

• axios 등으로 API 통신 함수 정리
• 응답 타입은 types/에서 정의 후 import

4. hooks/

• 복잡한 상태나 이벤트 핸들링을 커스텀 훅으로 추상화

5. store/

• Redux, Zustand 등 상태 관리 툴 적용
• slice 단위로 파일 구성

---

🛠️ 실전 팁

• 라우터와 페이지 구조는 1:1로 매핑하면 추적이 쉽다
• atomic design 도입 시 컴포넌트 단위 정리를 더 세밀하게 할 수 있음
• 팀에서 구조를 정한 뒤 wiki 등에 정의하고 공유하는 것이 좋다
• 컴포넌트/훅/서비스 등은 index.ts로 export 정리하면 import 간결화 가능

---

🔨 TIL

• 구조는 한 번에 완벽하게 만드는 것이 아니라, 프로젝트의 흐름에 따라 진화시켜야 한다.
• 기능 추가보다 더 중요한 것이 구조를 지키며 확장하는 능력이다.
• 초기 설계에 시간을 쓰는 것이 장기적으로 생산성을 높이는 지름길임을 다시 느꼈다.