Next.js 15 완벽 가이드 | App Router·Server Actions·Turbopack·Partial Prerendering
이 글의 핵심
Next.js 15의 새로운 기능과 변경사항을 실전 예제로 완벽 정리합니다. App Router, Server Actions, Turbopack, Partial Prerendering, React 19 지원까지 실무에 바로 적용할 수 있는 가이드입니다.
실무 경험 공유: 스트리밍 플랫폼의 관리 대시보드를 Next.js 15로 마이그레이션하면서, Turbopack으로 개발 빌드 시간을 28초에서 6초로 단축하고, Server Actions로 API 코드를 40% 줄인 경험을 바탕으로 작성했습니다.
들어가며: “Next.js 15, 뭐가 달라졌나요?”
Next.js 15의 주요 변화
2024년 10월 출시된 Next.js 15는 성능, 개발자 경험, 안정성에서 큰 도약을 이뤘습니다.
주요 변경사항:
- React 19 정식 지원
- Turbopack 안정화 (개발 빌드 속도 최대 76% 향상)
- Partial Prerendering (PPR) 실험적 지원
- Server Actions 안정화
- Caching 전략 변경 (기본값이 no-cache로)
- Async Request APIs (cookies, headers, params)
flowchart TB
subgraph v14["Next.js 14"]
A1[Pages Router 중심]
A2[fetch 기본 캐싱]
A3[Webpack 기본]
end
subgraph v15["Next.js 15"]
B1[App Router 완성]
B2[fetch 기본 no-cache]
B3[Turbopack 안정화]
B4[React 19 지원]
B5[PPR 실험적 지원]
end
v14 --> v15
실무 문제 시나리오
시나리오 1: 개발 빌드가 너무 느려요
대규모 프로젝트에서 npm run dev 시작이 30초 이상 걸립니다. Turbopack으로 전환하면 5초 이내로 단축됩니다.
시나리오 2: 정적 페이지인데 매번 서버에서 렌더링돼요
Next.js 14에서는 fetch가 기본 캐싱되어 예상치 못한 동작이 발생했습니다. Next.js 15는 명시적 캐싱으로 예측 가능합니다.
시나리오 3: 폼 제출 시 클라이언트 코드가 너무 많아요
Server Actions를 사용하면 클라이언트 번들 크기를 줄이고 서버에서 직접 데이터를 처리할 수 있습니다.
1. Next.js 15 설치 및 마이그레이션
새 프로젝트 생성
npx create-next-app@latest my-app
cd my-app
npm run dev
설치 시 선택사항:
- TypeScript: Yes (권장)
- ESLint: Yes
- Tailwind CSS: Yes (선택)
src/directory: Yes (권장)- App Router: Yes (필수)
- Turbopack: Yes (권장)
기존 프로젝트 업그레이드
npm install next@latest react@latest react-dom@latest
package.json:
{
"dependencies": {
"next": "^15.0.0",
"react": "^19.0.0",
"react-dom": "^19.0.0"
}
}
주요 Breaking Changes
1. Async Request APIs
Before (Next.js 14):
// app/page.tsx
import { cookies, headers } from 'next/headers';
export default function Page() {
const cookieStore = cookies();
const headersList = headers();
// ...
}
After (Next.js 15):
// app/page.tsx
import { cookies, headers } from 'next/headers';
export default async function Page() {
const cookieStore = await cookies();
const headersList = await headers();
// ...
}
2. fetch 기본 캐싱 변경
Before (Next.js 14):
// 기본값: cache: 'force-cache'
const res = await fetch('https://api.example.com/data');
After (Next.js 15):
// 기본값: cache: 'no-store'
const res = await fetch('https://api.example.com/data');
// 캐싱을 원하면 명시적으로
const res = await fetch('https://api.example.com/data', {
cache: 'force-cache'
});
3. Route Handlers의 GET 메서드
Before (Next.js 14):
// app/api/data/route.ts
export async function GET(request: Request) {
// 기본 캐싱됨
return Response.json({ data: 'cached' });
}
After (Next.js 15):
// app/api/data/route.ts
export async function GET(request: Request) {
// 기본 캐싱 안 됨
return Response.json({ data: 'not cached' });
}
// 캐싱을 원하면
export const dynamic = 'force-static';
2. Turbopack으로 개발 속도 향상
Turbopack이란?
Rust로 작성된 차세대 번들러로, Webpack보다 훨씬 빠릅니다.
성능 비교 (Next.js 공식 벤치마크):
- 초기 컴파일: 76% 빠름
- HMR (Hot Module Replacement): 96% 빠름
- 메모리 사용량: 30% 감소
Turbopack 활성화
# 개발 모드에서 Turbopack 사용
npm run dev --turbo
# 또는 package.json에 추가
{
"scripts": {
"dev": "next dev --turbo"
}
}
실전 예제: 대규모 프로젝트
// next.config.js
/** @type {import('next').NextConfig} */
const nextConfig = {
// Turbopack 설정 (기본값으로 활성화됨)
experimental: {
turbo: {
// Turbopack 옵션
rules: {
'*.svg': {
loaders: ['@svgr/webpack'],
as: '*.js',
},
},
},
},
};
module.exports = nextConfig;
실측 결과 (300개 컴포넌트 프로젝트):
- Webpack: 초기 시작 28초
- Turbopack: 초기 시작 6초
- HMR: 0.1초 이내
3. Server Actions 완벽 가이드
Server Actions란?
서버에서 실행되는 함수를 클라이언트에서 직접 호출할 수 있는 기능입니다. API 라우트 없이 폼 제출, 데이터 변경이 가능합니다.
sequenceDiagram
participant Client as 클라이언트
participant SA as Server Action
participant DB as 데이터베이스
Client->>SA: 폼 제출 (POST)
SA->>DB: 데이터 저장
DB-->>SA: 성공
SA-->>Client: 리디렉션/재검증
기본 사용법
// app/actions.ts
'use server';
export async function createPost(formData: FormData) {
const title = formData.get('title') as string;
const content = formData.get('content') as string;
// 데이터베이스 저장
await db.post.create({
data: { title, content }
});
// 캐시 재검증
revalidatePath('/posts');
redirect('/posts');
}
// app/new-post/page.tsx
import { createPost } from '../actions';
export default function NewPostPage() {
return (
<form action={createPost}>
<input name="title" required />
<textarea name="content" required />
<button type="submit">작성</button>
</form>
);
}
고급 패턴: useFormState + useFormStatus
// app/actions.ts
'use server';
import { z } from 'zod';
const schema = z.object({
title: z.string().min(1).max(100),
content: z.string().min(10),
});
export async function createPost(prevState: any, formData: FormData) {
const validatedFields = schema.safeParse({
title: formData.get('title'),
content: formData.get('content'),
});
if (!validatedFields.success) {
return {
errors: validatedFields.error.flatten().fieldErrors,
};
}
await db.post.create({
data: validatedFields.data
});
revalidatePath('/posts');
return { success: true };
}
// app/new-post/page.tsx
'use client';
import { useFormState, useFormStatus } from 'react-dom';
import { createPost } from '../actions';
function SubmitButton() {
const { pending } = useFormStatus();
return (
<button type="submit" disabled={pending}>
{pending ? '작성 중...' : '작성'}
</button>
);
}
export default function NewPostPage() {
const [state, formAction] = useFormState(createPost, null);
return (
<form action={formAction}>
<input name="title" required />
{state?.errors?.title && <p>{state.errors.title}</p>}
<textarea name="content" required />
{state?.errors?.content && <p>{state.errors.content}</p>}
<SubmitButton />
</form>
);
}
Server Actions 보안
// app/actions.ts
'use server';
import { auth } from '@/lib/auth';
export async function deletePost(postId: string) {
const session = await auth();
if (!session?.user) {
throw new Error('Unauthorized');
}
const post = await db.post.findUnique({
where: { id: postId }
});
if (post.authorId !== session.user.id) {
throw new Error('Forbidden');
}
await db.post.delete({
where: { id: postId }
});
revalidatePath('/posts');
}
4. Partial Prerendering (PPR)
PPR이란?
정적 부분과 동적 부분을 하나의 페이지에서 결합하는 기술입니다. 정적 콘텐츠는 즉시 보여주고, 동적 콘텐츠는 스트리밍으로 로드합니다.
flowchart LR
subgraph Page["페이지"]
Static[정적 콘텐츠<br/>즉시 표시]
Dynamic[동적 콘텐츠<br/>Suspense로 스트리밍]
end
Static --> User[사용자]
Dynamic --> User
PPR 활성화
// next.config.js
/** @type {import('next').NextConfig} */
const nextConfig = {
experimental: {
ppr: true,
},
};
module.exports = nextConfig;
실전 예제: 블로그 포스트
// app/posts/[id]/page.tsx
import { Suspense } from 'react';
// 정적 부분: 빌드 시 생성
async function PostContent({ id }: { id: string }) {
const post = await db.post.findUnique({
where: { id },
select: { title: true, content: true, createdAt: true }
});
return (
<article>
<h1>{post.title}</h1>
<time>{post.createdAt.toLocaleDateString()}</time>
<div>{post.content}</div>
</article>
);
}
// 동적 부분: 요청 시 생성
async function PostComments({ id }: { id: string }) {
const comments = await db.comment.findMany({
where: { postId: id },
orderBy: { createdAt: 'desc' }
});
return (
<section>
<h2>댓글 ({comments.length})</h2>
{comments.map(comment => (
<div key={comment.id}>{comment.content}</div>
))}
</section>
);
}
export default function PostPage({ params }: { params: { id: string } }) {
return (
<>
{/* 정적: 즉시 표시 */}
<PostContent id={params.id} />
{/* 동적: 스트리밍 */}
<Suspense fallback={<div>댓글 로딩 중...</div>}>
<PostComments id={params.id} />
</Suspense>
</>
);
}
PPR 최적화 팁
// 동적 부분을 명시적으로 표시
export const dynamic = 'force-static'; // 기본값
// 특정 부분만 동적으로
import { unstable_noStore as noStore } from 'next/cache';
async function DynamicData() {
noStore(); // 이 함수는 캐싱하지 않음
const data = await fetchRealtimeData();
return <div>{data}</div>;
}
5. React 19 통합
React 19의 새로운 기능
Next.js 15는 React 19를 정식 지원합니다.
주요 기능:
- Actions: 폼 제출 간소화
- useOptimistic: 낙관적 업데이트
- use: 프로미스/컨텍스트 읽기
- ref as prop: ref를 일반 prop처럼 사용
useOptimistic 예제
'use client';
import { useOptimistic } from 'react';
import { likePost } from './actions';
export function LikeButton({ postId, initialLikes }: { postId: string; initialLikes: number }) {
const [optimisticLikes, addOptimisticLike] = useOptimistic(
initialLikes,
(state, amount: number) => state + amount
);
async function handleLike() {
addOptimisticLike(1); // 즉시 UI 업데이트
await likePost(postId); // 서버 요청
}
return (
<button onClick={handleLike}>
좋아요 {optimisticLikes}
</button>
);
}
use Hook
'use client';
import { use } from 'react';
export function PostContent({ postPromise }: { postPromise: Promise<Post> }) {
const post = use(postPromise); // 프로미스를 직접 읽음
return (
<article>
<h1>{post.title}</h1>
<p>{post.content}</p>
</article>
);
}
6. 캐싱 전략 완벽 가이드
Next.js 15의 캐싱 레이어
flowchart TB
subgraph Caching["캐싱 레이어"]
A[Request Memoization]
B[Data Cache]
C[Full Route Cache]
D[Router Cache]
end
A --> B --> C --> D
fetch 캐싱
// 캐싱 안 함 (기본값)
const res = await fetch('https://api.example.com/data');
// 캐싱 (재검증 시간 지정)
const res = await fetch('https://api.example.com/data', {
next: { revalidate: 3600 } // 1시간
});
// 영구 캐싱
const res = await fetch('https://api.example.com/data', {
cache: 'force-cache'
});
// 캐싱 안 함 (명시적)
const res = await fetch('https://api.example.com/data', {
cache: 'no-store'
});
캐시 재검증
// app/actions.ts
'use server';
import { revalidatePath, revalidateTag } from 'next/cache';
export async function updatePost(id: string, data: any) {
await db.post.update({ where: { id }, data });
// 특정 경로 재검증
revalidatePath('/posts');
revalidatePath(`/posts/${id}`);
// 태그로 재검증
revalidateTag('posts');
}
// fetch에 태그 지정
const res = await fetch('https://api.example.com/posts', {
next: { tags: ['posts'] }
});
라우트 레벨 캐싱
// app/posts/page.tsx
// 정적 생성 (기본값)
export const dynamic = 'force-static';
// 동적 렌더링
export const dynamic = 'force-dynamic';
// 재검증 시간 지정
export const revalidate = 3600; // 1시간
// ISR (Incremental Static Regeneration)
export const revalidate = 60; // 60초마다 재생성
7. 성능 최적화 패턴
이미지 최적화
import Image from 'next/image';
export function ProductCard({ product }: { product: Product }) {
return (
<div>
<Image
src={product.image}
alt={product.name}
width={300}
height={300}
placeholder="blur"
blurDataURL={product.blurDataURL}
loading="lazy"
sizes="(max-width: 768px) 100vw, (max-width: 1200px) 50vw, 33vw"
/>
<h3>{product.name}</h3>
</div>
);
}
폰트 최적화
// app/layout.tsx
import { Inter, Noto_Sans_KR } from 'next/font/google';
const inter = Inter({
subsets: ['latin'],
display: 'swap',
variable: '--font-inter',
});
const notoSansKR = Noto_Sans_KR({
subsets: ['latin'],
weight: ['400', '700'],
display: 'swap',
variable: '--font-noto-sans-kr',
});
export default function RootLayout({ children }: { children: React.ReactNode }) {
return (
<html lang="ko" className={`${inter.variable} ${notoSansKR.variable}`}>
<body>{children}</body>
</html>
);
}
스트리밍 SSR
// app/dashboard/page.tsx
import { Suspense } from 'react';
async function SlowComponent() {
await new Promise(resolve => setTimeout(resolve, 3000));
return <div>느린 컴포넌트</div>;
}
export default function DashboardPage() {
return (
<div>
<h1>대시보드</h1>
{/* 즉시 표시 */}
<div>빠른 콘텐츠</div>
{/* 스트리밍 */}
<Suspense fallback={<div>로딩 중...</div>}>
<SlowComponent />
</Suspense>
</div>
);
}
번들 크기 최적화
// 동적 import
import dynamic from 'next/dynamic';
const HeavyComponent = dynamic(() => import('./HeavyComponent'), {
loading: () => <p>로딩 중...</p>,
ssr: false, // 클라이언트에서만 로드
});
export default function Page() {
return (
<div>
<HeavyComponent />
</div>
);
}
8. 실전 예제: 풀스택 블로그
프로젝트 구조
app/
├── (auth)/
│ ├── login/
│ │ └── page.tsx
│ └── register/
│ └── page.tsx
├── (main)/
│ ├── page.tsx
│ ├── posts/
│ │ ├── page.tsx
│ │ ├── [id]/
│ │ │ └── page.tsx
│ │ └── new/
│ │ └── page.tsx
│ └── layout.tsx
├── api/
│ └── posts/
│ └── route.ts
├── actions.ts
└── layout.tsx
데이터베이스 (Prisma)
// prisma/schema.prisma
model Post {
id String @id @default(cuid())
title String
content String
published Boolean @default(false)
authorId String
author User @relation(fields: [authorId], references: [id])
createdAt DateTime @default(now())
updatedAt DateTime @updatedAt
comments Comment[]
}
model Comment {
id String @id @default(cuid())
content String
postId String
post Post @relation(fields: [postId], references: [id])
authorId String
author User @relation(fields: [authorId], references: [id])
createdAt DateTime @default(now())
}
model User {
id String @id @default(cuid())
email String @unique
name String
posts Post[]
comments Comment[]
}
Server Actions
// app/actions.ts
'use server';
import { auth } from '@/lib/auth';
import { prisma } from '@/lib/prisma';
import { revalidatePath } from 'next/cache';
import { redirect } from 'next/navigation';
import { z } from 'zod';
const postSchema = z.object({
title: z.string().min(1).max(100),
content: z.string().min(10),
});
export async function createPost(formData: FormData) {
const session = await auth();
if (!session?.user) {
throw new Error('Unauthorized');
}
const validatedFields = postSchema.parse({
title: formData.get('title'),
content: formData.get('content'),
});
const post = await prisma.post.create({
data: {
...validatedFields,
authorId: session.user.id,
},
});
revalidatePath('/posts');
redirect(`/posts/${post.id}`);
}
export async function deletePost(postId: string) {
const session = await auth();
if (!session?.user) {
throw new Error('Unauthorized');
}
const post = await prisma.post.findUnique({
where: { id: postId },
});
if (post?.authorId !== session.user.id) {
throw new Error('Forbidden');
}
await prisma.post.delete({
where: { id: postId },
});
revalidatePath('/posts');
redirect('/posts');
}
포스트 목록 페이지
// app/(main)/posts/page.tsx
import { prisma } from '@/lib/prisma';
import Link from 'next/link';
export const revalidate = 60; // 60초마다 재생성
export default async function PostsPage() {
const posts = await prisma.post.findMany({
where: { published: true },
include: {
author: {
select: { name: true },
},
_count: {
select: { comments: true },
},
},
orderBy: { createdAt: 'desc' },
});
return (
<div>
<h1>블로그 포스트</h1>
<Link href="/posts/new">새 글 작성</Link>
<ul>
{posts.map(post => (
<li key={post.id}>
<Link href={`/posts/${post.id}`}>
<h2>{post.title}</h2>
<p>
{post.author.name} · {post.createdAt.toLocaleDateString()}
· 댓글 {post._count.comments}
</p>
</Link>
</li>
))}
</ul>
</div>
);
}
포스트 상세 페이지 (PPR)
// app/(main)/posts/[id]/page.tsx
import { Suspense } from 'react';
import { prisma } from '@/lib/prisma';
import { notFound } from 'next/navigation';
// 정적 부분
async function PostContent({ id }: { id: string }) {
const post = await prisma.post.findUnique({
where: { id },
include: {
author: {
select: { name: true },
},
},
});
if (!post) notFound();
return (
<article>
<h1>{post.title}</h1>
<p>
{post.author.name} · {post.createdAt.toLocaleDateString()}
</p>
<div>{post.content}</div>
</article>
);
}
// 동적 부분
async function PostComments({ id }: { id: string }) {
const comments = await prisma.comment.findMany({
where: { postId: id },
include: {
author: {
select: { name: true },
},
},
orderBy: { createdAt: 'desc' },
});
return (
<section>
<h2>댓글 ({comments.length})</h2>
{comments.map(comment => (
<div key={comment.id}>
<p>{comment.content}</p>
<small>
{comment.author.name} · {comment.createdAt.toLocaleDateString()}
</small>
</div>
))}
</section>
);
}
export default function PostPage({ params }: { params: { id: string } }) {
return (
<>
<PostContent id={params.id} />
<Suspense fallback={<div>댓글 로딩 중...</div>}>
<PostComments id={params.id} />
</Suspense>
</>
);
}
9. 자주 하는 실수와 해결법
문제 1: “cookies is not a function”
원인: Next.js 15에서 cookies()가 async 함수로 변경됨.
// ❌ 잘못된 코드
import { cookies } from 'next/headers';
export default function Page() {
const cookieStore = cookies(); // 에러!
}
// ✅ 올바른 코드
import { cookies } from 'next/headers';
export default async function Page() {
const cookieStore = await cookies();
}
문제 2: fetch 캐싱 예상과 다름
원인: Next.js 15는 기본값이 no-store로 변경됨.
// ❌ 캐싱 안 됨 (기본값)
const res = await fetch('https://api.example.com/data');
// ✅ 캐싱하려면 명시적으로
const res = await fetch('https://api.example.com/data', {
next: { revalidate: 3600 }
});
문제 3: Server Actions에서 redirect 안 됨
원인: redirect()는 예외를 던지므로 try-catch로 감싸면 안 됨.
// ❌ 잘못된 코드
export async function createPost(formData: FormData) {
try {
await db.post.create({ data: {...} });
redirect('/posts'); // 예외가 catch됨!
} catch (error) {
return { error: 'Failed' };
}
}
// ✅ 올바른 코드
export async function createPost(formData: FormData) {
try {
await db.post.create({ data: {...} });
} catch (error) {
return { error: 'Failed' };
}
redirect('/posts'); // try-catch 밖에서
}
문제 4: Turbopack에서 특정 패키지 에러
원인: 일부 패키지가 Turbopack과 호환되지 않음.
// next.config.js
/** @type {import('next').NextConfig} */
const nextConfig = {
experimental: {
turbo: {
// 특정 패키지는 Webpack으로 처리
resolveAlias: {
'problematic-package': 'problematic-package/dist/index.js',
},
},
},
};
module.exports = nextConfig;
10. 배포 및 프로덕션 최적화
Vercel 배포
# Vercel CLI 설치
npm i -g vercel
# 배포
vercel
# 프로덕션 배포
vercel --prod
환경 변수
# .env.local
DATABASE_URL="postgresql://..."
NEXTAUTH_SECRET="..."
NEXTAUTH_URL="http://localhost:3000"
// next.config.js
/** @type {import('next').NextConfig} */
const nextConfig = {
env: {
NEXT_PUBLIC_API_URL: process.env.NEXT_PUBLIC_API_URL,
},
};
module.exports = nextConfig;
성능 모니터링
// app/layout.tsx
import { SpeedInsights } from '@vercel/speed-insights/next';
import { Analytics } from '@vercel/analytics/react';
export default function RootLayout({ children }: { children: React.ReactNode }) {
return (
<html lang="ko">
<body>
{children}
<SpeedInsights />
<Analytics />
</body>
</html>
);
}
정리 및 체크리스트
핵심 요약
- Next.js 15는 React 19, Turbopack, PPR로 성능과 개발 경험이 크게 향상됨
- Turbopack으로 개발 빌드 속도 최대 76% 향상
- Server Actions로 API 라우트 없이 서버 로직 실행
- Partial Prerendering으로 정적+동적 콘텐츠 최적 결합
- 캐싱 전략 변경으로 더 예측 가능한 동작
마이그레이션 체크리스트
-
cookies(),headers(),params를 async로 변경 - fetch 캐싱 동작 확인 및 명시적 설정
- Route Handlers의 GET 메서드 캐싱 확인
- Turbopack 활성화 및 테스트
- Server Actions로 폼 처리 마이그레이션
- PPR 실험적 기능 테스트
- 성능 벤치마크 측정
같이 보면 좋은 글
- React 18 완벽 가이드 | Concurrent Rendering·Suspense·useTransition
- 웹 보안 완벽 가이드 | OWASP Top 10·XSS·CSRF·JWT
- Kubernetes 실전 가이드 | Pod·Service·Deployment·Ingress
이 글에서 다루는 키워드
Next.js, React, App Router, Server Actions, Turbopack, Partial Prerendering, SSR, ISR, 캐싱, 성능 최적화
자주 묻는 질문 (FAQ)
Q. Next.js 14에서 15로 업그레이드해야 하나요?
A. 새 프로젝트는 15를 권장합니다. 기존 프로젝트는 Turbopack과 PPR의 이점이 크다면 업그레이드하세요. Breaking changes가 있으므로 테스트 후 적용하세요.
Q. Turbopack은 프로덕션에서도 사용할 수 있나요?
A. 아직 개발 모드에서만 안정화되었습니다. 프로덕션 빌드는 여전히 Webpack을 사용합니다.
Q. Server Actions vs API Routes, 언제 뭘 쓰나요?
A. 폼 제출, 데이터 변경은 Server Actions를 권장합니다. 외부 API 제공, 복잡한 인증 로직은 API Routes를 사용하세요.
Q. PPR을 사용하면 무조건 빠른가요?
A. 정적 콘텐츠가 많고 일부만 동적일 때 효과적입니다. 전체가 동적이면 일반 SSR이 나을 수 있습니다.