shadcn/ui sık hatalar: components.json, alias, Tailwind, React 19 ve registry

Özet tablo

Son sütun serideki ilgili yazıyı gösterir; bağlantılar aşağıdaki bölümlerde ve yazının sonunda.

1. components.json yok, bozuk ya da zaten var

components.json, CLI'nin projenizi nasıl anlayacağını ve bileşenleri nereye yazacağını belirleyen dosyadır. Belgeye göre yalnızca CLI kullanıyorsanız gereklidir; kodu elle kopyalıyorsanız şart değildir. Bu dosya yokken npx shadcn@latest add button çalıştırırsanız CLI 3.6.2 kaynak koduna göre şu onay sorusunu sorar: You need to create a components.json file to add components. Proceed? Evet derseniz kurulum başlatılır. Dosya var ama geçersizse, kaynak koddaki metin geçersiz bir components.json bulunduğunu ve bileşen eklemeden önce init ile geçerli bir dosya oluşturmanız gerektiğini söyler, ardından https://ui.shadcn.com/docs/components-json adresini önerir.

Ters durum da sık görülür: daha önce başlatılmış bir projede init yeniden çalıştırıldığında kaynak koddaki şu mesaj çıkar:

A components.json file already exists at /proje/yolu.
To start over, remove the components.json file and run init again.

Çözüm iki yoldan biridir. Baştan başlamak istiyorsanız dosyayı silip init çalıştırın. CLI belgesindeki -f, --force seçeneği de mevcut yapılandırmanın üzerine yazmayı sağlar. Ancak components.json belgesi bazı alanların kurulumdan sonra değiştirilemeyeceğini vurgular: style, tailwind.baseColor ve tailwind.cssVariables. CSS değişkenleri ile utility sınıfları arasında geçiş yapmak için bileşenleri silip yeniden kurmanız gerekir. Alanların anlamı components.json ayarları yazısında.

Monorepo'da ek bir kural vardır: belgeye göre her çalışma alanının kendi components.json dosyası olmalı ve takma adlar o çalışma alanına göre doğru tanımlanmalıdır. add komutu da uygulamanın klasöründe, örneğin apps/web içinde çalıştırılır. Bkz. monorepo kurulumu.

2. Framework algılanamadı

init önce projenin hangi çatıyla kurulduğunu doğrular. Algılayamazsa kaynak koddaki metin, belirtilen klasörde desteklenen bir framework bulunamadığını, projeyi elle yapılandırmak için bir kurulum sayfasını ziyaret etmenizi ve yapılandırmadan sonra CLI ile bileşen ekleyebileceğinizi söyler (metnin başı We could not detect a supported framework at şeklindedir). Ayrıca klasörde package.json yoksa CLI projeyi boş kabul eder ve yeni proje oluşturma akışına geçer. Desteklenen çatıların kurulum sayfaları kurulum dizininde listelenir; hiçbirine uymuyorsanız manuel kurulum adımlarını izleyin.

3. Tailwind CSS bulunamadı veya sürüm uyuşmuyor

init sırasında Tailwind doğrulaması başarısız olursa kaynak kod şu üç satırı yazar:

No Tailwind CSS configuration found at /proje/yolu.
It is likely you do not have Tailwind CSS installed or have an invalid configuration.
Install Tailwind CSS then try again.

Kaynak koddaki koşullara göre bu, Tailwind sürümünün hiç algılanamadığı, Tailwind v3 projesinde yapılandırma dosyası veya CSS dosyasının bulunamadığı ya da Tailwind v4 projesinde CSS dosyasının bulunamadığı durumlarda olur. Çözüm, çatınızın kurulum sayfasındaki Tailwind adımını tamamlamaktır; Vite sayfası örneğin tailwindcss ve @tailwindcss/vite paketlerinin kurulmasını ve CSS dosyasına @import "tailwindcss"; eklenmesini ister. Tailwind'in kendisini öğrenmek için Tailwind CSS rehberine bakın.

Sürüm uyumsuzluğu daha sinsi bir sorundur. Tailwind v4 belgesine göre geçiş kırıcı değildir: Tailwind v3 ve React 18 ile çalışan mevcut uygulamalar çalışmaya devam eder ve siz yükseltene kadar yeni eklenen bileşenler de v3 ve React 18 düzeninde gelir. Yalnızca yeni projeler Tailwind v4 ve React 19 ile başlar. Tailwind v4 projesinde components.json içindeki tailwind.config alanı boş bırakılmalıdır. Projeyi kendiniz yükseltiyorsanız belgede iki önemli değişiklik vardır. Birincisi, tailwindcss-animate kullanımdan kalktı: paketi kaldırın, CSS'teki eklenti satırını silin, tw-animate-css paketini geliştirme bağımlılığı olarak kurun ve import satırını ekleyin:

/* globals.css: önce */
@plugin 'tailwindcss-animate';

