본문으로 건너뛰기

Next.js · EP 03

Next.js 15 업그레이드 실전 가이드 — 캐시 기본값부터 React Compiler 베타까지

Next.js 15는 fetch 캐시와 GET 라우트 핸들러의 캐시 기본값을 사실상 해제하는 방향으로 바뀌었습니다. 14에서 15로 올리는 실전 절차와 React Compiler 베타 적용기를 정리한 마이그레이션 가이드.

· 9분 읽기

Next.js 15 업그레이드 실전 가이드 — 캐시 기본값부터 React Compiler 베타까지

개요

Next.js 14 App Router로 돌리던 사이드 프로젝트를 Next.js 15로 올리면서 겪은 변화를 정리했습니다. Next.js 15는 2024년 10월 21일에 정식 출시된 메이저 버전인데, 눈에 띄는 신기능보다는 캐시 기본값의 대전환이 핵심입니다. 또 React 19를 전제로 설계되어 있어서, 업그레이드는 단순히 next 버전을 바꾸는 일이 아니라 React 생태계 전체를 함께 점검하는 작업이 됩니다.

이 글은 (1) 바뀐 캐시 기본값을 이해하고, (2) @next/codemod로 마이그레이션을 수행하고, (3) React Compiler 베타를 붙여 보는 순서로 구성했습니다. 라우터 구조 자체를 해부하는 내용은 최소화하고 업그레이드와 컴파일러에 집중합니다.

왜 지금 Next.js 15로 올리는가

타임라인부터 정리하면 다음과 같습니다.

즉 지금(2025년 4월)은 15.x와 React 19 안정판 조합이 충분히 검증된 시점입니다. 반대로 14에 머물러 있으면 React 19의 새로운 API(폼 액션, useActionState 등)와 그 생태계에서 점점 멀어집니다. React 19가 왜 큰 전환인지 배경이 궁금하다면 예전에 정리한 React 동시성 렌더링 글을 먼저 보셔도 좋습니다.

핵심 변경 1: 캐시 기본값이 반대로 뒤집혔다

App Router가 처음 나왔을 때의 캐시 설계는 “성능을 위해 기본으로 최대한 캐시하고, 필요하면 opt-out”이었습니다. Next.js 15에서는 이 방향을 완전히 뒤집어 “기본으로 캐시하지 않고, 필요한 곳만 opt-in”으로 바뀌었고, 공식 발표 글에서도 이 결정 배경을 직접 설명하고 있습니다.

fetch는 더 이상 기본으로 캐시되지 않는다

Next.js 14까지 App Router의 fetch는 기본적으로 force-cache처럼 동작해서 응답이 캐시에 담겼습니다. 15부터는 기본값이 no-store입니다. 캐시하고 싶은 요청은 이제 명시해야 합니다.

// Next.js 15: 캐시가 필요한 fetch는 직접 선언
const res = await fetch('https://api.example.com/notices', {
  cache: 'force-cache',
  next: { revalidate: 3600 },
});

마이그레이션 관점에서 중요한 지점은 “예전에 캐시 덕에 빠랐던 요청들이 이제 매번 네트워크를 탄다”는 것입니다. 공개 API 조회처럼 재검증 주기를 줄 수 있는 요청은 위처럼 되살리고, 사용자별 데이터는 그대로 두는 식으로 하나씩 판단했습니다.

GET 라우트 핸들러는 기본 동적

Next.js 14에서는 GET 메서드의 라우트 핸들러가 동적 함수를 쓰지 않는 한 빌드 시 정적으로 캐시되었습니다. Next.js 15부터는 GET 핸들러도 기본적으로 캐시되지 않습니다. 정적 응답을 원한다면 라우트 세그먼트 설정을 직접 붙입니다.

// app/api/notices/route.ts
export const dynamic = 'force-static'; // 15에서 정적 캐시를 원할 때만 선언

export async function GET() {
  return Response.json(await getNotices());
}

참고로 sitemap.ts, opengraph-image.tsx, icon.tsx 같은 메타데이터 파일은 종전처럼 정적 기본값을 유지한다고 발표 글에 명시되어 있습니다.

클라이언트 라우터 캐시: Page 세그먼트의 staleTime이 0으로

브라우저 안에 있는 라우터 캐시도 바뀌었습니다. Next.js 15에서는 Page 세그먼트의 staleTime 기본값이 0이 되어 내비게이션 시 항상 최신 서버 데이터를 반영합니다. 뒤로 가기 시 캐시 복원, 공유 레이아웃 재요청 생략, loading.js 5분 캐시 같은 동작은 그대로입니다. 이전 동작이 필요하다면 설정으로 되돌릴 수 있습니다.

// next.config.ts
const nextConfig = {
  experimental: {
    staleTimes: {
      dynamic: 30, // Next.js 14의 Page 세그먼트 동작(30초)으로 되돌리기
    },
  },
};

export default nextConfig;

비동기 요청 API: params와 searchParams는 이제 Promise

