React 19 kullanan bir projede shadcn/ui bileşeni eklerken npm'in ERESOLVE unable to resolve dependency tree hatası vermesi, kurulan paketlerden birinin peerDependencies listesinde henüz React 19'un yer almamasından kaynaklanır. Belgedeki iki çözüm şunlardır: kurulumu --force ya da --legacy-peer-deps bayrağıyla yapmak veya react ile react-dom paketlerini 18 sürümüne düşürmek. Bu sorun yalnızca npm'de hata olarak görünür; pnpm ve bun yalnızca sessiz bir uyarı gösterir.
Bu yazıda sorunun nedenini, belgedeki hata çıktısını, iki çözümün ne anlama geldiğini, CLI'nin bu durumda sorduğu soruyu ve paketlerin React 19 durum tablosunu anlatıyoruz. Önemli bir uyarıyla başlayalım: React 19 sayfasının başındaki güncel not, React 19 ve Tailwind v4 için tam desteğin latest sürümde eklendiğini ve rehberin güncelliğini yitirmiş olabileceğini söyler. Yani bu sayfa bugün çoğunlukla eski bağımlılıkları olan projeler ve hatanın mantığını anlamak için yararlıdır.
Sorun nedir? peerDependencies ve React 19
Bir React kütüphanesi hangi React sürümleriyle çalıştığını package.json dosyasındaki peerDependencies alanında bildirir. Belgenin yazıldığı dönemde React 19 sürüm adayı (rc) aşamasındaydı ve Next.js 15 ile test edilip destekleniyordu. Paket yazarlarının React 19'u desteklemek için paketlerini test edip bu alana eklemesi gerekiyordu. Belgede gösterilen değişiklik, alanın nasıl genişletildiğini gösterir:
"peerDependencies": {
"react": "^16.8 || ^17.0 || ^18.0 || ^19.0",
"react-dom": "^16.8 || ^17.0 || ^18.0 || ^19.0"
},Eski listede ^19.0 yoktu. Projenizde React 19 kuruluysa ve kurmak istediğiniz paket bu sürümü listelemiyorsa npm bağımlılık ağacını çözemez. Bir paketin React 19'u listeleyip listelemediğini kurmadan önce şu komutla kontrol edebilirsiniz:
npm info <package> peerDependenciesKomuttaki <package> yerine paket adını yazarsınız, örneğin npm info vaul peerDependencies. Çıktıdaki react satırında ^19.0 görüyorsanız paket React 19'u resmi olarak destekliyor demektir.
Hata çıktısı nasıl görünür?
Belgede npm'in verdiği hatanın başlangıcı şöyle gösterilir. Buradaki proje adı ve React sürümü belgenin örneğidir; sizin çıktınızda kendi değerleriniz yer alır:
npm error code ERESOLVE
npm error ERESOLVE unable to resolve dependency tree
npm error
npm error While resolving: my-app@0.1.0
npm error Found: react@19.0.0-rc-69d4b800-20241021
npm error node_modules/react
npm error react@"19.0.0-rc-69d4b800-20241021" from the root projectERESOLVE kodu, npm'in sürüm kısıtlarını aynı anda sağlayan bir paket kümesi bulamadığını gösterir. Found: satırı projede bulunan React sürümünü söyler; çıktının devamında genellikle hangi paketin hangi React aralığını istediği yazar. Belgenin notu burada önemlidir: bu davranış npm'e özgüdür. pnpm ve bun aynı durumda kurulumu durdurmaz, yalnızca sessiz bir uyarı verir. Bu yüzden belge pnpm, bun veya yarn kullanıyorsanız bayrak gerekmediğini söyler.
Çözüm 1: --force veya --legacy-peer-deps
İlk çözüm, paketi npm'in peer dependency denetimini gevşeten bir bayrakla kurmaktır. Belgedeki komutlar:
npm i <package> --force
npm i <package> --legacy-peer-depsİki bayrak aynı şeyi yapmaz. Belgenin açıklamasına göre --force tüm bağımlılık çakışmalarını yok sayıp ezer ve kurulumu zorla tamamlar. --legacy-peer-deps ise yalnızca katı peer dependency denetimini atlar; karşılanmamış peer bağımlılıkları olan paketlerin hata vermeden kurulmasına izin verir. İkisi de paketi kurar ve peer dependency uyarılarını görmezden gelir; fark, --force bayrağının etkisinin daha geniş olmasıdır.
| Bayrak | Belgedeki anlamı | Etki alanı |
|---|---|---|
| --force | Bağımlılık çakışmalarını yok sayar ve ezer, kurulumu zorlar | Tüm çakışmalar |
| --legacy-peer-deps | Katı peer dependency denetimini atlar | Yalnızca peer bağımlılıkları |
Bu bayraklar sorunu ortadan kaldırmaz, yalnızca npm'in kurulumu durdurmasını engeller. Paket gerçekten React 19 ile uyumsuz bir şey yapıyorsa bunu çalışma zamanında görürsünüz. Belgenin her iki çözüm için tekrarladığı uyarı budur: hangisini seçerseniz seçin uygulamanızı gerilemelere karşı iyice test edin.
Çözüm 2: React 18 kullanmak
İkinci yol, kurmak istediğiniz paketle uyumlu olan React 18'e dönmek ve bağımlılık güncellendiğinde yeniden yükseltmektir:
npm i react@18 react-dom@18Bu yol bayrak gerektirmez ama React 19 ile gelen özelliklerden ve React 19 için güncellenen bileşen kodundan vazgeçmek demektir. Tailwind v4 sayfasına göre siz yükseltene kadar yeni eklenen bileşenler v3 ve React 18 uyumlu gelir; yani React 18'de kalan bir proje shadcn/ui kullanmaya devam edebilir. Next.js 15 ile çalışıyorsanız framework'ün hangi React sürümünü gerektirdiğini kendi belgesinden kontrol edin; bu ayrıntı shadcn/ui sayfasında yer almaz.
shadcn CLI bu durumda ne sorar?
Belgeye göre npm kullanan bir projede npx shadcn@latest init -d çalıştırdığınızda CLI, peer dependency sorununu çözmek için bir seçenek seçmenizi ister. Belgede gösterilen istem:
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-depsSeçiminizden sonra CLI bağımlılıkları o bayrakla kurar. Bileşen eklerken de süreç aynıdır: add komutu gerekirse aynı soruyu sorar. Belge her yeni bağımlılık kurulumundan sonra uygulamayı test etmenizi hatırlatır.
Depo kopyasındaki 3.6.2 kaynağı bu davranışı daha dar tanımlar. update-dependencies.ts dosyasında soru yalnızca paket yöneticisi npm olduğunda ve projenin package.json dosyasında React 19 ile birlikte react-day-picker paketinin 8 sürümü bulunduğunda sorulur. Kaynaktaki uyarı metni de belgedekinden biraz farklıdır ("peer dependency issues in npm" ifadesini içerir). --silent ile çalıştırıldığında ise soru sorulmaz ve --force seçilir. Yani güncel CLI ile React 19 projelerinin çoğunda bu soruyu hiç görmeyebilirsiniz; bu, belgenin başındaki "tam destek eklendi" notuyla da uyumludur.
Paketlerin React 19 durumu
Belge, shadcn/ui bileşenlerinin kullandığı paketler için bir durum tablosu tutar. İşaretlerden biri npm, pnpm ve bun ile React 19 üzerinde çalıştığını, diğeri ise pnpm ve bun ile çalışıp npm'de bayrak gerektirdiğini gösterir. Depo kopyasındaki tabloda tüm paketler ilk durumdadır, yani çalışır olarak işaretlenmiştir. Notlu satırlar şunlardır:
| Paket | Durum | Belgedeki not |
|---|---|---|
| radix-ui | Çalışıyor | Yok |
| lucide-react | Çalışıyor | Yok |
| class-variance-authority | Çalışıyor | React 19'u peer dependency olarak listelemiyor |
| tailwindcss-animate | Çalışıyor | React 19'u peer dependency olarak listelemiyor |
| embla-carousel-react | Çalışıyor | Yok |
| recharts | Çalışıyor | Ayrı not var (react-is) |
| react-hook-form | Çalışıyor | Yok |
| react-resizable-panels | Çalışıyor | Yok |
| sonner | Çalışıyor | Yok |
| react-day-picker | Çalışıyor | npm için bayrakla çalışır, v9 yükseltmesi sürüyor |
| input-otp | Çalışıyor | Yok |
| vaul | Çalışıyor | Yok |
| @radix-ui/react-icons | Çalışıyor | İlgili bir PR'a bağlantı verir |
| cmdk | Çalışıyor | Yok |
react-day-picker satırındaki "v9 yükseltmesi sürüyor" notu sayfanın yazıldığı döneme aittir. Changelog'un Haziran 2025 notu, Calendar bileşeninin React DayPicker'ın en son sürümüne yükseltildiğini söyler; eski takvimi kullanan projeler için yükseltme rehberi takvim sayfasındadır, bkz. shadcn Calendar ve Date Picker. Bu, CLI kaynağındaki sorunun neden react-day-picker 8 ile bağlantılı olduğunu da açıklar. tailwindcss-animate paketinin kendisi ise artık kullanımdan kaldırılmıştır ve yerini tw-animate-css almıştır; ayrıntı Tailwind v4 geçişi yazısında.
Recharts ve react-is
Grafik bileşeni recharts kullanır. Belgeye göre recharts'ı React 19 ile kullanmak için react-is bağımlılığını package.json içinde geçersiz kılmanız (override) gerekir:
"overrides": {
"react-is": "^19.0.0-rc-69d4b800-20241021"
}Buradaki sürüm bir örnektir; belge react-is sürümünün kullandığınız React 19 sürümüyle eşleşmesi gerektiğini vurgular. Ardından kurulumu npm install --legacy-peer-deps ile yaparsınız. Grafik bileşeninin kendisi shadcn chart yazısında.
React 19 desteğinin zaman çizelgesi
Changelog, React 19 ile ilgili adımları birkaç notta toplar. Ekim 2024 notu shadcn/ui'nin React 19 ve Next.js 15 ile uyumlu olduğunu duyurur ve bu rehbere bağlantı verir. Şubat 2025'teki Tailwind v4 notu, tüm bileşenlerin Tailwind v4 ve React 19 için güncellendiğini ve forwardRef kullanımlarının kaldırıldığını söyler. Haziran 2025 notları önce birleşik radix-ui paketine geçiş komutunu, ardından Calendar bileşeninin React DayPicker'ın en son sürümüne yükseltildiğini duyurur. React 19 sayfasının başındaki güncelleme notu da bu sürecin sonunda eklenmiştir.
Bu sıra pratikte şunu anlatır: React 19 ile ilgili sorunların büyük kısmı bileşenlerin kendisinden değil, onların kullandığı üçüncü taraf paketlerin peer dependency listelerinden kaynaklanıyordu ve bu listeler zamanla güncellendi. Yeni bir proje init ile başlatıldığında Tailwind v4 sayfasına göre zaten React 19 ve Tailwind v4 ile gelir; monorepo şablonu da belgeye göre React 19 kullanır. Bugün bu hatayı en çok, bağımlılıkları uzun süredir güncellenmemiş bir projeyi React 19'a taşırken görürsünüz. Bu durumda önce bağımlılıkları güncellemek, ardından bayrağa ihtiyaç kalıp kalmadığını kontrol etmek, doğrudan --force kullanmaktan daha temiz bir yoldur. Tailwind v4 sayfasındaki bağımlılık güncelleme komutu (@radix-ui/*, cmdk, lucide-react, recharts, tailwind-merge, clsx) bunun için iyi bir başlangıç listesidir.
Uygulamalı akış: npm ile React 19 projesinde bileşen eklemek
Belgedeki adımları birleştiren bir örnek düşünelim: npm kullanan bir Next.js projesine drawer bileşenini ekliyorsunuz ve kurulum ERESOLVE ile duruyor. Önce bileşenin bağımlılığının React 19'u listeleyip listelemediğine bakarsınız; drawer bileşeni vaul paketini kullanır:
npm info vaul peerDependencies
npx shadcn@latest add drawerPaket React 19'u listeliyorsa sorun büyük olasılıkla başka bir pakettedir ve hata çıktısındaki satırlar hangisi olduğunu gösterir. CLI bir bayrak sorarsa önce daha dar etkili olan --legacy-peer-deps seçeneğini denemek mantıklıdır. Kurulumdan sonra bileşeni açıp kapatarak ve sayfayı derleyerek test edersiniz. Sorun çözülmüyorsa ve paketin React 19 desteği gerçekten yoksa React 18'e dönmek son seçenektir.
Sık yapılan hatalar
- pnpm veya bun ile de bayrak aramak: Belgeye göre bu paket yöneticilerinde bayrak gerekmez; yalnızca sessiz uyarı vardır.
- --force bayrağını alışkanlık haline getirmek: Tüm çakışmaları ezer; gerçek bir uyumsuzluğu gizleyebilir.
- Bayrakla kurup test etmemek: Belge her iki çözümden sonra uygulamanın gerilemelere karşı test edilmesini ister.
- react-is sürümünü örnekten kopyalamak: Sürüm kendi React 19 sürümünüzle eşleşmelidir.
- Güncel olmayan rehbere körü körüne uymak: Sayfanın başındaki not, tam desteğin
latestsürümde olduğunu ve rehberin eskimiş olabileceğini söyler. - Eski react-day-picker ile kalmak: CLI kaynağında React 19 sorusunu tetikleyen durum budur; takvimi güncelleyin.
Sık Sorulan Sorular
Bu hata shadcn/ui'nin bir hatası mı?
Hayır. Hata npm'in bağımlılık çözümlemesinden gelir: kurulan bir paket React 19'u peer dependency olarak listelemediğinde ortaya çıkar. shadcn/ui CLI yalnızca npm'i uygun bayrakla çalıştırmanıza yardımcı olur.
--force mu --legacy-peer-deps mi seçmeliyim?
Belge ikisini de çözüm olarak sunar. --legacy-peer-deps yalnızca peer dependency denetimini atladığı için etkisi daha dardır; --force tüm çakışmaları ezer. Hangisini seçerseniz seçin uygulamanızı test edin.
Bayrağı her seferinde yazmak zorunda mıyım?
Belge, npm ile her bileşen eklemede aynı seçimi yapmanızı anlatır; kalıcı bir ayar önermez. pnpm, bun veya yarn kullanıyorsanız bayrak hiç gerekmez.
Hangi paketin soruna yol açtığını nasıl bulurum?
Belge çıktının yalnızca başını gösterir; npm'in ERESOLVE çıktısının devamı genellikle çözümlemenin hangi pakette takıldığını ve o paketin hangi React aralığını istediğini yazar. Şüphelendiğiniz paketi npm info <package> peerDependencies ile kontrol edip listede ^19.0 olup olmadığına bakarsınız. Paket listede yoksa ya güncel bir sürümünü arar ya da belgedeki iki çözümden birini uygularsınız.
Bu sayfa hâlâ geçerli mi?
Sayfanın kendisi güncelliğini yitirmiş olabileceğini söyler ve React 19 için tam desteğin latest sürümde olduğunu belirtir. Eski bağımlılıkları olan projelerde ve hatanın nedenini anlamak için yine de yararlıdır.
Marka adları sahiplerine aittir. Bu yazı bağımsız bir teknik rehberdir; adı geçen kuruluşlarla bayilik veya ortaklık ilişkisi bulunduğu anlamına gelmez.
İlgili içerikler: shadcn/ui öğrenme rehberi · Next.js kurulumu · init komutu · Tailwind v4 geçişi · shadcn sık hatalar · Node.js ve npm kurulumu