THE DEVLOG

scribbly.

검색전체 게시글지식 지도
Next JS 치트 시트

2025.05.09 21:18:13

Next JS 프로젝트 생성

1. 프로젝트 생성 (Create Next App)

Next.js 프로젝트는 공식 CLI 도구인 create-next-app을 통해 빠르게 생성할 수 있다.
npx create-next-app@latest

실행 후, 아래와 같은 선택지를 안내받는다. 최신 권장사항은 다음과 같다:

  • TypeScript 사용 여부: Yes
  • App Router 사용 여부: Yes
  • Tailwind CSS 사용 여부: Yes (선택 사항)
  • ESLint, Prettier 설정: Yes (권장)

2. App Router 폴더 구조

App Router를 사용하면, 모든 라우팅은 app/ 디렉토리를 기준으로 동작한다. 기본 폴더 구조는 다음과 같다:

my-app/
├── app/
│   ├── layout.tsx     # 공통 레이아웃
│   ├── page.tsx       # 루트 경로 페이지 (/)
│   └── about/
│       └── page.tsx   # /about 페이지
├── public/            # 정적 파일 (favicon, 이미지 등)
├── styles/            # 전역 스타일
├── next.config.js     # Next.js 설정 파일
  • layout.tsx: 해당 디렉토리 하위 모든 페이지에 공통 적용되는 레이아웃을 정의한다.
  • page.tsx: 해당 경로의 최상위 페이지 컴포넌트를 정의한다.
  • 폴더명은 경로(URL)를 의미하며, 중첩 라우팅도 가능하다.

3. App Router의 핵심 개념

App Router는 React의 최신 기능들과 Next.js만의 기능들을 결합하여 다음과 같은 특징을 가진다:

  • React Server Components 지원
  • 스트리밍(Streaming) 기반의 점진적 렌더링
  • 파일 시스템 기반 동적 라우팅 ([id], (group), @slot 등)
  • 자동 로딩 상태 처리 (loading.tsx)
  • 자동 에러 바운더리 처리 (error.tsx)
  • 서버 액션(Server Actions) 및 캐싱 전략 강화
  • 메타데이터 설정 (generateMetadata)

4. 개발 서버 실행

프로젝트 디렉토리로 이동한 후 다음 명령어를 실행한다:

cd my-app
npm run dev

기본적으로 http://localhost:3000에서 개발 서버가 실행된다.

5. 배포 (Vercel 기준)

Next.js는 Vercel에서 공식적으로 관리되므로, 배포도 매우 간편하다. CLI를 통해 다음과 같이 배포할 수 있다:

npm install -g vercel
vercel

명령어를 실행하면 로그인 및 프로젝트 설정 후 자동으로 배포가 이루어진다. 정적 자산 및 서버 컴포넌트도 Vercel의 CDN 및 Edge 네트워크에 의해 최적화된다.

Routing

Next js는 파일 시스템 기반 라우팅을 하며, 폴더명으로 라우팅 경로가 정해진다.

기본 라우팅 구조

app/ 디렉터리 내의 폴더와 파일 구조가 URL 경로를 결정한다

  • app/page.tsx → /
  • app/about/page.tsx → /about
  • app/blog/page.tsx → /blog

이러한 구조를 통해 명시적인 라우팅 설정 없이도 페이지를 구성할 수 있다

중첩 라우팅 (Nested Routing)

디렉터리 내에 또 다른 디렉터리를 생성하여 중첩된 라우팅을 구현할 수 있다.

예시:

app/
├── dashboard/
│   ├── page.tsx       → /dashboard
│   └── settings/
│       └── page.tsx   → /dashboard/settings

이러한 구조를 통해 계층적인 페이지 구성을 할 수 있으며, 각 수준에서 별도의 레이아웃을 적용할 수도 있다.

동적 라우팅 (Dynamic Routing)

경로의 일부를 동적으로 처리하려면 대괄호 []를 사용한다.

예시:

app/
└── blog/
    └── [slug]/
        └── page.tsx   → /blog/:slug

위 구조에서 /blog/hello-world와 같은 경로는 params.slug를 통해 접근할 수 있습니다.

Next js 15에서는 slug를 Promise로 접근한다.

export default async function Page({
  params,
}: {
  params: Promise<{ slug: string }>
}) {
  const { slug } = await params
  return <div>My Post: {slug}</div>
}

Catch-all 및 Optional Catch-all 라우팅

  • [...slug] : 다중 경로 세그먼트를 배열로 캡처한다. 예: /blog/a/b/c → params.slug = ['a', 'b', 'c']
  • [[...slug]] : 선택적 다중 경로 세그먼트를 캡처한다. 예: /blog 또는 /blog/a/b 모두 매칭된다.(Next.js)

4. 라우트 그룹 (Route Groups)과 소괄호 ()

소괄호로 감싼 디렉터리는 URL 경로에 영향을 주지 않으며, 파일 구조를 정리하거나 특정 레이아웃을 적용하는 데 사용된다.

예시:

app/
├── (marketing)/
│   └── about/
│       └── page.tsx   → /about
├── (shop)/
│   └── about/
│       └── page.tsx   → /about

위 구조에서 (marketing)과 (shop)은 URL에 나타나지 않지만, 각각의 about 페이지는 서로 다른 레이아웃을 적용할 수 있다.

라우트 그룹을 사용하면 다음과 같은 이점이 있습니다:

  • 코드 조직화: 관련된 파일들을 그룹화하여 관리하기 쉬움
  • 레이아웃 분리: 같은 경로에 대해 다른 레이아웃을 적용 가능
  • URL 경로 유지: 파일 구조 변경 없이도 URL 경로를 유지할 수 있음

정리

  • 기본 라우팅: app/ 디렉터리의 구조가 URL 경로를 결정
  • 중첩 라우팅: 디렉터리 내에 하위 디렉터리를 생성하여 계층적 라우팅 구현
  • 동적 라우팅: 대괄호 []를 사용하여 경로의 일부를 동적으로 처리
  • 라우트 그룹: 소괄호 ()를 사용하여 파일 구조를 정리하거나 레이아웃을 분리