[동네zip] React 프로젝트에서 Next.js 폴더 기반 라우팅을 도입한 이유와 효과 🏁

 

 

도입 배경 : 구조화의 필요성!

공부하거나 자습할 때는 아주 작은 규모의 프로그램이었기 때문에, 폴더 구조에 대해 고민할 필요가 없었다.

하지만 팀 프로젝트 단위로 확장되자 시작부터가 난관이었다. 특히 리액트는 컴포넌트 분리와 구조화가 아주 중요하기 때문에 고민이 더 길어질 수 밖에 없었다.

 

기획, 디자인이 끝난 직후(약 4일 소요) 바로 개발을 진행해야했고, 남은 기간이 2주 정도로 짧았기 때문에

 

1. 파일 구조로 인한 커뮤니케이션 낭비 줄이기!

2. 개발 생산성 극대화

 

이 2가지 목표를 충족하는 설계가 필요했다.

 

 

결론 : Next.js의 폴더 기반 라우팅 구조 도입

출처 : Next.js@15.2.1

시원하게 결론부터 말하자면!! React 프로젝트였지만 Next.js의 file-base rouing 구조를 차용해 폴더 구조를 설계했다.

이미지는 최신 버전인 15버전인데, 우리 팀에서 채택한 Next.js의 file-base routing은 12버전에 더 가깝다. 각 폴더의 Index.jsx 파일이 진입점이 된다.

• `pages/` 폴더는 URL 경로를 기준으로 구성
• `components/` 폴더는 `pages/`와 동일한 구조로 구성하여 협업 최적화
• 각 폴더의 `index.jsx` 파일은 진입점 역할을 하도록 설계 (Next.js v12 스타일 참고)

 

 

간단한 예시를 살펴보자면 다음과 같다 :

src/
├── pages/
│   └── purchase/
│       ├── index.jsx         # /purchase
│       └── products.jsx      # /purchase/products
├── components/
│   └── purchase/
│       ├── PurchaseForm.jsx
│       └── ProductCard.jsx

 

 

구조 설계의 핵심 포인트

 

1. Next.js 스타일의 file&folder base routing

• 폴더명이 곧 URL이 되도록 구성
• 라우팅 설계 시 폴더 구조만 보고 경로 유추 가능
• 유지 보수성과 협업 시 직관적인 탐색 가능

 

2. components와 pages의 동일 구조

• `components/` 하위 폴더가 `pages/`와 동일한 구조를 가지도록 설계
• 각 페이지에 대응하는 UI 컴포넌트를 같은 위치에서 관리 → 담당 컴포넌트 빠르게 찾기 가능!!

 

3. 역할별 폴더 분리

• `store/` : 상태 관리 (Redux)
• `utils/` : 공통 유틸 함수
• `styles/` : 전역 스타일 및 디자인 토큰 관리

 

4. UI 일관성 유지

• `GlobalStyle`을 통해 디자인 토큰(색상, 폰트 등)을 중앙에서 정의하여 UI/UX 일관성 확보!

 

컴포넌트 분리 기준 선정 과정

 

다소 낯선 Atomic Design System

 

 

기획과 디자인이 완료된 직후, 개발 전에 가장 먼저 논의한 것이 컴포넌트 분리 기준이었다.

짧은 개발 기간과 역할 분담 구조를 고려해 다음 3가지 기준을 검토했다:

 

1. 페이지 단위 분리 (우리 팀이 채택한 방식)

• 라우팅에 직접 연결되는 화면 단위로 분리
• 담당 컴포넌트를 빠르게 찾을 수 있음 

 

2. 도메인 단위 분리

• 기능별 분리. 대규모 프로젝트에 적합하나, 처음 협업하는 팀에게는 진입장벽 존재

 

3. Atomic Design System 기반 분리

• 원자(atom), 분자(molecule), 유기체(organism), 템플릿, 페이지 등으로 쪼갠 디자인 시스템 기반
• 추상화에 대한 이해도가 높아야 하며 학습 곡선이 있
• 이름에서 알 수 있듯이 화학적 관점에서 영감을 얻은 디자인 시스템
• 더 알아보기 ▼

• 이름에서 알 수 있듯이 화학적 관점에서 영감을 얻은 디자인 시스템
• 원자 < 분자 < 유기체 < 템플릿 < 페이지
  • 원자 : 더 이상 분해할 수 없는 기본 컴포넌트 → 예: label, input, button과 같은 기본 HTML 태그 / 글꼴, 애니메이션, 컬러 팔레트 같은 추상적 요소)
  • 분자 : 여러 개의 atom을 결합. 단일 책임 원칙 → 예: 검색 버튼과 인풋창으로 구성된 검색 폼(form) 컴포넌트
  • 유기체 : 원자/분자에 비해 좀 더 명확한 영역과 특정 컨텍스트를 가져 상대적으로 재사용성이 낮음 → 예: 헤더
  • 템플릿 : 원자 ~ 유기체를 조합해 만든 하나의 페이지 틀 = 실제 컨텐츠가 없는 페이지 수준의 스켈레톤, 데이터를 전달 받기 전 페이지 레이아웃
  • 페이지 : 유저가 볼 수 있는 실제 컨텐츠 = 템플릿의 인스턴스

 

 

프론트엔드가 기획, 디자인 단계부터 페이지별로 역할을 나누어 진행했기 때문에 팀원 모두 페이지 단위 분리를 가장 선호했다.

이유는 간단했다.

 

협업 시 내가 맡은 컴포넌트를 찾다가 길을 잃지 않기 위해서 🏁

 

 

 

 

기대 효과 및 실제 성과

기대 효과

• 담당 페이지/컴포넌트 탐색 시 생산성 향상
• 폴더 구조 = 라우팅 구조 → 명확한 경로 설정
• 협업 시 커뮤니케이션 최소화

 

실제 성과

• 기획/디자인 담당자가 직접 개발까지 이어가면서 이해도가 높아져 작업 속도 향상
• 각자의 폴더만 보면 어떤 페이지/컴포넌트를 담당하는지 명확
• 구조에 대한 팀원 전체의 합의가 이뤄졌고, 실제 협업에서 긍정적인 피드백을 받음

 

다만, 배포 직전 일부 라우팅 구조가 문서화와 일치하지 않음을 발견했다.
→ 초기 문서화와 개발 단계의 소통 중요성을 크게 느꼈고, 다음 프로젝트에서는 개선하고 싶다.

 

 

회고

이번 구조 설계 및 초기 환경 설정 경험을 통해 단순히 기술을 적용하는 데 그치지 않고, 협업과 유지 보수성까지 고려한 설계의 중요성을 배울 수 있었다.

또 Next.js의 라우팅 구조와 Atomic Design System에 대해 얕게나마 학습하게 되었고, 다음 프로젝트에서 기회가 있다면 도입해보고 싶다.

 

---

관련 글

[동네zip] 팀 프로젝트 최종 회고 - 인생 첫 팀 리딩, FE 리드가 되다! 😎

https://suyeon-dev.tistory.com/111

쓰는 중

 

---

참고

[Next.js] App Router > Getting Started > Project Structure

[카카오 엔터프라이즈 | FE 기술블로그] 아토믹 디자인을 활용한 디자인 시스템 도입기 (2022.5)

아토믹 디자인 시스템 이미지 출처