Next.js 15 + React 19

Next.js 15와 React 19 환경에서 shadcn/ui를 사용하는 방법을 알려드릴게요. peer 의존성 문제로 설치가 막힐 때 어떤 플래그를 쓰면 되는지, 그리고 패키지별 지원 상황이 어떤지 정리해 드릴게요.

출처: 문서

본문

아래 가이드는 React 19를 지원하는 모든 프레임워크에 적용돼요. Next.js 15로 업그레이드하는 분들이 이 페이지를 쉽게 찾을 수 있도록 "Next.js 15 + React 19"라는 제목을 붙였어요. 패키지 관리자들과 함께 React 19 업그레이드를 진행하고 있어요.

요약 (TL;DR)

npm을 사용한다면 플래그 하나로 shadcn/ui 의존성을 설치할 수 있어요. shadcn CLI를 실행하면 플래그 선택을 안내받게 됩니다. pnpm, bun, yarn은 플래그가 필요 없어요.

각 패키지의 React 19 지원 상황은 업그레이드 현황을 확인해 주세요.

무슨 일이 벌어지고 있나요?

React 19가 이제 rc 버전이고, 최신 Next.js 15 릴리스에서 테스트·지원되고 있어요.

React 19를 지원하려면 패키지 관리자들이 각자의 패키지를 테스트하고 React 19를 peer dependency로 포함하도록 업데이트해야 해요. 이 작업은 이미 진행 중이에요.

"peerDependencies": {
-  "react": "^16.8 || ^17.0 || ^18.0",
+  "react": "^16.8 || ^17.0 || ^18.0 || ^19.0",
-  "react-dom": "^16.8 || ^17.0 || ^18.0"
+  "react-dom": "^16.8 || ^17.0 || ^18.0 || ^19.0"
},

패키지가 React 19를 peer dependency로 나열하는지 npm info <package> peerDependencies 명령어로 확인할 수 있어요.

그동안 React 19를 peer dependency로 나열하지 않은 패키지를 설치하려고 하면 다음과 같은 오류 메시지가 나와요.

npm error code ERESOLVE
npm error ERESOLVE unable to resolve dependency tree
npm error
npm error While resolving: [email protected]
npm error Found: [email protected]
npm error node_modules/react
npm error   react@"19.0.0-rc-69d4b800-20241021" from the root project

참고: 이는 npm에만 해당하는 문제예요. PNPM과 Bun은 조용한 경고만 표시합니다.

해결 방법

해결책 1: `--force` 또는 `--legacy-peer-deps`

--force 또는 --legacy-peer-deps 플래그로 패키지를 강제 설치할 수 있어요.

npm i <package> --force

npm i <package> --legacy-peer-deps

이렇게 하면 패키지가 설치되면서 peer dependency 경고를 무시해요.

What do the `--force` and `--legacy-peer-deps` flag do?

  - `--force`: Ignores and overrides any dependency conflicts, forcing the
    installation of packages.
  - `--legacy-peer-deps`: Skips strict peer dependency checks, allowing
    installation of packages with unmet peer dependencies to avoid errors.

</AccordionContent>

해결책 2: React 18 사용

설치하려는 패키지와 호환되는 react와 react-dom을 18 버전으로 낮추고, 의존성이 업데이트되면 다시 올리면 돼요.

npm i react@18 react-dom@18

어떤 해결책을 선택하든, 회귀(regression)가 없는지 앱을 충분히 테스트하세요.

Next.js 15에서 shadcn/ui 사용하기

pnpm, bun, yarn 사용 시

설치 가이드의 안내를 따라 shadcn/ui를 설치하면 돼요. 플래그는 필요 없습니다.

npm 사용 시

npx shadcn@latest init -d를 실행하면 peer dependency 문제를 해결할 옵션을 선택하라는 안내가 나와요.

It looks like you are using React 19.
Some packages may fail to install due to peer dependency issues (see https://ui.shadcn.com/react-19).

? How would you like to proceed? › - Use arrow-keys. Return to submit.
❯   Use --force
    Use --legacy-peer-deps

그런 다음 선택한 플래그와 함께 명령어를 실행하면 돼요.

컴포넌트 추가

컴포넌트를 추가하는 과정도 위와 같아요. peer dependency 문제를 해결할 플래그를 선택하면 됩니다.

새 의존성을 설치한 뒤에는 항상 앱을 테스트하는 걸 기억하세요.

업그레이드 현황

업그레이드 진행 상황을 쉽게 추적하도록 shadcn/ui 의존성의 React 19 지원 상태를 아래 표로 정리해 봤어요.

✅ - npm, pnpm, bun에서 React 19와 함께 동작합니다.
🚧 - pnpm, bun에서는 동작하나 npm에서는 플래그가 필요합니다. PR이 진행 중입니다.

Package	Status	Note
radix-ui	✅
lucide-react	✅
class-variance-authority	✅	Does not list React 19 as a peer dependency.
tailwindcss-animate	✅	Does not list React 19 as a peer dependency.
embla-carousel-react	✅
recharts	✅	See note below
react-hook-form	✅
react-resizable-panels	✅
sonner	✅
react-day-picker	✅	Works with flag for npm. Work to upgrade to v9 in progress.
input-otp	✅
vaul	✅
@radix-ui/react-icons	🚧	See PR #194
cmdk	✅

궁금한 점이 있다면 GitHub에서 이슈를 열어 주세요.

Recharts

React 19에서 recharts를 사용하려면 react-is 의존성을 재정의(override)해야 해요.

다음을 package.json에 추가합니다.

"overrides": {
  "react-is": "^19.0.0-rc-69d4b800-20241021"
}

참고로 react-is 버전은 사용 중인 React 19 버전과 일치해야 해요. 위는 예시입니다.

npm install --legacy-peer-deps를 실행합니다.

Next.js 15 + React 19