프론트엔드를 처음 접할 때에는 폴더구조에 대한 중요성이나, 어떻게 구상을 할까라는 고민을 하지않았다.
코드만 잘 짜면 뭐 상관없겠지라는 생각이었다.

하지만 프로젝트 규모가 커지기 시작하면,
폴더 구조는 어느 순간 가장 큰 문제가 된다.

이 파일은 왜 여기에 있지?

이 로직은 어떤 기능을 위한 거지?

이거 수정하면 어디까지 영향이 갈까?

이 글은 내가 실제 프로젝트를 하면서 겪었던 흐름을 바탕으로,
프론트엔드 폴더 구조가 어떻게 변해왔는지,
그리고 왜 FSD까지 이야기하게 되는지를 정리한 글이다.

폴더 구조는 단순한 정리가 아니다

폴더 구조는 파일을 예쁘게 나누는 문제가 아니다.

폴더 구조는
이 프로젝트가 어떤 기준으로 설계되었는지,
어디까지 확장될 수 있는지를 보여준다.

그래서 나는 이렇게 생각하게 됐다.

폴더 구조는 곧 아키텍처다.

기능 중심 구조 (Functional Structure)

프론트엔드에서 가장 흔하게 시작하는 구조다.

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

처음에는 꽤 합리적으로 보인다.

컴포넌트는 components 훅흔 hook에, API 로직은 services 왜 처음엔 좋아 보일까?

규칙이 단순하다
설명이 필요 없다
빠르게 만들 수 있다

소규모 프로젝트나 개인 학습에는 충분히 좋은 구조다.

하지만 규모가 커지면 문제가 생기는데, 프로젝트가 조금만 커져도 이런 상황을 마주하게 된다.

components 안에 의미 없는 컴포넌트가 쌓이고, hooks가 전역 쓰레기통처럼 변한다. 또 특정 페이지에서만 쓰는 로직이 전역에 퍼진다.

결국 이런 질문이 생긴다.

“이 파일은 어떤 기능을 위한 거지?”

기능 중심 구조는 파일의 성격으로만 나눌 뿐,
비즈니스 맥락을 담지 못한다.

도메인 중심 구조 (Domain-based Structure)

기능 중심 구조의 한계를 느끼고 나면,
자연스럽게 도메인 중심 구조로 이동하게 된다.

src/
 ├─ auth/
 │   ├─ components/
 │   ├─ hooks/
 │   ├─ api.ts
 │   └─ types.ts
 ├─ user/
 ├─ payment/
 ├─ common/

이 구조의 핵심 질문은 하나다. 그렇다면 이 코드는 무엇을 위한 코드인가?

도메인 중심 구조의 장점

코드의 맥락이 바로 보인다

auth/ 폴더에 들어가면 로그인, 회원가입과 관련된 코드만 있다.

영향 범위가 제한된다

auth 도메인 내부를 수정하면 대부분 auth 관련 기능에만 영향이 간다.

협업이 쉬워진다

“이건 auth 쪽 로직이야” , “payment 도메인에서 처리하자” 라는 방식으로 구현할 수 있다.

도메인 중심 구조의 한계

하지만 도메인 중심 구조도 완벽하지는 않다.

도메인 내부 구조가 점점 커지기 때문이다.

하나의 도메인 안에 UI, 로직, 상태가 뒤섞여 재사용 기준이 애매해진다.

그리고 이쯤 되면 “도메인 안에서도 역할 기준이 필요하지 않을까?”라는 의문점이 생긴다.

FSD (Feature-Sliced Design)

이 고민에서 등장한 개념이 FSD (Feature-Sliced Design) 다.

FSD는 단순한 폴더 구조가 아니라, 프론트엔드 아키텍처 방법론에 가깝다.

FSD의 핵심 철학

기능(Feature)을 중심으로,
변경 이유가 같은 것끼리 묶는다.

그리고 이를 위해 명확한 레이어를 정의한다.

FSD의 대표적인 레이어 구조

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

아래로 갈수록 범용적,
위로 갈수록 구체적이다.

shared

공통 UI 컴포넌트

공통 유틸

디자인 시스템

shared/
 ├─ ui/
 ├─ lib/
 └─ api/

비즈니스 로직 없음

entities

도메인 모델

핵심 데이터 구조

entities/
└─ user/
├─ model/
└─ api/

“유저란 무엇인가”에 대한 정의

features

하나의 사용자 행동 단위

로그인, 좋아요, 결제 요청 등

features/
└─ login/
├─ ui/
└─ model/

행동 중심

widgets

여러 feature를 조합한 UI 블록

widgets/
└─ header/

pages

실제 라우팅 단위

화면 조립 역할

app

앱 초기화

전역 설정

라우터, 프로바이더

FSD가 주는 가장 큰 장점

변경 이유가 명확해진다

UI 변경 → shared / widgets

기능 변경 → features

데이터 변경 → entities

리팩토링이 쉬워짐.

코드의 책임이 분리된다

페이지는 조립만 한다

비즈니스 로직은 feature에 있다

페이지가 가벼워짐.

대규모 프로젝트에 강하다

팀원이 늘어나도 구조가 유지된다

규칙이 곧 가이드가 된다

그래서, 어떤 구조가 정답일까?

정답은 없다.
대신 단계는 있다.

단계 추천 구조
개인 학습 기능 중심
중소 규모 협업 도메인 중심
대규모 / 장기 프로젝트 FSD

중요한 건
지금 프로젝트에 맞는 구조를 선택하고,
필요하면 바꿀 수 있어야 한다는 것이다.