Previous
Next
Next.js 15 완벽 가이드 2026 | App Router·Server Actions·Turbopack

Next.js 15 완벽 가이드 2026 | App Router·Server Actions·Turbopack

· 8분 읽기 · 수정 중급
Next.js 15 완벽 가이드 2026 | App Router·Server Actions·Turbopack

이 글의 핵심

Next.js 15의 새로운 기능과 변경사항을 실전 예제로 완벽 정리. App Router, Server Actions, Turbopack, Partial Prerendering, React 19 지원까지. Start now.

이 글의 핵심

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를 사용하면 클라이언트 번들 크기를 줄이고 서버에서 직접 데이터를 처리할 수 있습니다.

App Router vs Pages Router: 라우팅·데이터 페칭의 근본 차이

Pages Router(pages/)는 Next.js 12 이전부터 이어진 모델입니다. 각 페이지는 단일 React 트리로 묶이고, getServerSideProps·getStaticProps·getInitialProps로 페이지 단위에서만 데이터를 주입합니다. 레이아웃은 _app.tsx·_document.tsx로 전역이 한 번에 고정되고, 경로별 중첩 레이아웃·공유 UI 상태를 프레임워크가 구조적으로 표현하기 어렵습니다.

App Router(app/)는 React Server Components(RSC)를 전제로 합니다. layout.tsx가 경로 세그먼트마다 중첩되고, page.tsx는 그 트리 안의 리프입니다. 데이터는 서버 컴포넌트 본문에서 직접 async 함수로 페칭하거나, Route Handler·Server Actions와 조합합니다. 즉 “페이지 한 방에 props”가 아니라 컴포넌트 트리 단위로 서버·클라이언트 경계를 나눕니다.

구분Pages RouterApp Router
라우팅pages/foo.tsx → /fooapp/foo/page.tsx → /foo
레이아웃_app 단일 래퍼세그먼트별 layout.tsx 중첩
데이터GSSP/GSP 등 페이지 API서버 컴포넌트 async + fetch/DB
클라이언트 번들페이지 단위 하이드레이션 중심RSC 페이로드 + Client Component 청크
APIpages/api/*app/**/route.ts Route Handlers

언제 무엇을 쓰나: 신규 프로젝트는 App Router가 기본 권장입니다. 기존 pages/는 점진적 이전이 가능하지만, 두 라우터를 한 앱에서 혼용할 때는 URL·미들웨어·국제화 규칙을 명확히 나눠야 합니다.

서버 컴포넌트 아키텍처(RSC)

App Router에서 기본은 서버 컴포넌트입니다. 서버에서만 실행되며, useState·useEffect·브라우저 전용 API는 사용할 수 없습니다. 클라이언트 상호작용이 필요하면 파일 상단에 'use client'인 클라이언트 컴포넌트로 분리하고, 서버 컴포넌트는 그 자식으로 서버에서 렌더된 RSC 페이로드를 넘깁니다.

동작을 한 줄로 요약하면 다음과 같습니다.

  1. 서버에서 React 트리를 렌더링하고, 직렬화 가능한 RSC 페이로드(스트리밍 가능)를 생성합니다.
  2. 클라이언트는 Client Component 경계까지 하이드레이션하고, 서버 트리는 페이로드로 병합합니다.
  3. 'use client' 모듈과 그 하위만 번들에 포함되는 경향이 있어, 경계를 얕게 유지할수록 JS 전송량이 줄어듭니다.

실무 패턴: 데이터베이스·비밀 키·대용량 변환은 서버 컴포넌트에 두고, 폼·차트·모달 등은 클라이언트로 내립니다. Server Actions는 이 경계에서 서버만의 뮤테이션을 타입 안전하게 노출하는 수단입니다.

정적 렌더링 vs 동적 렌더링: 결정은 어디서 나오나

