[Next.js] Next.js 13 프로젝트 구조 설계하기

Next.js 13에서 프로젝트 구조 설계의 중요성 🤔

Next.js 13 버전부터 App Router와 React Server Components 같은 최신 기능이 추가되며 프로젝트 설계 방식에 많은 변화가 생겼음. 특히 app/ 폴더를 중심으로 파일 기반 라우팅과 데이터 페칭 방식이 바뀌어 프로젝트 구조를 더 효율적이고 깔끔하게 설계할 수 있게 되었음.

Next.js 13의 기본 폴더 구조 🗂️

Next.js 13의 기능에 맞춰 아래와 같이 폴더 구조를 확장할 수 있음. 이 구조는 기능별로 파일을 분리하여 유지보수성과 코드 가독성을 높여줌.

project-root/
├── app/
│   ├── layout.js            # 전역 레이아웃
│   ├── error.js             # 오류 페이지
│   ├── loading.js           # 로딩 스피너
│   ├── global.css           # 전역 스타일
│   ├── dashboard/           # 중첩 경로 예시
│   │   ├── layout.js        # 대시보드 전용 레이아웃
│   │   └── page.js          # 대시보드 페이지
│   └── ...                  # 추가 라우팅 경로
├── components/              # 재사용 가능한 컴포넌트
├── hooks/                   # 커스텀 훅 모음
├── lib/                     # 유틸리티 함수 및 API 호출
├── services/                # API 서비스 함수
├── store/                   # 전역 상태 관리
├── styles/                  # 스타일 파일 모음
├── public/                  # 정적 파일
├── types/                   # 타입 정의 파일
└── next.config.js           # Next.js 설정 파일

app/ - App Router 기반 라우팅 및 서버 컴포넌트 활용

Next.js 13에서는 app/ 폴더를 중심으로 페이지 컴포넌트, 레이아웃, 로딩 상태, 에러 페이지를 구성할 수 있음. 이 폴더 안에서의 파일 이름이 곧 URL 경로로 매핑되며, 각 폴더는 특정 페이지의 경로를 나타냄.

app/
├── layout.js            # 공통 레이아웃
├── error.js             # 에러 페이지
├── loading.js           # 로딩 화면
└── dashboard/           # /dashboard 경로
    ├── layout.js        # 대시보드 전용 레이아웃
    └── page.js          # 대시보드 메인 페이지

레이아웃 파일은 모든 하위 페이지에 공통으로 적용될 레이아웃을 설정하고, 로딩 파일은 페이지 로드 중에 표시되는 로딩 화면을 정의함. 에러 파일을 통해 오류가 발생할 경우 나타나는 페이지도 쉽게 구성할 수 있음.

components/ - UI 컴포넌트

components/ 폴더는 애플리케이션에서 재사용 가능한 UI 컴포넌트를 모아두는 곳임. Next.js 13에서는 클라이언트 전용 컴포넌트와 서버 전용 컴포넌트를 함께 사용하기 때문에, 이 폴더를 서버 전용과 클라이언트 전용 컴포넌트로 분리하는 것이 좋음.

components/
├── server/                # 서버 전용 컴포넌트
└── client/                # 클라이언트 전용 컴포넌트

클라이언트에서만 사용해야 하는 컴포넌트에는 'use client';를 추가하여 명시함.

hooks/ - 커스텀 훅 모음

hooks/ 폴더에는 재사용 가능한 로직을 묶은 커스텀 훅을 관리함. 데이터 페칭, 로컬 상태 관리 등 다양한 로직을 캡슐화하여 컴포넌트에서 반복되는 코드를 줄일 수 있음. 클라이언트 훅의 경우 클라이언트 컴포넌트에서만 사용할 수 있음.

hooks/
├── useFetchData.js       # 데이터 페칭 훅
└── useAuth.js            # 인증 관련 훅

lib/ - 유틸리티 함수 및 API 호출 함수

lib/ 폴더에는 유틸리티 함수와 API 요청 함수를 관리함. API 호출 로직을 분리하면, 컴포넌트의 비즈니스 로직과 API 로직을 분리하여 유지보수를 쉽게 할 수 있음.

lib/
├── api.js                # API 호출 함수 모음
└── utils.js              # 기타 유틸리티 함수들

services/ - API 서비스 함수

services/ 폴더는 API 호출 로직을 캡슐화하여 비즈니스 로직과 분리한 계층임. 이를 통해 각 컴포넌트에서 API 로직을 손쉽게 호출할 수 있으며, 중복 코드가 줄어듦.

services/
├── authService.js        # 인증 관련 API
└── postService.js        # 게시물 관련 API

store/ - 전역 상태 관리

Next.js 13에서는 Redux, Recoil 등 상태 관리 라이브러리를 사용하여 전역 상태를 관리할 수 있음. store/ 폴더는 전역 상태 관리와 관련된 설정 파일을 포함하며, 클라이언트에서 사용할 상태만 여기서 관리함.

store/
├── index.js              # 전역 상태 관리 설정 파일
└── userSlice.js          # 사용자 관련 상태 슬라이스

styles/ 폴더 - 스타일 파일 🎨

styles/ 폴더는 CSS 파일이나 CSS 모듈, 또는 TailwindCSS 설정을 포함하는 곳임. 전역 스타일 파일을 한 곳에서 관리할 수 있으며, Next.js의 CSS 모듈 기능을 통해 컴포넌트별 스타일을 분리할 수 있음.

styles/
├── globals.css           # 전역 스타일
├── variables.css         # CSS 변수
└── components/           # 컴포넌트별 CSS 모듈
    └── Button.module.css

전역 스타일 파일은 app/globals.css에 넣어 전역적으로 적용할 수 있음.

types/ 폴더 - TypeScript 타입 정의 파일 📜

TypeScript를 사용하는 경우 types/ 폴더는 공통 타입을 정의하는 곳임. 프로젝트에서 사용하는 인터페이스나 타입을 모아 관리하면 코드의 안정성과 가독성이 높아짐.

types/
├── index.d.ts            # 공통 타입 정의 파일
└── user.d.ts             # 사용자 관련 타입 정의

Next.js의 전역 설정 파일 🔧

next.config.js
next.config.js 파일은 Next.js의 전역 설정을 관리함. 환경 변수 설정, 이미지 도메인 설정 등을 여기에서 지정할 수 있음.

// next.config.js
module.exports = {
  images: {
    domains: ["example.com"],
  },
  i18n: {
    locales: ["en", "ko"],
    defaultLocale: "en",
  },
};