좋은 폴더 구조?

white noise·2025년 6월 1일

처음 프로젝트를 하게 되면 가장 고민하는 것 중에 하나가 폴더 구조를 어떻게 만들어야 할까에 대한 고민일 것이다. ~~지금도 고민이다~~

그래서 폴더 대충 만들면 되는거 아님? 싶을텐데 폴더 구조를 생각하지 않고 만들다보면 생기는 문제점을 보여주겠다.

문제점

│  App.css
│  App.jsx
│  index.css
│  main.jsx
│
├─components
│      Account.jsx
│      Account.module.css
│      Auth.jsx
│      BannerIcon.jsx
│      BannerIcon.module.css
│      BirthPage.module.css
│      BloodTypePage.module.css
│      ConstellationItem.jsx
│      ConstellationItem.module.css
│      ConstellationPage.module.css
│      Footer.jsx
│      Footer.module.css
│      FortunePage.module.css
│      FortuneResultPage.module.css
│      FortuneTitle.jsx
│      FortuneTitle.module.css
│      Header.jsx
│      Header.module.css
│      Info.jsx
│      Info.module.css
│      KeyResultPage.module.css
│      KeywordPage.module.css
│      ListPage.module.css
│      Loading.jsx
│      Loading.module.css
│      LoginPage.module.css
│      MainView.jsx
│      MainView.module.css
│      Modal.jsx
│      Modal.module.css
│      MyPage.module.css
│      MyPlaylist.jsx
│      MyPlaylist.module.css
│      TestButton.module.css
│      TestFooter.jsx
│      TestFooter.module.css
│      TestMenu.jsx
│      TestMenu.module.css
│
├─images
│      acquarius.png
│      aries.png
│      cancer.png
│      capricorn.png
│      gemini.png
│      leo.png
│      libra.png
│      pisces.png
│      sagittarius.png
│      scorpio.png
│      taurus.png
│      virgo.png
│
└─pages
        BirthPage.jsx
        BloodTypePage.jsx
        ConstellationPage.jsx
        FortunePage.jsx
        FortuneResultPage.jsx
        HomePage.jsx
        KeyResultPage.jsx
        KeywordPage.jsx
        ListPage.jsx
        LoginPage.jsx
        MbtiPage.jsx
        MyPage.jsx
        SignupPage.jsx

부끄러운 내 이전 프로젝트 코드인데, 정리가 되어있지 않다.
팀원님이랑 둘 다 경험이 없어서.. 폴더 정리는 최소한으로 하고 작업했고, 작업하다보니 더욱 폴더가 더러워졌다..

결국 규모가 큰 프로젝트를 만들수록 폴더구조를 더욱 잘 구축해야한다.

그래서! 내가 다음부터 헤매지 않기 위해 한 번 알아보려고 한다.

좋은 폴더 구조

src/
├── assets/
│   ├── images/
│   │   └── logo.png
│   └── styles/
│       └── global.css
├── components/
│   ├── Button.tsx
│   └── Navbar.tsx
├── context/
│   └── AuthContext.tsx
├── data/
│   └── menuItems.ts
├── features/
│   └── user/
│       ├── UserProfile.tsx
│       └── userSlice.ts
│       └── index.ts
├── hooks/
│   └── useAuth.ts
├── layouts/
│   └── MainLayout.tsx
├── lib/
│   └── apiClient.ts
├── pages/
│   ├── Home.tsx
│   └── About.tsx
├── services/
│   └── userService.ts
└── utils/
    └── formatDate.ts

가장 보편적인 폴더구조가 이런 느낌인 것 같다.

하나하나 설명하자면

assets

프로젝트의 모든 사진, 폰트 파일, 전역 스타일 같은 정적 파일들을 보관한다.

components

재사용 가능한 UI 컴포넌트들을 모아두며, 예를 들면 버튼, 모달 등이 있다.

가벼운 프로젝트라면 분리할 필요가 딱히 없지만, 여러 기능들이 있다면 컴포넌트 폴더 아래에 하위 폴더들을 세분화하는 것을 추천한다.
(components 폴더 안에 체크박스, input, 날짜 선택 등을 모아둔 form 폴더를 만들기도 한다.)

context

React Context 관련 파일을 저장한다.

data

assets 폴더와 비슷하지만 보통 더미데이터나 프로그램 내에서 사용되는 정보(store 아이템, 테마 정보 등)가 포함된 JSON 파일, 상수 등을 저장해놓는다.

features

모든 애플리케이션 기능이 포함되어 있다. 비슷한 기능을 묶어놓음으로써 구조를 이해하기 쉽다.

features에 각 기능이 있는 폴더마다 index.ts (or index.js)가 존재한다 이 index.ts가 공개 API처럼 작동하며 다른 도메인에서 무언가를 가져올 때는 이 파일을 통해서 가져오게 된다.

# Bad 🚫 🚫 🚫
import { UserProfile } from '@/features/profile/components/UserProfile.vue'

# Good ✅ ✅ ✅
import { UserProfile } from '@/features/profile'

다만 규모가 작은 프로젝트라면 features는 필요가 없을 수도 있다.
features에는 모든 애플리케이션 기능이 들어가야 해서 pages에는 최소한의 기능만을 유지해야하는데, 소규모 프로젝트라면 features 대신 pages에 페이지마다 기능을 모아둬도 괜찮다.