한 라우트가 빌드 타임에 HTML/RSC 결과를 고정할지, 요청마다 새로 그릴지는 다음 요인의 합으로 결정됩니다.

  • dynamic 세그먼트 설정: export const dynamic = 'force-static' | 'force-dynamic' | 'auto' 등.
  • 동적 API 사용: cookies(), headers(), searchParams를 읽는 방식, unstable_noStore() 호출 등은 동적 렌더링을 유발하기 쉽습니다(Next.js 15에서는 cookies/headers/params가 비동기이므로, “언제 await 하느냐”도 트리 분석 대상이 됩니다).
  • fetch 캐시 옵션: cache: 'no-store' 또는 next: { revalidate: 0 }은 데이터가 매 요청마다 신선해야 함을 의미해 전체 라우트가 동적이 될 수 있습니다. 반대로 force-cache·revalidate: N은 ISR/정적 쪽으로 기울게 합니다.
  • 라우트별 revalidate: 세그먼트에 export const revalidate = 3600처럼 두면 시간 기반 ISR 의도를 명시합니다.

결정 가이드: 마케팅·문서처럼 동일한 HTML이면 정적/ISR. 대시보드·개인화처럼 요청마다 달라지면 동적. “정적 껍데기 + 일부만 스트리밍”이면 Suspense 경계 + PPR(실험) 조합을 검토합니다.

캐싱 레이어: Router / React / Data / Full Route Cache

Next.js 문서가 설명하는 캐시 스택은 서로 다른 목적의 네 층입니다. 혼동하기 쉬우므로 역할을 분리해 이해하는 것이 좋습니다.

flowchart TB
  subgraph per["1. Request Memoization (React)"]
    M["동일 요청 내 동일 fetch URL 중복 제거"]
  end
  subgraph data["2. Data Cache"]
    D["fetch 결과의 영속 캐시 (설정 시)"]
  end
  subgraph full["3. Full Route Cache"]
    F["정적 라우트의 HTML + RSC 페이로드"]
  end
  subgraph router["4. Router Cache (클라이언트)"]
    R["소프트 내비게이션 시 레이아웃·로딩 상태 재사용"]
  end
  per --> data
  data --> full
  router --> R
  • Request Memoization: 한 번의 서버 요청 처리 중 같은 fetch 입력이 반복되면 React가 합쳐 줍니다. 요청이 끝나면 사라지는 짧은 수명의 중복 제거입니다.
  • Data Cache: fetch에 cache: 'force-cache' 또는 next: { revalidate } 등을 줄 때 서버 쪽에 유지되는 결과 저장소입니다. revalidatePath/revalidateTag로 무효화합니다.
  • Full Route Cache: 정적으로 빌드된 라우트의 산출물(HTML·RSC)을 CDN/서버에 캐시하는 층입니다. 동적 라우트는 여기에 들어가지 않습니다.
  • Router Cache: 브라우저 클라이언트가 클라이언트 내비게이션할 때 레이아웃 세그먼트를 잠시 재사용해 체감 속도를 높입니다. Next.js 15에서는 기본 동작이 보수적으로 바뀌었으므로, 항상 최신 데이터가 필요하면 fetch/router.refresh/cache: 'no-store' 등으로 의도를 드러내야 합니다.

추가로 서버에서 동일 함수의 DB 조회 중복을 막으려면 React의 cache(fn)으로 래핑하는 패턴이 흔합니다. 이는 fetch 메모이제이션과는 별개로 서버 로직 재사용에 가깝습니다.

