PromleeBlog
sitemapaboutMe

posting thumbnail
Next.js 15 버전으로 안전하게 업그레이드하는 방법
How to Safely Upgrade to Next.js 15

📅
🚀

들어가기 전에🔗

Next.js는 꾸준히 발전하면서 더 빠르고 효율적인 웹 애플리케이션 개발 환경을 제공합니다. 2024년에 공개된
Next.js 15 버전
은 몇 가지 중요한 변경 사항을 포함하고 있기 때문에, 기존 프로젝트를 업그레이드하기 전에 반드시 차근차근 준비가 필요합니다.
이번 글에서는 Next.js 14에서 15로 업그레이드하는 방법을 예제를 통해 하나하나 설명드리겠습니다. 만약 아직 14버전이 아닌 더 낮은 버전을 사용하고 계시다면, 먼저 14로 올리는 것이 좋습니다.
🚀

주요 변경 사항 요약🔗

업그레이드를 하기 전에 어떤 변화가 있었는지 간단히 살펴보겠습니다:
🚀

버전 확인 및 의존성 정리🔗

먼저 현재 프로젝트의 Next.js 버전을 확인하고, 사용 중인 관련 패키지들을 정리해야 합니다.
npm list next
만약 14.x를 사용하고 있다면, 아래 명령어로 15버전으로 올릴 수 있습니다:
npm install next@latest react@latest react-dom@latest
또는 yarn을 사용하는 경우:
yarn add next@latest react@latest react-dom@latest
주의
: Next.js는 React와 ReactDOM 버전과 밀접하게 연동되어 있으므로, 함께 업데이트해야 오류를 줄일 수 있습니다.
🚀

문제 발생 및 해결🔗

✅

1. next/image의 priority 속성 제거🔗

Next.js 15부터 priority 속성은 더 이상 사용되지 않습니다. 아래와 같은 코드를 사용하고 있었다면:
<Image src="/logo.png" alt="logo" width={100} height={100} priority />
priority 속성을 제거하고, 대신 <link rel="preload">를 직접 사용하거나 loading="eager"를 고려해야 합니다:
<Image src="/logo.png" alt="logo" width={100} height={100} loading="eager" />
✅

2. next/font fallback 설정 변경🔗

기존에는 다음과 같이 fallback 설정을 했었다면:
const inter = Inter({ subsets: ['latin'], fallback: ['Arial'] });
이제는 fallback은 더 이상 문자열 배열이 아닌, 새로운 방식으로 처리되며 경고가 뜰 수 있습니다. 이 경우, 공식 문서의 폰트 설정 가이드를 따르는 것이 좋습니다.
✅

3. Turbopack 사용 프로젝트라면🔗

Next.js 15에서는 Turbopack이 더 강화되었습니다. next.config.js에 다음과 같이 명시적으로 설정할 수 있습니다:
const nextConfig = {
  experimental: {
    turbo: true,
  },
};
module.exports = nextConfig;
단, 아직 모든 기능이 안정적인 것은 아니므로, 문제가 생길 경우 비활성화하는 것도 고려해보아야 합니다.
✅

4. Async Request API 도입🔗

Next.js 15에서는
Async Request API
가 정식으로 도입되었습니다. 이는 request.cookies나 request.headers 등과 같은 서버 컴포넌트 내 비동기 API 접근을 단순화해주는 기능입니다.
기존에는 headers()와 같은 헬퍼 함수를 사용해야 했습니다:
import { headers } from 'next/headers';
export default async function Page() {
  const headerList = headers();
  const token = headerList.get('Authorization');
  return <div>Header 확인</div>;
}
이제는 props로 받은 request 객체에서 바로 비동기로 접근할 수 있습니다:
export default async function Page({ request }) {
  const token = await request.headers.get('Authorization');
  return <div>Header 확인</div>;
}
코드를 더 간결하게 만들 수 있으며, cookies, headers, url, body 등 다양한 속성에 접근할 수 있습니다. 다만 아직 실험적인 기능이기 때문에, 적용 시에는 공식 문서↗를 참고하여 점진적으로 도입하는 것이 좋습니다.
✅

5. Codemods로 마이그레이션 자동화🔗

Next.js 15에서는
Codemod 도구
가 함께 제공되어 반복적이고 오류가 생기기 쉬운 코드 수정을 자동으로 처리할 수 있습니다. Codemod는 주로 다음과 같은 작업을 수행합니다:
npx @next/codemod <transform> <path>
예를 들어, priority 속성을 제거하는 경우:
npx @next/codemod remove-priority-image ./src
모든 Codemod 목록은 공식 문서↗에서 확인하실 수 있습니다. 적용 전에는 항상 버전 관리 시스템(git 등)을 사용하여 백업을 만들어두는 것이 좋습니다.
🚀

결론🔗

Next.js 15로의 업그레이드는 몇 가지 주의할 점이 있지만, 하나하나 체크하면서 적용하면 큰 문제 없이 마이그레이션이 가능합니다. 특히 deprecated된 속성이나 설정은 릴리즈 노트를 꼼꼼히 확인하면서 적용하는 것이 중요합니다.
예상치 못한 빌드 에러나 동작 오류가 있다면, 일단 이전 버전에서 어떤 기능이 변경되었는지를 중심으로 코드를 점검해 보시길 권장드립니다.
✅

더 생각해 보기🔗

✅

참고🔗

🚀 들어가기 전에
🚀 주요 변경 사항 요약
🚀 버전 확인 및 의존성 정리
🚀 문제 발생 및 해결
✅ 1. `next/image`의 `priority` 속성 제거
✅ 2. `next/font` fallback 설정 변경
✅ 3. Turbopack 사용 프로젝트라면
✅ 4. Async Request API 도입
✅ 5. Codemods로 마이그레이션 자동화
🚀 결론
✅ 더 생각해 보기
✅ 참고