Nextjs15 로 마이그레이션 하기

현 프로젝트에서 Nextjs14 를 사용하고 있었는데, Nextjs15 의 안정적 버전이 나와 이번에 마이그레이션을 진행했습니다.

 

우선적으로 크게 바뀐 것은 동기 API 들이 비동기로 변경되었고, page, layout 에서 사용되는 params 또한 비동기로 변경되었습니다.

그래서 간단하게 변화 부분에 대한 내용과 새롭게 추가된 내용을 간략하게 정리하겠습니다.

🚀 Next.js 15 업그레이드

Next.js 15 버전이 출시되면서 많은 주요 변경 사항과 새로운 기능들이 추가되었습니다. React 19 지원과 비동기 API 변화 등 프로젝트에 큰 영향을 줄 요소들이 많으므로, 이번 포스팅에서는 Next.js 15 업그레이드에 필요한 가이드와 새 기능을 최대한 쉽게 설명드리겠습니다.

1. Next.js 15 업그레이드 방법

업그레이드 준비

Next.js 15로 업그레이드하는 방법은 두 가지입니다: 자동 코드 변환(codemod) 도구 사용 또는 수동 설치 방식입니다.

npx @next/codemod@canary upgrade latest

수동으로 업그레이드하려면 최신의 Next.js 및 React 버전을 설치해야 합니다:

npm install next@latest react@rc react-dom@rc eslint-config-next@latest

주의 사항: React 19와 연결 종속성 경고

업그레이드 중에 react와 react-dom에서 연결 종속성 경고가 발생할 수 있습니다. 이 경우, React 19가 안정화되기 전에는 --force 플래그를 추가하거나, --legacy-peer-deps 플래그로 경고를 무시할 수 있습니다.

---

2. React 19의 주요 변경 사항

React 19의 새로운 최소 요구 버전

Next.js 15에서는 react와 react-dom의 최소 버전이 19로 변경되었습니다. 또한 일부 기존 훅이 더 이상 추천되지 않거나 제거될 예정입니다. 예를 들어, useFormState는 React 19에서 비추천 상태이며, 향후 버전에서 제거될 가능성이 높습니다.

새로운 훅과 상태 관리

React 19에서는 useActionState가 추가되며, pending 상태를 직접 읽는 기능을 제공합니다. useFormStatus 또한 새로운 키들을 포함하여 한층 더 강력해졌습니다.

---

3. 비동기 API의 변화

이전에는 동기적으로 사용하던 동적 API들이 이제 비동기식으로 전환되었습니다. 이에 따라 cookies, headers, draftMode와 같은 API는 await 키워드를 통해 비동기적으로 접근해야 하고, app 라우터에 page, layout 에서 사용하는 params 또한 이제 비동기로 접근해야 합니다.

비동기 API로의 전환을 돕는 codemod 제공

Next.js는 API 변경에 대한 부담을 줄이기 위해 codemod를 제공합니다. 이 도구를 통해 기존 코드에 적용된 동기식 API들을 비동기식으로 빠르게 전환할 수 있습니다.

// 변경 전
const userCookie = cookies();

// 변경 후
const userCookie = await cookies();

---

4. 비동기 처리 방식의 변화

• params와 searchParams 또한 비동기적으로 사용해야 합니다. 비동기적 레이아웃 및 페이지 구현 예시를 통해 이러한 변화에 적응할 수 있습니다.

// Before
type Params = { slug: string }
 
export function generateMetadata({ params }: { params: Params }) {
  const { slug } = params
}
 
export default async function Layout({
  children,
  params,
}: {
  children: React.ReactNode
  params: Params
}) {
  const { slug } = params
}
 
// After
type Params = Promise<{ slug: string }>
 
export async function generateMetadata({ params }: { params: Params }) {
  const { slug } = await params
}
 
export default async function Layout({
  children,
  params,
}: {
  children: React.ReactNode
  params: Params
}) {
  const { slug } = await params
}

---

5. 런타임 설정과 캐싱 변화

Edge 런타임 설정

기존 experimental-edge 값이 지원되지 않으며, 대신 edge 값으로 업데이트해야 합니다. 또한, fetch 요청은 기본적으로 캐시되지 않으므로, 특정 요청에 대해 캐시를 활성화하려면 cache: 'force-cache' 옵션을 사용합니다.

캐싱 정책 업데이트

• GET 메서드는 기본적으로 캐시되지 않으므로, 캐시가 필요할 경우 export const dynamic = 'force-static'을 설정하세요.
• 클라이언트 측 라우터 캐시는 페이지 간 네비게이션에는 사용되지 않지만, 브라우저의 뒤로 가기, 앞으로 가기에서는 재사용됩니다.

---

6. 기타

폰트 설정 변경

// Before
import { Inter } from '@next/font/google'
 
// After
import { Inter } from 'next/font/google'

 

클라이언트 사이드 라우터 캐시

/** @type {import('next').NextConfig} */
const nextConfig = {
  experimental: {
    staleTimes: {
      dynamic: 30,
      static: 180,
    },
  },
}
 
module.exports = nextConfig

 

공식 페이지: https://nextjs.org/docs/canary/app/building-your-application/upgrading/version-15