[2026] 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) 아래 코드는 mermaid를 사용한 구현 예제입니다. 각 부분의 역할을 이해하면서 코드를 살펴보시기 바랍니다.

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: 아래 코드는 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): 아래 코드는 typescript를 사용한 구현 예제입니다. 필요한 모듈을 import하고. 코드를 직접 실행해보면서 동작을 확인해보세요.

// app/page.tsx
import { cookies, headers } from 'next/headers';
export default function Page() {
  const cookieStore = cookies();
  const headersList = headers();
  // ...
}

After (Next.js 15): 아래 코드는 typescript를 사용한 구현 예제입니다. 필요한 모듈을 import하고, 비동기 처리를 통해 효율적으로 작업을 수행합니다. 코드를 직접 실행해보면서 동작을 확인해보세요.

// 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): 아래 코드는 typescript를 사용한 구현 예제입니다. 비동기 처리를 통해 효율적으로 작업을 수행합니다. 코드를 직접 실행해보면서 동작을 확인해보세요.

// 기본값: 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): 아래 코드는 typescript를 사용한 구현 예제입니다. 비동기 처리를 통해 효율적으로 작업을 수행합니다. 코드를 직접 실행해보면서 동작을 확인해보세요.

// app/api/data/route.ts
export async function GET(request: Request) {
  // 기본 캐싱됨
  return Response.json({ data: 'cached' });
}

After (Next.js 15): 아래 코드는 typescript를 사용한 구현 예제입니다. 비동기 처리를 통해 효율적으로 작업을 수행합니다. 코드를 직접 실행해보면서 동작을 확인해보세요.

// 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 활성화

아래 코드는 bash를 사용한 구현 예제입니다. 코드를 직접 실행해보면서 동작을 확인해보세요.

# 개발 모드에서 Turbopack 사용
npm run dev --turbo
# 또는 package.json에 추가
{
  "scripts": {
    "dev": "next dev --turbo"
  }
}

실전 예제: 대규모 프로젝트

다음은 typescript를 활용한 상세한 구현 코드입니다. 각 부분의 역할을 이해하면서 코드를 살펴보시기 바랍니다.

// 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 라우트 없이 폼 제출, 데이터 변경이 가능합니다. 아래 코드는 mermaid를 사용한 구현 예제입니다. 코드를 직접 실행해보면서 동작을 확인해보세요.

sequenceDiagram
    participant Client as 클라이언트
    participant SA as Server Action
    participant DB as 데이터베이스
    Client->>SA: 폼 제출 (POST)
    SA->>DB: 데이터 저장
    DB-->>SA: 성공
    SA-->>Client: 리디렉션/재검증

기본 사용법

다음은 typescript를 활용한 상세한 구현 코드입니다. 비동기 처리를 통해 효율적으로 작업을 수행합니다. 각 부분의 역할을 이해하면서 코드를 살펴보시기 바랍니다.

// 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');
}

아래 코드는 typescript를 사용한 구현 예제입니다. 필요한 모듈을 import하고. 각 부분의 역할을 이해하면서 코드를 살펴보시기 바랍니다.

// 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

다음은 typescript를 활용한 상세한 구현 코드입니다. 필요한 모듈을 import하고, 비동기 처리를 통해 효율적으로 작업을 수행합니다, 에러 처리를 통해 안정성을 확보합니다, 조건문으로 분기 처리를 수행합니다. 각 부분의 역할을 이해하면서 코드를 살펴보시기 바랍니다.

// 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 };
}

다음은 typescript를 활용한 상세한 구현 코드입니다. 필요한 모듈을 import하고, 함수를 통해 로직을 구현합니다, 에러 처리를 통해 안정성을 확보합니다. 각 부분의 역할을 이해하면서 코드를 살펴보시기 바랍니다.

// 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 보안

다음은 typescript를 활용한 상세한 구현 코드입니다. 필요한 모듈을 import하고, 비동기 처리를 통해 효율적으로 작업을 수행합니다, 에러 처리를 통해 안정성을 확보합니다, 조건문으로 분기 처리를 수행합니다. 각 부분의 역할을 이해하면서 코드를 살펴보시기 바랍니다.

// 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이란?

