liminfoNext.js Reference
Next.js 프레임워크 레퍼런스
Next.js Reference 소개
Next.js 레퍼런스는 Next.js 13에서 도입되고 Next.js 14+에서 완성된 App Router 아키텍처 전체를 다룹니다. [slug] 동적 라우트, [...slug] 포괄 라우트, 괄호를 사용한 라우트 그룹, 그리고 layout.tsx·page.tsx·loading.tsx·error.tsx·not-found.tsx 등의 특수 파일 컨벤션을 빠르게 조회할 수 있습니다. 파일시스템 라우터가 디렉토리 구조를 URL 경로로 어떻게 매핑하는지 에디터를 벗어나지 않고 확인할 수 있습니다.
데이터 페칭 패턴도 이 레퍼런스의 핵심입니다. 서버 컴포넌트에서의 fetch()와 cache·revalidate 옵션, revalidatePath()와 revalidateTag()를 이용한 온디맨드 재검증, loading.tsx 기반의 Suspense 스트리밍, 그리고 cache: "no-store"로 동적 렌더링을 강제하는 방법을 다룹니다. Route Handler(app/api/route.ts)와 Server Action("use server")은 GET/POST 전체 예제와 함께 NextResponse.json() 및 FormData 처리 방법을 포함합니다.
레퍼런스는 라우팅·데이터페칭·API·미들웨어·렌더링·설정의 여섯 카테고리로 구성되어 있어 필요한 API를 즉시 찾을 수 있습니다. 프로덕션 앱을 개발하는 풀스택 TypeScript 개발자, Pages Router에서 마이그레이션 중인 개발자, 현대적인 React를 배우는 부트캠프 수강생이 매일 활용하고 있습니다. next/image 최적화, next/link 네비게이션, next/navigation의 useRouter, SSG를 위한 generateStaticParams, 동적 SEO를 위한 generateMetadata, next.config.js 설정까지 복사 가능한 TypeScript 코드 스니펫이 포함되어 있습니다.
주요 기능
- App Router 파일 컨벤션 — layout.tsx, page.tsx, loading.tsx, error.tsx, not-found.tsx
- 동적 라우트([slug]), 포괄 라우트([...slug]), 괄호 라우트 그룹 패턴
- 서버 컴포넌트 fetch() — cache / revalidate / next.tags 옵션 정리
- revalidatePath()와 revalidateTag()를 이용한 온디맨드 캐시 재검증
- Route Handler(GET, POST)와 Server Action — FormData 처리 예제 포함
- NextRequest 기반 미들웨어 — 쿠키 인증과 matcher 패턴
- generateStaticParams로 SSG 구현, generateMetadata로 동적 Open Graph 설정
- next/image 이미지 최적화, next/link 네비게이션, next.config.js 리다이렉트 설정
자주 묻는 질문
Next.js에서 서버 컴포넌트와 클라이언트 컴포넌트의 차이는 무엇인가요?
서버 컴포넌트는 서버에서만 실행되며 브라우저에 JavaScript를 전송하지 않습니다. 데이터베이스나 파일 시스템에 직접 접근할 수 있고, App Router에서 기본값입니다. 클라이언트 컴포넌트는 파일 최상단에 "use client"를 선언하며 useState, useEffect 같은 React 훅을 사용할 수 있습니다. 브라우저 인터랙티비티나 브라우저 API가 필요할 때만 클라이언트 컴포넌트를 사용하면 됩니다.
Next.js App Router의 캐싱은 어떻게 동작하나요?
Next.js 14는 fetch() 응답을 기본적으로 캐시합니다(force-cache). 완전한 동적 렌더링이 필요하면 { cache: "no-store" }를 사용하고, N초마다 갱신되는 증분 정적 재생성(ISR)에는 { next: { revalidate: N } }을 씁니다. 세밀한 온디맨드 캐시 무효화가 필요하면 { next: { tags: ["posts"] } }로 태그를 붙이고 Server Action 안에서 revalidateTag("posts")를 호출하세요.
Server Action은 무엇이고 언제 사용해야 하나요?
Server Action은 "use server"로 표시된 비동기 함수로, form action이나 클라이언트 이벤트에서 호출될 때 서버에서 실행됩니다. 폼 제출, 데이터베이스 변경, 캐시 무효화를 위한 별도의 API 라우트 파일을 대체합니다. CSRF 보호가 자동으로 처리되며, 변경 로직을 UI와 함께 배치할 수 있습니다. 폼에서 데이터베이스에 쓰거나 서버 전용 API를 호출할 때 사용하세요.
Next.js 미들웨어로 인증을 구현하는 방법은?
프로젝트 루트에 middleware.ts 파일을 만들고 NextRequest를 받는 middleware 함수를 export합니다. 세션 쿠키나 JWT 헤더를 확인하고, 토큰이 없거나 유효하지 않으면 NextResponse.redirect()로 로그인 페이지로 이동시킵니다. config.matcher 배열로 미들웨어가 실행될 경로를 제한할 수 있습니다. 예를 들어 ["/dashboard/:path*"]를 지정하면 대시보드 경로만 보호됩니다.
layout.tsx와 template.tsx의 차이는 무엇인가요?
layout.tsx는 같은 세그먼트 내 탐색에서 상태와 DOM을 유지합니다 — 자식 컴포넌트가 리마운트되지 않습니다. template.tsx는 각 하위 라우트마다 새 인스턴스를 만들어 라우트 변경 시 완전히 리마운트됩니다. 사이드바나 내비게이션 같은 영구적인 UI에는 layout.tsx를 쓰고, 라우트 변경마다 컴포넌트 상태를 초기화하거나 진입 애니메이션이 필요할 때는 template.tsx를 사용하세요.
generateStaticParams는 어떻게 동작하나요?
generateStaticParams는 동적 라우트 페이지에서 export하는 비동기 함수로, 파라미터 객체 배열을 반환합니다. Next.js는 이 배열을 사용해 빌드 시 모든 해당 경로를 정적 HTML로 미리 렌더링합니다. 예를 들어 app/blog/[slug]/page.tsx에서 [{ slug: "post-1" }, { slug: "post-2" }]를 반환하면 각 게시물이 정적으로 빌드됩니다. 반환되지 않은 경로는 요청 시 동적으로 렌더링됩니다.
App Router에서 커스텀 Open Graph 메타데이터를 추가하는 방법은?
정적 메타데이터는 page.tsx나 layout.tsx에서 metadata 객체를 export하면 됩니다. 라우트 파라미터나 서버 데이터를 기반으로 동적으로 생성하려면 generateMetadata 비동기 함수를 export합니다. openGraph 필드에 title, description, images 배열을 포함시키면 Next.js가 자동으로 HTML head에 메타 태그를 삽입해 줍니다. react-helmet이나 next/head를 별도로 import할 필요가 없습니다.
병렬 라우트(Parallel Routes)는 어떤 기능인가요?
병렬 라우트는 @folder 형식의 네임드 슬롯으로 정의되며, 같은 레이아웃에서 여러 페이지를 동시에 렌더링할 수 있습니다. 각 슬롯은 독립적인 loading과 error 경계를 가집니다. 사이드바와 메인 콘텐츠 영역이 서로 독립적인 로딩 상태를 가져야 하는 대시보드 등에 유용합니다.