캐시는 아니지만 같은 메이저에서 온 큰 브레이킹 체인지라 짚고 갑니다. cookies, headers, draftMode, 그리고 params와 searchParams가 비동기로 바뀌었습니다. 렌더링 파이프라인에서 요청 의존 데이터를 명확히 구분하기 위한 변경이라고 공식 글은 설명합니다.

// app/posts/[id]/page.tsx
export default async function PostPage({
  params,
}: {
  params: Promise<{ id: string }>;
}) {
  const { id } = await params;
  const post = await getPost(id);
  return <article>{post.title}</article>;
}

수동 마이그레이션 대신 전용 codemod가 준비되어 있습니다.

npx @next/codemod@canary next-async-request-api .

핵심 변경 2: React 19 지원

Next.js 15의 App Router는 React 19를 사용합니다. 15.0 출시 당시엔 React 19가 RC 단계였지만, 15.1부터 React 19 안정판을 지원합니다. Pages Router는 React 18 하위 호환도 유지되므로 App Router부터 올리고 Pages Router는 천천히 따라가는 전략도 가능합니다. 다만 한 앱에서 두 라우터가 서로 다른 React 버전을 쓰는 조합은 공식 문서도 권장하지 않습니다.

React 19로 올리며 체크할 것은 결국 서드파티 의존성입니다. 저의 경우 UI 라이브러리와 훅 몇 개에서 peer 경고가 나왔지만, React 19 업그레이드 가이드를 따라 타입 변경(ReactNode 관련 등)만 손보면 됐습니다.

업그레이드 실전 순서

정리하면 제가 밟은 순서는 이렇습니다.

  1. 업그레이드 전용 브랜치를 만들고 codemod CLI를 실행합니다. 의존성 업데이트부터 사용 가능한 codemod 목록 표시, 적용까지 대화형으로 진행됩니다.
npx @next/codemod@canary upgrade latest
  1. codemod 후 남은 타입 에러를 수작업으로 잡습니다. 대부분 params/searchParams의 Promise 화와 next/headers 관련이었습니다.
  2. fetch 캐시 의도를 다시 기입합니다. “이 요청 캐시 되고 있었나?”를 하나씩 묻는 시간이 의외로 제일 오래 걸렸습니다.
  3. 개발 서버의 정적 라우트 표시기로 라우트별 렌더링 전략을 확인합니다. Next.js 15부터 개발 중에 정적/동적 여부가 표시됩니다.
  4. 프로덕션 빌드로 회귀 확인 후 머지했습니다.

공식 버전 15 업그레이드 가이드가 단계별로 잘 정리되어 있으니 병행해서 보시길 권합니다.

React Compiler(베타) 도입기

업그레이드를 마친 김에 React Compiler도 붙여 봤습니다. 결론부터 말하면 ESLint 플러그인은 바로 도입하고, 컴파일러는 베타 한계를 인정한 범위에서만 사용 중입니다.

컴파일러가 하는 일

React Compiler는 빌드 타임에 컴포넌트와 훅을 정적 분석해서 useMemo/useCallback 없이도 자동으로 메모이제이션 코드를 주입하는 도구입니다. 공식 학습 문서의 표현을 빌리면, JavaScript 의미와 Rules of React를 이해해 “코드를 다시 쓰지 않고” 최적화를 넣는다고 합니다. 2024년 5월 React Conf에서 실험 버전으로 공개되었고, 2024년 10월 21일 베타가 발표되었으며, 이 글을 쓰는 시점 기준 베타 단계입니다. 베타 발표 글의 로드맵에는 “대부분의 앱에서 문제 없이 동작하는 것이 검증되면 RC를 낸다”고 되어 있어서, 정식 버전은 가까운 시일 내로 예고된 상태입니다.

왜 필요한가에 대한 흥미로운 근거도 있습니다. Meta는 컴파일러 도입 전 조사에서 전체 React PR의 약 8%만 수동 메모이제이션을 사용했고, 그 PR들은 작성에 31~46% 더 오래 걸렸다고 베타 발표 글에서 밝혔습니다. 수동 메모이제이션이 코드가 아니라 인지 비용이라는 이야기입니다.

설치와 Next.js 설정

Next.js 15는 React Compiler를 실험적 기능으로 지원합니다. 주의점은 현재 Babel 플러스인 형태로 동작해 개발·빌드 시간이 늘어날 수 있다는 것인데, 이 역시 Next.js 15 발표 글에 명시된 내용입니다.

npm install -D babel-plugin-react-compiler@beta eslint-plugin-react-compiler@beta
// next.config.ts
import type { NextConfig } from 'next';

const nextConfig: NextConfig = {
  experimental: {
    reactCompiler: {},
  },
};

export default nextConfig;

설정 옵션의 세부 내용은 Next.js의 reactCompiler 설정 문서를 참고하세요.

before / after: 코드에서 사라지는 것들

컴파일러를 켜면 이런 코드가 실제로 사라집니다.