정적 부분과 동적 부분을 하나의 페이지에서 결합하는 기술입니다. 정적 콘텐츠는 즉시 보여주고, 동적 콘텐츠는 스트리밍으로 로드합니다. 아래 코드는 mermaid를 사용한 구현 예제입니다. 코드를 직접 실행해보면서 동작을 확인해보세요.

flowchart LR
    subgraph Page[페이지]
        Static["정적 콘텐츠\n즉시 표시"]
        Dynamic["동적 콘텐츠\nSuspense로 스트리밍"]
    end
    Static --> User[사용자]
    Dynamic --> User

PPR 활성화

아래 코드는 typescript를 사용한 구현 예제입니다. 코드를 직접 실행해보면서 동작을 확인해보세요.

// next.config.js
/** @type {import('next').NextConfig} */
const nextConfig = {
  experimental: {
    ppr: true,
  },
};
module.exports = nextConfig;

실전 예제: 블로그 포스트

다음은 typescript를 활용한 상세한 구현 코드입니다. 필요한 모듈을 import하고, 비동기 처리를 통해 효율적으로 작업을 수행합니다, 반복문으로 데이터를 처리합니다. 각 부분의 역할을 이해하면서 코드를 살펴보시기 바랍니다.

// 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 최적화 팁

아래 코드는 typescript를 사용한 구현 예제입니다. 필요한 모듈을 import하고, 비동기 처리를 통해 효율적으로 작업을 수행합니다. 각 부분의 역할을 이해하면서 코드를 살펴보시기 바랍니다.

// 동적 부분을 명시적으로 표시
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 예제

다음은 typescript를 활용한 상세한 구현 코드입니다. 필요한 모듈을 import하고, 비동기 처리를 통해 효율적으로 작업을 수행합니다. 각 부분의 역할을 이해하면서 코드를 살펴보시기 바랍니다.

'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

아래 코드는 typescript를 사용한 구현 예제입니다. 필요한 모듈을 import하고, 비동기 처리를 통해 효율적으로 작업을 수행합니다. 각 부분의 역할을 이해하면서 코드를 살펴보시기 바랍니다.

'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의 캐싱 레이어

아래 코드는 mermaid를 사용한 구현 예제입니다. 코드를 직접 실행해보면서 동작을 확인해보세요.

flowchart TB
    subgraph Caching[캐싱 레이어]
        A[Request Memoization]
        B[Data Cache]
        C[Full Route Cache]
        D[Router Cache]
    end
    A --> B --> C --> D

fetch 캐싱

다음은 typescript를 활용한 상세한 구현 코드입니다. 비동기 처리를 통해 효율적으로 작업을 수행합니다. 각 부분의 역할을 이해하면서 코드를 살펴보시기 바랍니다.

// 캐싱 안 함 (기본값)
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'
});

캐시 재검증

다음은 typescript를 활용한 상세한 구현 코드입니다. 필요한 모듈을 import하고, 비동기 처리를 통해 효율적으로 작업을 수행합니다. 각 부분의 역할을 이해하면서 코드를 살펴보시기 바랍니다.

// 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');
}

다음은 간단한 typescript 코드 예제입니다. 비동기 처리를 통해 효율적으로 작업을 수행합니다. 코드를 직접 실행해보면서 동작을 확인해보세요.

// fetch에 태그 지정
const res = await fetch('https://api.example.com/posts', {
  next: { tags: ['posts'] }
});

라우트 레벨 캐싱

아래 코드는 typescript를 사용한 구현 예제입니다. 각 부분의 역할을 이해하면서 코드를 살펴보시기 바랍니다.

// 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. 성능 최적화 패턴

이미지 최적화

다음은 typescript를 활용한 상세한 구현 코드입니다. 필요한 모듈을 import하고. 각 부분의 역할을 이해하면서 코드를 살펴보시기 바랍니다.

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>
  );
}

폰트 최적화

다음은 typescript를 활용한 상세한 구현 코드입니다. 필요한 모듈을 import하고. 각 부분의 역할을 이해하면서 코드를 살펴보시기 바랍니다.

// 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

