shadcn/ui ile Baştan Sona Proje Kurulumu
shadcn/ui Nedir ve Neden Seçilmelidir?
shadcn/ui, modern web geliştirmede React bileşenlerini hızlı ve tutarlı şekilde uygulamak isteyen geliştiriciler için açık kaynaklı bir bileşen kütüphanesidir. Radix UI ve Tailwind CSS üzerine inşa edilen bu araç, önceden tasarlanmış bileşenleri kodunuza doğrudan kopyalayıp yapıştırmanız anlamına gelir—npm üzerinden yükleme yerine.
Bu yaklaşım, geleneksel bileşen kütüphanelerinden önemli ölçüde ayrılır. Diğer kütüphaneler siyah kutu olarak işlev görürken, shadcn/ui tam kontrol sağlar. Stilinizi özelleştirmek, bileşen davranışını değiştirmek ya da özel gereksinimler için kodu düzenlemek istediğinizde, tüm kaynak kodu elinizin altındadır. Bu esneklik, özellikle kurumsal projeler ve özelleştirmeye yoğun bağımlı uygulamalar için kritik bir avantajdır.
Gerekli Ön Koşullar ve Ortam Hazırlığı
shadcn/ui ile başlamadan önce, temel altyapıyı sağlamlaştırmanız gerekir:
- Next.js Projesi: Sürüm 13.0 veya daha üzeri, App Router desteğiyle birlikte
- Node.js: Sürüm 18 veya daha yeni
- Tailwind CSS: Projenizde önceden kurulmuş olmalı
- Radix UI Bağımlılıkları: Çoğu bileşen için otomatik olarak kurulacak
Bu koşulları sağlıyorsanız, ilk adımlar nispeten düzgündür. Ancak Tailwind CSS henüz kurulu değilse, shadcn/ui kurulumundan önce bunu tamamlamanız zorunludur. İki sistemin birlikte çalışması, tasarım sisteminin uyumlu ve performant kalması için temeldir.
Adım Adım Kurulum Süreci
1. shadcn/ui CLI Aracını Başlatın
Next.js projesinin kök dizininde aşağıdaki komutu çalıştırın:
npx shadcn-ui@latest init
Bu komut, bir seri yapılandırma sorusu soracaktır. Bu sorular şunları kapsar:
- Hangi stil sistemi kullanacaksınız (varsayılan: Tailwind)
- CSS değişkenleri için temel renk şemanız
- Dark mode desteğini etkinleştirmek isteyip istemediğiniz
- Bileşenlerin depolanacağı dizin (genellikle /components/ui)
Çoğu geliştirici için varsayılan seçenekler yeterlidir. Ancak renkler ve dark mode gibi konuları, projenizin tasarım sisteminin gereksinimlerine göre özelleştirmeyi düşünün.
2. Konfigürasyon Dosyalarını İnceleyip Doğrulayın
Kurulum tamamlandığında, aşağıdaki dosyalar oluşturulmuş veya güncellenmiş olacaktır:
- components.json: shadcn/ui konfigürasyonunu tanımlar
- tailwind.config.ts: Tailwind ayarlarını içerir (CSS değişkenleri eklenir)
- globals.css: Temel renkler ve stil değişkenleri tanımlanır
- lib/utils.ts: CSS sınıf isimlerini birleştirmek için yardımcı fonksiyon
Bu dosyalarda herhangi bir değişiklik yapmadan önce, projenizin mevcut Tailwind yapılandırmasıyla uyumlu olduğunu kontrol edin. Eğer özel Tailwind eklentileriniz varsa, bunların shadcn/ui ayarlarıyla çatışmayacağından emin olun.
3. İlk Bileşenleri Ekleyin
Basit bir bileşenle başlayın. Örneğin, bir Button bileşeni eklemek için:
npx shadcn-ui@latest add button
Bu komut, Button bileşenini /components/ui/button.tsx dizinine indirir. Bileşeni React bileşeninizde kullanmak şimdi oldukça basittir:
import { Button } from "@/components/ui/button" export default function HomePage() { return <Button>Tıkla</Button> }
Yaygın Kurulum Sorunları ve Çözümleri
Stil Çatışmaları: Projenizde başka CSS çerçeveleri varsa (Emotion, Styled Components gibi), shadcn/ui'nin Tailwind tabanlı stillerle uyumlu olması için cascading order'ı kontrol etmeniz gerekebilir. CSS dosyalarını imports sırasına göre düzenleyin.
TypeScript Hataları: Node.js ve TypeScript versiyonlarının uyumlu olmadığı durumlar nadiren ortaya çıkar. Bu durumda, package-lock.json dosyasını silin ve npm install komutunu yeniden çalıştırın.
Dark Mode Problemi: Dark mode desteğini etkinleştirdiyseniz ancak sistem sekmeyi algılamıyorsa, globals.css dosyasında .dark sınıf tanımının doğru şekilde yapılmış olduğunu kontrol edin.
Eğitim seçeneklerini karşılaştırırken olduğu gibi, shadcn/ui kurulumunda da dikkatli bir planlama gerekir. Başta biraz zaman ayırarak doğru yapılandırma yapmak, sonraki geliştirme sürecinizin hızını ve kalitesini doğrudan etkileyecektir. Bileşenleri eklemeye başlamadan önce, temel ortamınızın sağlam olup olmadığını test edin. Örneğin, bir Input ve Card bileşeni ekleyip basit bir form oluşturmayı deneyin. Bu küçük test, potansiyel sorunları erken aşamada ortaya çıkaracaktır.
shadcn/ui'nin güçlü yönü, sahip olduğunuz kontrol ve esnekliktir. Bileşenleri indirdikten sonra, onları projenizin ihtiyaçlarına tam olarak uyarlayabilirsiniz. Bu, başlangıçta biraz fazla görünebilir, ancak karmaşık uygulamalar geliştirirken size muazzam bir avantaj sağlar. Kurulum tamamlandıktan sonra, bileşen kütüphanesini keşfetmeye başlayabilir ve projenizin tasarım sistemini tutarlı tutmanın ne kadar kolay olduğunu görebilirsiniz.