React·Next.js FSD 폴더 구조 템플릿: app/pages/widgets/features/entities/shared

React·Next.js FSD 폴더 구조 템플릿: app/pages/widgets/features/entities/shared

FSD는 폴더를 예쁘게 나누는 기법이 아니라 의존성 흐름을 제어하는 방식이다. React와 Next.js 프로젝트에서 공통으로 쓰기 좋은 기본 템플릿을 먼저 고정하면 팀 생산성이 안정된다. 검색 유입이 많은 키워드(폴더 구조, 마이그레이션, 안티패턴, 상태관리)를 기준으로 실무 적용 포인트를 정리했다.

FSD 공식 사이트 참조 이미지 (출처: feature-sliced.design)

핵심 개념

실무에서 먼저 결정할 기준

이 주제는 코드 배치 기준을 먼저 정하고, 이후 네이밍과 import 경계를 린트로 고정하는 순서가 가장 안정적이다.

핵심 요소 3~6개

항목	의미	언제 쓰는지(실무 상황)
app	전역 설정, providers, router	애플리케이션 부트스트랩 코드를 관리할 때
pages	라우트 단위 페이지 조합	화면 진입점에서 widgets/features를 조합할 때
widgets	페이지 섹션 단위 블록	헤더, 사이드바, 피드 블록 등을 구성할 때
features	사용자 액션 중심 기능	로그인, 결제, 검색 같은 상호작용 기능 구현 시
entities/shared	도메인 모델 및 공통 자원	도메인 재사용 모델과 UI 유틸을 분리할 때

예시 코드

src/
  app/providers/
  pages/catalog/
  widgets/header/
  features/add-to-cart/
  entities/product/
  shared/ui/
  shared/lib/

문제 상황 1개

상황: Next.js App Router 도입 후 기존 src 구조와 충돌해 파일 위치가 뒤섞인다.
원인: 라우팅 구조와 도메인 구조를 분리하지 않고 한 폴더에 혼합했다.
해결: 라우트 진입점은 app/pages에 두고, 도메인 기능은 features/entities로 분리한다.
예방 팁: 폴더 생성 규칙을 CLI 템플릿으로 자동화해 임의 구조 생성을 막는다.

참고/출처

공식 문서: FSD Tutorial
공식 문서: Next.js Documentation
공식 문서: React Documentation