Next.js 16 Launchpad은(는) 무엇을 하나요?
Next.js 16: Turbopack 기본 설정 (빌드 속도 2~5배 향상), Cache Components ('use cache'), 그리고 명시적 제어를 위한 proxy.ts.
사용 시점
✅ Next.js 16, Turbopack, Cache Components, proxy 마이그레이션, App Router, React 19.2
❌ Pages Router, Next.js ≤15, 일반적인 React 질문
요구 사항
| 도구 | 버전 |
|---|---|
| Node.js | 20.9.0+ |
| TypeScript | 5.1.0+ |
| React | 19.2+ |
빠른 시작
# 새 프로젝트
npx create-next-app@latest my-app
# 기존 프로젝트 업그레이드
npx @next/codemod@canary upgrade latest
npm install next@latest react@latest react-dom@latest
권장: TypeScript, ESLint, Tailwind, App Router, Turbopack, @/* 별칭.
최소 설정
// app/layout.tsx
export default function RootLayout({ children }: { children: React.ReactNode }) {
return (
<html lang="en">
<body>{children}</body>
</html>
)
}
// app/page.tsx
export default function Page() {
return <h1>Hello, Next.js 16!</h1>
}
설정
// next.config.ts
import type { NextConfig } from 'next'
const nextConfig: NextConfig = {
cacheComponents: true,
reactCompiler: true,
}
export default nextConfig
v15 → v16 변경 사항
| v15 | v16 |
|---|---|
experimental.turbopack | 기본값 |
experimental.ppr | cacheComponents |
middleware.ts (Edge) | proxy.ts (Node) |
동기 params | await params |
핵심 패턴
1. 서버 컴포넌트 (기본값)
export default async function BlogPage() {
const res = await fetch('https://api.example.com/posts')
const posts = await res.json()
return <PostList posts={posts} />
}
2. 캐시 컴포넌트
import { cacheLife } from 'next/cache'
export default async function BlogPage() {
'use cache'
cacheLife('hours')
const posts = await fetch('https://api.example.com/posts').then(r => r.json())
return <PostList posts={posts} />
}
3. 클라이언트 컴포넌트
'use client'
import { useState } from 'react'
export default function Counter() {
const [count, setCount] = useState(0)
return (
<div>
<p>Count: {count}</p>
<button onClick={() => setCount(count + 1)}>+</button>
</div>
)
}
4. 프록시 경계
// app/proxy.ts
export function proxy(request: NextRequest) {
if (!request.cookies.get('auth') && request.nextUrl.pathname.startsWith('/dashboard')) {
return NextResponse.redirect(new URL('/login', request.url))
}
return NextResponse.next()
}
5. 캐시 태그 + 서버 액션
// app/blog/page.tsx
'use cache'
cacheLife('hours')
cacheTag('blog-posts')
export default async function BlogList() {
const posts = await db.posts.findMany()
return <PostList posts={posts} />
}
// app/actions.ts
'use server'
import { updateTag } from 'next/cache'
export async function createPost(data: PostData) {
await db.posts.create(data)
updateTag('blog-posts')
}
6. Suspense를 사용한 스트리밍
export default function Dashboard() {
return (
<div>
<Suspense fallback={<Skeleton />}>
<RevenueCard />
</Suspense>
<Suspense fallback={<Skeleton />}>
<UsersCard />
</Suspense>
</div>
)
}
async function RevenueCard() {
const data = await db.analytics.revenue()
return <div>{data}</div>
}
핵심 개념
- Turbopack - Rust 번들러, 증분 컴파일, Fast Refresh
- 서버 컴포넌트 -
app/에서 기본값, 클라이언트 JS 없음 - 클라이언트 컴포넌트 -
'use client', 훅, 브라우저 API - 캐시 컴포넌트 -
'use cache'+cacheLife()for PPR - 프록시 경계 - 인증/재작성/리디렉션을 위한
proxy.ts - 부분 사전 렌더링(PPR) - 정적 셸 + 동적 스트리밍
마이그레이션 체크리스트
-
비동기 요청 API
npx @next/codemod@canary async-request-api업데이트:
const { slug } = await params -
middleware.ts → proxy.ts
- 파일 이름 변경,
proxy내보내기 - Node 런타임만 사용 (Edge 아님)
- 파일 이름 변경,
-
설정 업데이트
experimental.*플래그 제거cacheComponents,reactCompiler활성화serverRuntimeConfig/publicRuntimeConfig제거
-
캐시 컴포넌트
experimental.ppr을cacheComponents: true로 교체- 동적 섹션을
<Suspense>로 감싸기
-
이미지
- 쿼리 문자열을 위한
images.localPatterns설정
- 쿼리 문자열을 위한
전체 가이드는 references/nextjs16-migration-playbook.md를 참조하세요.
일반적인 함정
❌ 'use cache'와 런타임 API(cookies(), headers()) 혼용
❌ 캐시 컴포넌트 활성화 시 <Suspense> 누락
❌ Turbopack에서 틸드(~) Sass 임포트 사용
❌ Edge 런타임에서 proxy.ts 실행
✅ 먼저 쿠키/헤더를 읽어 캐시된 컴포넌트에 props로 전달
✅ 동적 자식을 <Suspense>로 감싸기
✅ 표준 Sass 임포트 사용
✅ 프록시에는 Node 런타임 사용
의사 결정 가이드
캐시 컴포넌트를 활성화할까요? → 예: 정적/반정적 콘텐츠인 경우 → 아니요: 완전 동적 대시보드인 경우
인증은 어디에 구현하나요?
→ proxy.ts: 라우트 간 검사
→ 라우트 핸들러: API별 로직
'use client'는 언제 사용하나요?
→ 훅, 상태, 브라우저 API가 필요할 때만
→ 프레젠테이셔널 컴포넌트는 서버 측 유지
프로덕션 패턴
전자상거래
// Product page with streaming
export default async function Product({ params }) {
const { id } = await params
const product = await db.products.findById(id)
return (
<>
<ProductInfo product={product} />
<Suspense fallback={<ReviewsSkeleton />}>
<Reviews productId={id} />
</Suspense>
</>
)
}
인증된 대시보드
// proxy.ts
export function proxy(request: NextRequest) {
const session = request.cookies.get('session')
if (!session && request.nextUrl.pathname.startsWith('/dashboard')) {
return NextResponse.redirect(new URL('/login', request.url))
}
}
더 많은 청사진은 references/nextjs16-advanced-patterns.md를 참조하세요.
성능
- Turbopack을 활성화 상태로 유지 (필요한 경우에만
--webpack으로 비활성화) Promise.all로 데이터 가져오기 병렬화- 스트리밍 경계를 위해
<Suspense>사용 - 대규모 저장소의 경우 파일 시스템 캐시 활성화
보안
server-only패키지 + React Taint API 사용proxy.ts에서 인증 유지- 서버 액션에서 입력 유효성 검사
NEXT_PUBLIC_접두사로 env 변수 관리- 캐시된 범위 전에 쿠키/헤더 추출
배포
- Vercel: 무설정 배포
- Docker/Node:
output: 'standalone' - 빌드 시간 모니터링 (2~5배 속도 향상 예상)
- CDN에 맞게 캐시 수명 주기 설정
참조 파일
- references/nextjs16-reference.md - 설치/설정/체크리스트
- references/nextjs16-migration-playbook.md - codemod를 사용한 마이그레이션 가이드
- references/nextjs16-advanced-patterns.md - 스트리밍, 캐싱, 인증 패턴
- references/NEXTJS_16_COMPLETE_GUIDE.md - 전체 문서
- scripts/bootstrap-nextjs16.ps1 - 자동 설정 스크립트
- assets/app-router-starter/ - 참조 구현
리소스
버전: 1.1.0 | 업데이트: 2025-12-27