// Before: 수동 메모이제이션
function ProductCard({ product, onSelect }: ProductCardProps) {
  const label = useMemo(
    () => `${product.name} · ${product.price.toLocaleString('ko-KR')}원`,
    [product],
  );
  const handleClick = useCallback(
    () => onSelect(product.id),
    [onSelect, product.id],
  );
  return (
    <button onClick={handleClick}>
      {label}
    </button>
  );
}
// After: 컴파일러가 자동으로 메모이제이션을 주입
function ProductCard({ product, onSelect }: ProductCardProps) {
  const label = `${product.name} · ${product.price.toLocaleString('ko-KR')}원`;
  const handleClick = () => onSelect(product.id);
  return <button onClick={handleClick}>{label}</button>;
}

의존성 배열을 잘못 쓰는 버그의 종류 자체가 사라지고, 코드 리뷰에서도 “이거 memo 해야 하지 않나” 같은 논의가 없어집니다.

ESLint 플러그인은 컴파일러보다 먼저

베타 발표 글이 강조하는 권장사항은 모두가 지금 바로 ESLint 플러그인을 쓰라는 것입니다. 컴파일러 없이 독립적으로 동작하고, Rules of React 위반(조건부 훅 호출, 잘못된 의존성 등)을 잡아 줍니다. 컴파일러 도입의 사전 작업이기도 합니다.

// eslint.config.mjs
import reactCompiler from 'eslint-plugin-react-compiler';

export default [
  // ...기존 설정
  {
    plugins: {
      'react-compiler': reactCompiler,
    },
    rules: {
      'react-compiler/react-compiler': 'warn',
    },
  },
];

도입하며 배운 팁

  • linter 먼저, 컴파일러는 나중: 위반 경고를 0으로 만들고 나서 컴파일러를 켜면 빌드 타임에 놀랄 일이 없었습니다.
  • 빌드 시간 오버헤드는 실제로 있습니다: Babel 기반이라서 작은 프로젝트에서도 체감됩니다. 설치 문서를 읽고 프로젝트에 맞게 판단하세요.
  • React 18 이하 프로젝트라면: 베타 발표 글에 따르면 target 설정과 react-compiler-runtime 패키지로 React 17/18에서도 쓸 수 있습니다. Next.js 15 App Router는 React 19라 해당하지 않지만, 다른 프로젝트에 적용할 때 유용한 정보입니다.
  • 베타는 베타다: 아직 이슈 트래커에 버그가 쌓이는 단계입니다. 프로덕션에 적용한다면 롤백 경로를 남겨 두세요.

정리

  • Next.js 15의 본질은 캐시 기본값의 반전입니다. “기본 캐시”에서 “기본 no-store”로 바뀌었고, 캐시가 필요한 곳은 이제 명시적으로 씁니다.
  • 업그레이드 절반은 @next/codemod가 해줍니다. 나머지 절반은 캐시 의도를 다시 적는 작업입니다.
  • React Compiler는 메모이제이션을 빌드 타임으로 옮기는 방향의 큰 변화입니다. 지금 단계에서는 ESLint 플러그인부터 도입하고, 컴파일러는 베타의 한계를 인정하며 점진적으로 붙이는 것이 현실적입니다.

업그레이드 그 자체보다 “내 앱의 캐시 전략을 다시 설명할 수 있는가”를 검증하게 되는 릴리스였습니다. Next.js 14 → 15를 앞두고 있다면 이 순서로 진행해 보시길 바랍니다.

레퍼런스

Related

· 18 min read Build Logs

damon-chat-desk 구축기 — 로컬 에이전트 데몬의 /ws 위에 얇은 웹 데스크를 얹기

로컬 AI 에이전트 데몬(damon-agent-core) 위에 정적 SPA 채팅 데스크를 얹었습니다. OpenAI 호환 경로 대신 /ws JSON-RPC v2와 일회용 ws_ticket을 고른 이유, 툴 실행 아코디언·turn.steer·plan.respond CAS·session.fork, 메모리 게이트(-32011)를 UI 문장으로 옮기는 법, ⌘K 팔레트, https 페이지에서 loopback 데몬에 붙을 수 없을 때의 demo 폴백까지 — PR 4건 +18,477줄, 테스트 223개, 번들 375kB의 기록입니다.

프론트엔드AI
→
· 15 min read Build Logs

AI 과제 지도(assignment-map) 구축기 — 수집기 흰 화면 복구부터 18종 레퍼런스 기반 UI 개편까지

채용 과제·해커톤의 AI 정책과 마감을 매일 수집하는 과제 지도를 6일 동안 PR 16건으로 고도화했습니다. evidence 문자열 하나가 배포 화면을 통째로 죽인 장애와 그 뿌리 수정, 18종 레퍼런스 실측에서 나온 PR A~E, npm ci 앞에서 돌던 테스트가 배포를 막은 CI 함정까지 실제 수치로 정리합니다.

프론트엔드AI
→
· 2 min read

AI-assisted 프론트엔드 PR workflow 사례 정리

AI 코딩 에이전트를 프론트엔드 PR workflow에 붙일 때 필요한 입력 계약, 변경 범위 제한, 검증 명령, 리뷰 로그를 하나의 사례로 정리했습니다.

프론트엔드AI
→