프로덕션에서 통하는 패턴

  • 에러·로딩 경계: error.tsx·loading.tsx·not-found를 세그먼트에 두어 부분 실패를 격리합니다.
  • 환경 분리: NEXT_PUBLIC_*만 브라우저에 노출하고, 시크릿은 Server Actions·Route Handler·서버 전용 모듈에만 둡니다.
  • 관측: unstable_after(또는 로깅 큐)로 응답 후 분석·감사 로그를 붙여 TTFB를 막지 않습니다.
  • 런타임 선택: Edge vs Node는 제약(일부 Node API, 실행 시간)이 다릅니다. 인증·지역 라우팅은 Middleware와 조합해 결정합니다.
  • 캐시 계약: “기본 no-store” 전제하에 어떤 데이터를 얼마나 stale 허용할지를 팀 규약으로 문서화하고, revalidateTag 단위로 무효화합니다.

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["정적 콘텐츠\n즉시 표시"]
        Dynamic["동적 콘텐츠\nSuspense로 스트리밍"]
    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 async function PostPage({
  params,
}: {
  params: Promise<{ id: string }>;
}) {
  const { id } = await params;
  return (
    <>
      {/* 정적: 즉시 표시 */}
      <PostContent id={id} />
      
      {/* 동적: 스트리밍 */}
      <Suspense fallback={<div>댓글 로딩 중...</div>}>
        <PostComments id={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

위 다이어그램은 의존 관계를 단순화한 것이며, 실제로는 (1) 요청 단위 메모이제이션 → (2) 데이터 캐시 → (3) 정적 라우트 산출물 캐시가 서버 쪽에서 연결되고, (4) Router Cache는 클라이언트 내비게이션 전용입니다.

레이어수명·범위무엇을 줄이나
Request Memoization단일 요청 내같은 fetch URL 반복 호출
Data Cache빌드/요청 간(설정 시)원격 API·동일 fetch 결과 재사용
Full Route Cache정적 라우트 산출물HTML·RSC 페이로드 재생성 비용
Router Cache클라이언트 세션 내(소프트 네비)레이아웃 등 재요청·깜빡임

React cache(): fetch가 아닌 Prisma·ORM 호출을 서버 컴포넌트 트리에서 여러 번 호출할 때, import { cache } from 'react'로 감싸면 동일 렌더 패스에서 결과를 재사용합니다. Data Cache와는 목적이 다릅니다.

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 async function PostPage({
  params,
}: {
  params: Promise<{ id: string }>;
}) {
  const { id } = await params;
  return (
    <>
      <PostContent id={id} />
      
      <Suspense fallback={<div>댓글 로딩 중...</div>}>
        <PostComments id={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·App Router·캐싱·Server Actions를 JD와 맞춰 말할 수 있게 키워드별로 정리해 두면 개발자 이력서·서류·면접 가이드와 기술 면접 완벽 대비 가이드 준비에 바로 붙습니다. 포트폴리오·배포 맥락은 개발 취업 실전 팁의 프로젝트 절과 함께 보세요.

정리 및 체크리스트

핵심 요약

  • 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 실험적 기능 테스트
  • 성능 벤치마크 측정

같이 보면 좋은 글

이 글에서 다루는 키워드

Next.js, React, App Router, Server Actions, Turbopack, Partial Prerendering, SSR, ISR, 캐싱, 성능 최적화

내부 동작과 핵심 메커니즘

이 글의 주제는 「Next.js 15 완벽 가이드 | App Router·Server Actions·Turbopack·Partial Prerendering」입니다. 앞선 튜토리얼을 구현·런타임 관점에서 다시 압축합니다. 구성 요소 간 책임 분리와 관측 가능한 지점을 기준으로 “입력이 어디서 검증되고, 핵심 연산이 어디서 일어나며, 부작용(I/O·네트워크·디스크)·동시성이 어디서 터지는가”를 한 장면으로 그리면 장애 분석이 빨라집니다.

처리 파이프라인(개념도)

flowchart TD
  A[입력·요청·이벤트] --> B[파싱·검증·디코딩]
  B --> C[핵심 연산·상태 전이]
  C --> D[부작용: I/O·네트워크·동시성]
  D --> E[결과·관측·저장]

경계에서의 지연·실패(시퀀스 관점)

sequenceDiagram
  participant C as 클라이언트/호출자
  participant B as 경계(프로세스·런타임·게이트웨이)
  participant D as 의존성(외부 API·DB·큐)
  C->>B: 요청/이벤트
  B->>D: 조회·쓰기·RPC
  D-->>B: 지연·부분 실패·재시도 가능
  B-->>C: 응답 또는 오류(코드·상관 ID)

알고리즘·프로토콜·리소스 관점 체크포인트

  • 불변 조건(Invariant): 각 단계가 만족해야 하는 조건(버퍼 경계, 프로토콜 상태, 트랜잭션 격리, 파일 디스크립터 상한)을 문장으로 적어 두면 디버깅 비용이 줄어듭니다.
  • 결정성: 동일 입력에 동일 출력이 보장되는 순수 층과, 시간·네트워크·스레드 스케줄에 의해 달라질 수 있는 층을 분리해야 테스트와 장애 분석이 쉬워집니다.
  • 경계 비용: 직렬화/역직렬화, 문자 인코딩, syscall 횟수, 락 경합, GC·할당, 캐시 미스처럼 누적 비용을 의심 목록에 넣습니다.
  • 백프레셔: 생산자가 소비자보다 빠를 때(소켓 버퍼, 큐 깊이, 스트림) 어디서 어떤 신호로 속도를 줄일지 정의합니다.

프로덕션 운영 패턴

실서비스에서는 기능과 함께 관측·배포·보안·비용·규제가 동시에 요구됩니다.

영역운영 관점 질문
관측성요청 단위 상관 ID, 에러율/지연 분위수(p95/p99), 의존성 타임아웃·재시도가 대시보드에 보이는가
안전성입력 검증·권한·비밀·감사 로그가 코드 경로마다 일관적인가
신뢰성재시도는 멱등 연산에만 적용되는가, 서킷 브레이커·백오프·DLQ가 있는가
성능캐시 계층·배치 크기·커넥션 풀·인덱스·백프레셔가 데이터 규모에 맞는가
배포롤백 룬북, 카나리/블루그린, 마이그레이션 호환성·플래그가 문서화되어 있는가
용량피크 트래픽·디스크·파일 디스크립터·스레드 풀 상한을 주기적으로 검증하는가

스테이징은 데이터 양·네트워크 RTT·동시성을 가능한 한 프로덕션에 가깝게 맞추는 것이 재현율을 높입니다.

확장 예시: 엔드투엔드 미니 시나리오

「Next.js 15 완벽 가이드 | App Router·Server Actions·Turbopack·Partial Prerendering」을 실제 배포·운영 흐름으로 옮긴 체크리스트형 시나리오입니다. 도메인에 맞게 단계 이름만 바꿔 적용할 수 있습니다.

  1. 입력 계약 고정: 스키마·버전·최대 페이로드·타임아웃·에러 코드 표를 API 또는 이벤트 경계에 둔다.
  2. 핵심 경로 계측: 요청 ID, 단계별 지연, 외부 호출 결과 코드를 한 화면(로그+메트릭+트레이스)에서 추적한다.
  3. 실패 주입: 의존성 타임아웃·5xx·부분 데이터·락 대기를 스테이징에서 재현한다.
  4. 호환·롤백: 설정/마이그레이션/클라이언트 버전을 되돌릴 수 있는지(또는 피처 플래그) 확인한다.
  5. 부하 후 검증: 피크 대비 p95/p99, 에러율, 리소스 상한, 알림 임계값이 기대 범위인지 본다.

의사코드 스케치(프레임워크 무관)

handle(request):
  ctx = newCorrelationId()
  validated = validateSchema(request)        // 경계에서 거절
  authorize(validated, ctx)                  // 권한·테넌트
  result = domainCore(validated)             // 순수에 가까운 규칙
  persistOrEmit(result, idempotentKey)       // I/O: 멱등·재시도 정책
  recordMetrics(ctx, latency, outcome)
  return result

문제 해결(Troubleshooting)

증상가능 원인조치
간헐적 실패레이스, 타임아웃, 외부 의존성 불안정, DNS최소 재현 스크립트, 분산 트레이스·로그 상관관계, 재시도·서킷 설정 점검
성능 저하N+1, 동기 I/O, 락 경합, 과도한 직렬화, 캐시 미스프로파일러·APM으로 핫스팟 확인 후 한 가지씩 제거
메모리 증가캐시 무제한, 구독/리스너 누수, 대용량 버퍼, 커넥션 미반납상한·TTL·힙/FD 스냅샷 비교
빌드·배포만 실패환경 변수, 권한, 플랫폼 차이, lockfileCI 로그와 로컬 diff, 런타임·이미지 버전 핀
설정이 로컬과 다름프로필·시크릿·기본값, 지역 리전단일 소스(예: 스키마 검증된 설정)와 배포 매트릭스 표준화
데이터 불일치비멱등 재시도, 부분 쓰기, 캐시 무효화 누락멱등 키·아웃박스·트랜잭션 경계 재검토

권장 순서: (1) 최소 재현 (2) 최근 변경 범위 축소 (3) 환경·의존성 차이 (4) 관측으로 가설 검증 (5) 수정 후 회귀·부하 테스트.

자주 묻는 질문 (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이 나을 수 있습니다.