주요 콘텐츠로 건너뛰기

NextJS와 함께 사용하기

NextJS에서도 FSD 아키텍처를 적용할 수 있지만, NextJS의 기본 프로젝트 구조와 FSD 원칙 간에 몇 가지 충돌이 발생할 수 있습니다.

주요 차이점​

  • NextJS의 pages 폴더와 FSD의 pages layer 간의 이름 충돌
  • NextJS 13 이전 버전에서는 FSD의 app layer에 해당하는 명확한 폴더 구조가 없음

FSD와 NextJS의 pages layer 충돌​

NextJS는 파일 시스템 기반 라우팅을 위해 pages 폴더를 사용하며, 해당 폴더 내 파일이 자동으로 라우트에 매핑됩니다. 그러나 이 방식은 FSD의 pages layer 개념과 충돌하며, 특히 FSD에서 권장하는 평탄한(flat) slice 구조를 NextJS의 중첩 라우팅 방식에서 유지하기 어려운 문제가 있습니다.

NextJS의 pages 폴더를 루트 폴더로 이동 (권장)​

가장 권장되는 방법은 NextJS의 pages 폴더를 프로젝트 루트에 배치하고, FSD 구조는 src 폴더 내에서 유지하는 것입니다. 이렇게 하면 NextJS의 라우팅 시스템을 그대로 활용하면서도 FSD 아키텍처를 온전히 적용할 수 있습니다.

├── pages              # NextJS의 라우팅 시스템용 폴더
├── src
│   ├── app
│   ├── entities
│   ├── features
│   ├── pages          # FSD의 pages layer
│   ├── shared
│   ├── widgets

FSD 구조 내 pages 폴더 이름 변경하기​

다른 방법으로는 FSD의 pages layer 이름을 변경하여 NextJS의 pages 폴더와의 충돌을 방지하는 것입니다. 예를 들어, pages를 views로 변경하면 NextJS의 라우팅 시스템과 FSD 구조를 동시에 유지할 수 있습니다.

├── app
├── entities
├── features
├── pages              # NextJS 라우팅용 폴더
├── views              # 이름이 변경된 FSD pages layer
├── shared
├── widgets

폴더 이름을 변경한 경우, 프로젝트의 README나 내부 문서에 이를 명확하게 기록하는 것이 중요합니다. 이러한 변경 사항은 "프로젝트 지식"의 일부로 문서화하여 팀원들이 쉽게 이해할 수 있도록 해야 합니다.

NextJS에서 FSD의 app layer 구현하기​

NextJS 13 이전 버전에서는 FSD의 app layer에 해당하는 명확한 폴더 구조가 제공되지 않았습니다. 대신 pages/_app.tsx 파일이 애플리케이션의 진입점 역할을 하며, 전역 상태 및 레이아웃을 관리합니다.

pages/_app.tsx에 app layer 기능 통합하기​

FSD의 app layer 개념을 NextJS에 적용하려면, app 폴더에 애플리케이션의 프로바이더와 레이아웃 구성을 정의한 후, 이를 pages/_app.tsx에서 가져와 사용할 수 있습니다.

// app/providers/index.tsx

const App = ({ Component, pageProps }: AppProps) => {
  return (
    <Provider1>
      <Provider2>
        <BaseLayout>
            <Component {...pageProps} />
        </BaseLayout>
      </Provider2>
    </Provider1>
  );
};

export default App;

그다음, pages/_app.tsx에서 App 컴포넌트를 가져와 NextJS의 진입점으로 설정하고, 전역 스타일을 로드할 수 있습니다.

// pages/_app.tsx

import 'app/styles/index.scss'

export { default } from 'app/providers';

App Router 사용하기​

NextJS 13.4 버전부터 정식 지원되는 App Router는 pages 폴더 대신 app 폴더를 통해 라우팅을 구현합니다. FSD 아키텍처를 App Router와 함께 사용할 때도 앞서 설명한 것과 유사한 방식으로 구조를 설정할 수 있습니다.

NextJS의 app 폴더를 프로젝트 루트에 배치하고, FSD의 app layer는 src 폴더 내에서 유지하는 것이 좋습니다. 또한, App Router와 Pages Router는 함께 사용할 수 있으므로, 필요에 따라 두 라우팅 시스템을 모두 활용할 수도 있습니다.

├── app                # NextJS의 App Router용 폴더
├── pages              # NextJS의 Pages Router용 폴더 (선택적)
│   ├── README.md      # 폴더의 용도 설명
├── src
│   ├── app            # FSD의 app layer
│   ├── entities
│   ├── features
│   ├── pages          # FSD의 pages layer
│   ├── shared
│   ├── widgets

Open in StackBlitz

참고 자료​