/* globals.css: sonra */
@import "tw-animate-css";

İkincisi, karanlık mod renkleri yenilendi; yükseltilmiş değil doğrudan v4 ile kurulmuş projelerde bileşenleri yeniden ekleyip renkleri yeni OKLCH değerleriyle güncellemeniz önerilir. Tüm adımlar Tailwind v4 geçişi yazısında.

4. @/components yolu çözülmüyor

init içe aktarma takma adını da doğrular. Bulamazsa kaynak koddaki metin No import alias found in your tsconfig.json file. şeklindedir ve takma adın nasıl ayarlanacağını gösteren kurulum sayfasını önerir. Aynı sorun, CLI'yi geçtikten sonra editörde veya derlemede @/components/ui/button yolunun bulunamaması olarak da görünebilir. Vite için belge iki ayrı yer ister: TypeScript tarafında hem tsconfig.json hem tsconfig.app.json dosyasına baseUrl ve paths, paketleyici tarafında vite.config.ts içine resolve.alias. tsconfig.json dosyasındaki eklenti:

{
  "files": [],
  "references": [
    { "path": "./tsconfig.app.json" },
    { "path": "./tsconfig.node.json" }
  ],
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@/*": ["./src/*"]
    }
  }
}

vite.config.ts içinde path modülünü kullanabilmek için belge önce npm install -D @types/node kurulmasını söyler:

import path from "path"
import tailwindcss from "@tailwindcss/vite"
import react from "@vitejs/plugin-react"
import { defineConfig } from "vite"

export default defineConfig({
  plugins: [react(), tailwindcss()],
  resolve: {
    alias: {
      "@": path.resolve(__dirname, "./src"),
    },
  },
})

Yalnızca tsconfig düzeltilirse editör yolu tanır ama Vite derlemesi başarısız olabilir; yalnızca vite.config.ts düzeltilirse derleme çalışır ama editör hata gösterir. İkisini birlikte yapın. Adımların tamamı Vite kurulumu yazısında, paths ayarının TypeScript tarafı TypeScript paths alias yazısında anlatılıyor.

5. npm ERESOLVE: React 19 peer dependency

npm ile React 19 kullanan bir projede, peer dependency listesinde React 19 bulunmayan bir paketi kurarken React 19 belgesinin gösterdiği türde bir hata alırsınız:

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 project

Belge bunun yalnızca npm'e özgü olduğunu, pnpm ve Bun'ın yalnızca sessiz bir uyarı gösterdiğini belirtir. İki çözüm önerilir: paketi --force veya --legacy-peer-deps ile kurmak ya da react ve react-dom paketlerini 18 sürümüne indirmek. Belgedeki tanıma göre --force bağımlılık çakışmalarını yok sayıp kurulumu zorlar, --legacy-peer-deps ise katı peer dependency denetimini atlar:

npm i <package> --force
npm i <package> --legacy-peer-deps
npm i react@18 react-dom@18

npm ile npx shadcn@latest init -d çalıştırdığınızda CLI React 19 kullandığınızı fark edip bu iki bayraktan birini seçmenizi ister. Recharts kullanıyorsanız belge package.json içine bir react-is override eklemenizi ve npm install --legacy-peer-deps çalıştırmanızı söyler; sürümün kullandığınız React 19 sürümüyle eşleşmesi gerekir, aşağıdaki yalnızca belgedeki örnektir:

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

6. toast bileşeni kurulmuyor

Tailwind v4 ile kurulan bir projede npx shadcn@latest add toast çalıştırırsanız CLI 3.6.2 kaynak kodundaki şu uyarı basılır ve işlem durur: The toast component is deprecated. Use the sonner component instead. Aynı uyarı toaster için de tanımlıdır. Bu, Şubat 2025'te duyurulan kullanımdan kaldırmanın sonucudur. Çözüm bildirimler için Sonner kullanmaktır: Sonner ile toast bildirimleri.

7. Registry ve namespace hataları

CLI 3.0 ile hata mesajları kullanıcılar ve dil modelleri için daha yol gösterici hale geldi. Değişiklik günlüğündeki örneklerden ilki, components.json içinde tanımlanmamış bir namespace kullanıldığında çıkar ve doğru yapılandırmanın kalıbını da gösterir:

Unknown registry "@acme". Make sure it is defined in components.json as follows:
{
  "registries": {
    "@acme": "[URL_TO_REGISTRY]"
  }
}

Çözüm, registries alanına namespace'i URL şablonuyla eklemektir; açık kaynak dizinindeki registry'ler ise CLI tarafından otomatik eklenir. Özel bir registry'nin başlığındaki ${REGISTRY_TOKEN} gibi bir değişken tanımlı değilse CLI eksik değişkenleri madde madde listeler ve bunları .env veya .env.local dosyasına eklemenizi söyler. Registry sunucusu yanıtında özel bir mesaj döndürüyorsa değişiklik günlüğüne göre çıktı şöyle görünebilir:

Error:
You are not authorized to access the item at http://example.com/r/component.

Message:
[Unauthorized] Your API key has expired. Renew it at https://example.com/api/renew-key.

Öğe bulunamazsa (404) kaynak koddaki ve belgedeki mesaj The item at ... was not found. It may not exist at the registry. şeklindedir; neden genellikle yanlış ad, registry'de olmayan öğe veya hatalı URL kalıbıdır. 401 ve 403 için namespace belgesi kimlik bilgilerinizi, ortam değişkenlerinizi ve API anahtarınızın izinlerini kontrol etmenizi isteyen mesajlar gösterir. Belgedeki metinler ile CLI 3.6.2 kaynak kodundaki metinler bu iki durumda birebir aynı değildir; kaynak kodda ikisi için de uzak bir registry ise kimlik doğrulamanız gerekebileceğini söyleyen tek bir cümle kullanılır. Bir öğe şemaya uymuyorsa Failed to parse registry item: ..., namespace geçersizse Invalid registry namespace: ... ile başlayan mesajlar kaynak kodda tanımlıdır. Yapılandırmanın tamamı namespace ve özel registry yazısında, registry tarafındaki şema kuralları registry kurma yazısında.

8. Bileşen güncellemesinde değişikliklerin kaybolması

Belgenin yeni karanlık mod renkleri için önerdiği npx shadcn@latest add --all --overwrite komutu tüm bileşenleri yeniden yazar. Belge açıkça CLI'nin mevcut bileşenlerinizin üzerine yazacağını söyler ve önce değişikliklerinizi commit etmenizi önerir. Aynı uyarı Calendar yükseltmesi için de geçerlidir: üzerine yazma sorusuna evet derseniz bileşende yaptığınız değişiklikleri yeni sürümle kendiniz birleştirmeniz gerekir. Bir registry:style veya registry:theme kurarken de CLI kaynak koduna göre mevcut CSS değişkenlerinin ve bileşenlerin üzerine yazılacağını bildiren bir onay sorusu çıkar.

9. MCP sunucusunda araç görünmüyor

MCP belgesindeki sorun giderme bölümü No tools or prompts mesajı için npx önbelleğini npx clear-npx-cache ile temizlemeyi, sunucuyu istemcide yeniden etkinleştirmeyi ve Cursor'da çıktı panelindeki MCP günlüğüne bakmayı önerir. Kurulum hatalarında ise geçerli bir components.json, var olan hedef klasörler ve yazma izni kontrol edilmelidir. Bkz. shadcn MCP sunucusu.

Hata ayıklarken genel yaklaşım

• Mesajın ilk satırını okuyun: CLI mesajları çoğunlukla neyin eksik olduğunu ve hangi belge sayfasına bakacağınızı söyler.
• Sırayı izleyin: init sırasıyla proje klasörünü, components.json durumunu, framework'ü, Tailwind'i ve içe aktarma takma adını doğrular; ilk başarısız adımı düzeltmek çoğu zaman sonrakileri de çözer.
• Kurmadan önce görün: Registry kaynaklı sorunlarda npx shadcn@latest view öğenin içeriğini dosya yazmadan gösterir.
• Commit edin: Kopyalanan kod sizin kodunuzdur; her add öncesi temiz bir çalışma ağacı, yanlış giden bir kurulumu geri almanın en kolay yoludur.

Sık Sorulan Sorular

Hata metni sizin alıntıladığınızdan farklı, neden?

CLI sık güncellenir. Bu yazıdaki metinler 19 Aralık 2025 tarihli depo kopyasından ve CLI 3.6.2 kaynağından alındı. Değişken kısımlar (yol, ad, URL) her projede farklıdır.

init yerine bileşenleri elle kopyalayabilir miyim?

Evet. Belgeye göre components.json yalnızca CLI için gereklidir. Elle kurulumda bağımlılıkları, CSS değişkenlerini ve cn yardımcısını kendiniz eklersiniz; adımlar manuel kurulum yazısında.

pnpm kullanıyorum, ERESOLVE görmüyorum ama uyarı var. Sorun mu?

React 19 belgesine göre pnpm ve Bun bu durumda yalnızca sessiz bir uyarı verir ve bayrak gerekmez. Yine de belge, hangi yolu seçerseniz seçin uygulamanızı yeni bağımlılıklardan sonra iyice test etmenizi önerir.

style değerini sonradan değiştirmek istersem?

components.json belgesine göre style kurulumdan sonra değiştirilemez. Pratikte bu, yeni bir yapılandırmayla başlayıp bileşenleri yeniden kurmak anlamına gelir; özelleştirmelerinizi elle taşırsınız.

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 · init komutu · React 19 peer dependency · Tailwind v4 geçişi · Vite kurulumu · Namespace ve özel registry