다음은 typescript를 활용한 상세한 구현 코드입니다. 필요한 모듈을 import하고, 비동기 처리를 통해 효율적으로 작업을 수행합니다. 각 부분의 역할을 이해하면서 코드를 살펴보시기 바랍니다.

// 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>
  );
}

번들 크기 최적화

다음은 typescript를 활용한 상세한 구현 코드입니다. 필요한 모듈을 import하고. 각 부분의 역할을 이해하면서 코드를 살펴보시기 바랍니다.

// 동적 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. 실전 예제: 풀스택 블로그

프로젝트 구조

다음은 code를 활용한 상세한 구현 코드입니다. 각 부분의 역할을 이해하면서 코드를 살펴보시기 바랍니다.

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를 활용한 상세한 구현 코드입니다. 각 부분의 역할을 이해하면서 코드를 살펴보시기 바랍니다.

// 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

다음은 typescript를 활용한 상세한 구현 코드입니다. 필요한 모듈을 import하고, 비동기 처리를 통해 효율적으로 작업을 수행합니다, 에러 처리를 통해 안정성을 확보합니다, 조건문으로 분기 처리를 수행합니다. 각 부분의 역할을 이해하면서 코드를 살펴보시기 바랍니다.

// 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');
}

포스트 목록 페이지

다음은 typescript를 활용한 상세한 구현 코드입니다. 필요한 모듈을 import하고, 비동기 처리를 통해 효율적으로 작업을 수행합니다, 반복문으로 데이터를 처리합니다. 각 부분의 역할을 이해하면서 코드를 살펴보시기 바랍니다.

// 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)

다음은 typescript를 활용한 상세한 구현 코드입니다. 필요한 모듈을 import하고, 비동기 처리를 통해 효율적으로 작업을 수행합니다, 반복문으로 데이터를 처리합니다, 조건문으로 분기 처리를 수행합니다. 각 부분의 역할을 이해하면서 코드를 살펴보시기 바랍니다.

// 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 함수로 변경됨. 아래 코드는 typescript를 사용한 구현 예제입니다. 필요한 모듈을 import하고, 비동기 처리를 통해 효율적으로 작업을 수행합니다. 각 부분의 역할을 이해하면서 코드를 살펴보시기 바랍니다.

// ❌ 잘못된 코드
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로 변경됨. 아래 코드는 typescript를 사용한 구현 예제입니다. 비동기 처리를 통해 효율적으로 작업을 수행합니다. 코드를 직접 실행해보면서 동작을 확인해보세요.

// ❌ 캐싱 안 됨 (기본값)
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로 감싸면 안 됨. 다음은 typescript를 활용한 상세한 구현 코드입니다. 비동기 처리를 통해 효율적으로 작업을 수행합니다, 에러 처리를 통해 안정성을 확보합니다. 각 부분의 역할을 이해하면서 코드를 살펴보시기 바랍니다.

// ❌ 잘못된 코드
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과 호환되지 않음. 아래 코드는 typescript를 사용한 구현 예제입니다. 각 부분의 역할을 이해하면서 코드를 살펴보시기 바랍니다.

// 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 배포

아래 코드는 bash를 사용한 구현 예제입니다. 코드를 직접 실행해보면서 동작을 확인해보세요.

# Vercel CLI 설치
npm i -g vercel
# 배포
vercel
# 프로덕션 배포
vercel --prod

환경 변수

다음은 간단한 bash 코드 예제입니다. 코드를 직접 실행해보면서 동작을 확인해보세요.

# .env.local
DATABASE_URL="postgresql://..."
NEXTAUTH_SECRET="..."
NEXTAUTH_URL="http://localhost:3000"

아래 코드는 typescript를 사용한 구현 예제입니다. 코드를 직접 실행해보면서 동작을 확인해보세요.

// next.config.js
/** @type {import('next').NextConfig} */
const nextConfig = {
  env: {
    NEXT_PUBLIC_API_URL: process.env.NEXT_PUBLIC_API_URL,
  },
};
module.exports = nextConfig;

성능 모니터링

다음은 typescript를 활용한 상세한 구현 코드입니다. 필요한 모듈을 import하고. 각 부분의 역할을 이해하면서 코드를 살펴보시기 바랍니다.

// 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이 나을 수 있습니다.