shadcn/ui Vite + React Kurulumu: Tailwind, Takma Ad ve init

1. Vite projesini oluşturun

Belge, yeni bir React projesini Vite ile oluşturmanızı ve şablon sorusunda React + TypeScript seçeneğini işaretlemenizi ister. Komut etkileşimlidir; proje adını ve şablonu size sorar.

npm create vite@latest

TypeScript şablonu seçmeniz önemlidir, çünkü sonraki adımlar Vite'ın TypeScript şablonundaki dosya düzenine göre yazılmıştır. JavaScript ile ilerlemek isterseniz shadcn/ui bunu components.json içindeki tsx alanıyla destekler; ancak takma ad ayarı o zaman jsconfig.json üzerinden yapılır (components.json ayarları).

2. Tailwind CSS'i ekleyin

shadcn/ui bileşenleri Tailwind CSS sınıflarıyla yazıldığı için projede Tailwind bulunmalıdır. Vite sayfası Tailwind'i resmî Vite eklentisiyle kurar:

npm install tailwindcss @tailwindcss/vite

Ardından src/index.css dosyasının içindeki her şeyi silip yerine tek bir satır yazarsınız. Vite şablonunun getirdiği örnek stiller artık gerekmez; tema değişkenlerini daha sonra init komutu bu dosyaya ekleyecektir.

@import "tailwindcss";

Bu kurulum Tailwind v4 içindir: ayrı bir tailwind.config.js dosyası ve PostCSS yapılandırması oluşturulmaz. Eski bir rehberde PostCSS ve tailwind.config.js adımları görürseniz, büyük olasılıkla Tailwind v3 dönemine aittir. Tailwind'in kendisiyle ilgili ayrıntılar için Tailwind CSS rehberi yazısına bakın.

3. tsconfig.json dosyasını düzenleyin

Belgenin dikkat çektiği nokta şudur: Vite'ın güncel sürümü TypeScript yapılandırmasını üç dosyaya böler ve bunlardan ikisini düzenlemeniz gerekir. Kökteki tsconfig.json diğer iki dosyaya referans veren bir çatı dosyasıdır; baseUrl ve paths alanlarını onun compilerOptions bölümüne eklersiniz. tsconfig.json dosyasının son hâli şöyledir:

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

Buradaki "@/*": ["./src/*"] eşlemesi, @/ ile başlayan her içe aktarmanın src klasörüne göre çözüleceğini söyler. Yani @/components/ui/button yolu src/components/ui/button.tsx dosyasını gösterir. Üçüncü dosya olan tsconfig.node.json bu adımda değişmez.

4. tsconfig.app.json dosyasını düzenleyin

Aynı baseUrl ve paths ayarı tsconfig.app.json dosyasına da eklenir. Belge bu adımın gerekçesini editörünüzün (IDE) yolları çözebilmesi olarak verir. Dosyadaki diğer ayarlara dokunmadan, compilerOptions içine şu alanları eklersiniz:

{
  "compilerOptions": {
    // ...
    "baseUrl": ".",
    "paths": {
      "@/*": [
        "./src/*"
      ]
    }
    // ...
  }
}

// ... satırları, şablonun oluşturduğu mevcut ayarların yerini gösterir; onları silmeyin. İki dosyadaki eşlemenin birebir aynı olması önemlidir. Biri ./src/*, diğeri ./* gösterirse editörünüz ile CLI farklı klasörlere bakabilir. paths ve baseUrl alanlarının TypeScript tarafındaki anlamı TypeScript paths ve alias ayarları yazısında ayrıntılı anlatılır.

5. vite.config.ts dosyasını güncelleyin

TypeScript ayarları editörün ve tür denetiminin yolu bulmasını sağlar; ancak uygulamanın çalışırken bu yolları çözebilmesi için takma adın Vite'a da bildirilmesi gerekir. Belge bu adımı "uygulamanızın yolları hatasız çözebilmesi için" diye açıklar. Önce Node türlerini geliştirme bağımlılığı olarak kurarsınız:

npm install -D @types/node

Bu paket gereklidir, çünkü yapılandırma dosyası Node'un path modülünü ve __dirname değişkenini kullanır. vite.config.ts dosyasının belgedeki hâli şöyledir:

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

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

@vitejs/plugin-react paketini belge ayrıca kurdurmaz; dosyadaki react() eklentisi, birinci adımda seçtiğiniz React şablonuyla birlikte gelir. Bu dosyada iki değişiklik vardır. Birincisi plugins dizisine eklenen tailwindcss() eklentisidir; ikinci adımda kurduğunuz Tailwind ancak bu sayede derlemeye dahil olur. İkincisi resolve.alias içindeki "@" tanımıdır ve tsconfig dosyalarındaki @/* eşlemesinin çalışma zamanı karşılığıdır. İkisi aynı klasörü, yani src klasörünü göstermelidir.

6. init komutunu çalıştırın

Hazırlık tamamlandıktan sonra proje kökünde shadcn CLI'ın init komutunu çalıştırırsınız:

npx shadcn@latest init

Komut, components.json dosyasını yapılandırmak için birkaç soru sorar. Vite sayfası bunlardan temel renk sorusunu örnek verir: Which color would you like to use as base color? › Neutral. Seçenekler neutral, gray, zinc, stone ve slate değerleridir ve bu seçim sonradan değiştirilemez. init bağımlılıkları kurar, cn yardımcısını ekler ve CSS değişkenlerini yapılandırır; tema değişkenleri ikinci adımda sadeleştirdiğiniz src/index.css dosyasına yazılır. Bu değişkenlerin anlamı tema ve CSS değişkenleri yazısında anlatılıyor.

Soruyu hiç görmeden ilerlemek isterseniz temel rengi CLI belgesindeki --base-color seçeneğiyle doğrudan verebilirsiniz; örneğin npx shadcn@latest init --base-color neutral. Bu, kurulumu bir betik içinde tekrarlarken işe yarar.

7. İlk bileşeni ekleyin

Artık bileşen ekleyebilirsiniz. Belgedeki örnek Button bileşenidir:

npx shadcn@latest add button

Komut Button bileşenini projenize ekler. src/App.tsx dosyasında belgedeki örneği Türkçe etiketle şöyle kullanabilirsiniz:

import { Button } from "@/components/ui/button"

function App() {
  return (
    <div className="flex min-h-svh flex-col items-center justify-center">
      <Button>Tıklayın</Button>
    </div>
  )
}

export default App

Kod, ekranı dikeyde dolduran bir kapsayıcının ortasına tek bir buton yerleştirir. flex, min-h-svh ve items-center gibi sınıflar Tailwind'in kendi sınıflarıdır; butonun görünüşünü ise button.tsx içindeki varyant sınıfları belirler. Farklı görünümler için Button varyantları yazısına geçebilirsiniz.

Kurulumdan sonra proje yapısı

Yedi adım tamamlandığında projenizde shadcn/ui ile ilgili dosyaların nerede durduğunu bilmek, sonraki bileşenleri eklerken işinizi kolaylaştırır. @ takma adı src klasörünü gösterdiği ve belgelerdeki varsayılan takma adlar @/components, @/components/ui, @/lib/utils, @/lib ve @/hooks olduğu için dosyalar src altında toplanır:

• components.json: proje kökünde, init tarafından yazılır.
• src/index.css: Tailwind içe aktarması ve init'in eklediği tema değişkenleri.
• src/lib/utils.ts: cn yardımcı fonksiyonu.
• src/components/ui/button.tsx: add button ile eklenen bileşen; sonraki her bileşen de bu klasöre gelir.
• src/App.tsx: bileşeni kullandığınız kendi kodunuz.

components.json dosyasında Vite için özellikle iki alanı kontrol edin. tailwind.css alanı, Tailwind'i içe aktaran dosyayı, yani bu kurulumda src/index.css dosyasını göstermelidir. tailwind.config alanı ise Tailwind v4 kullandığınız için boş kalmalıdır. Diğer alanların tamamı components.json ayarları yazısında anlatılıyor.

Mevcut bir Vite projesine eklemek

Belge yeni bir projeden yola çıkar, ancak adımlar mevcut bir Vite + React + TypeScript projesi için de aynıdır. Dikkat etmeniz gereken yer ikinci adımdır: belge src/index.css içindeki her şeyin silinmesini ister. Yeni şablonda bu dosya yalnızca örnek stiller içerdiği için sorun olmaz; ama mevcut bir projede kendi stillerinizi bu dosyada tutuyorsanız onları önce ayrı bir dosyaya taşıyın, sonra dosyayı Tailwind içe aktarmasıyla başlatın. Benzer şekilde projenizde zaten bir @ takma adı varsa farklı bir klasörü gösterip göstermediğini kontrol edin; shadcn/ui bileşenleri @/lib/utils yolunu kullanır.

Adımlar özet tablosu

Daha fazla bileşen eklemek

Button çalıştıktan sonra diğer bileşenleri aynı yolla eklersiniz. add komutu birden fazla bileşen adını tek seferde kabul eder; CLI bileşenlerin birbirine olan bağımlılıklarını ve npm paketlerini de çözer. Bir bileşenin hangi dosyaları ve bağımlılıkları getireceğini kurmadan önce görmek isterseniz view komutunu kullanabilirsiniz:

npx shadcn@latest view card
npx shadcn@latest add card dialog input

Bu komutlar Vite'a özgü değildir; her projede aynı şekilde çalışır. Seçeneklerinin tamamı CLI komutları yazısında anlatılıyor. Eklediğiniz her bileşen src/components/ui altına ayrı bir dosya olarak gelir ve @/components/ui/... yolundan içe aktarılır.

Vite projesinde sonraki adımlar

Kurulumdan sonra en sık ihtiyaç duyulan konu karanlık moddur. Next.js'te kullanılan yöntem Vite'ta doğrudan çalışmadığı için belgelerde Vite'a özel ayrı bir karanlık mod sayfası bulunur; bunu dark mode kurulumu yazısında diğer çatılarla birlikte ele alıyoruz. Form kurmak isterseniz React Hook Form ve Zod ya da TanStack Form yazıları Vite projelerinde de geçerlidir. Changelog'a göre Aralık 2025'te duyurulan npx shadcn create akışı da Vite için kullanılabilir; ayrıntısı yenilikler yazısındadır.

Sık yapılan hatalar

• Yalnızca bir tsconfig dosyasını düzenlemek: Belge iki dosyanın düzenlenmesini ister. Sadece tsconfig.json düzenlenirse editörünüz yolları tanımayabilir; sadece tsconfig.app.json düzenlenirse kökteki yapılandırma eksik kalır.
• vite.config.ts içinde alias tanımlamamak: Editörde hata görünmese bile uygulama çalışırken @/ ile başlayan içe aktarmalar çözülmez. Takma ad hem TypeScript'e hem Vite'a bildirilmelidir.
• @types/node kurmayı unutmak: path modülü ve __dirname için gereken türler bu paketle gelir; kurulmazsa yapılandırma dosyasında tür hatası görürsünüz.
• tailwindcss() eklentisini plugins dizisine eklememek: Paket kurulu olsa bile eklenti tanımlanmadıysa Tailwind sınıfları işlenmez ve bileşenler stilsiz görünür.
• Takma adı farklı klasörlere yönlendirmek: tsconfig dosyalarında ./src/*, vite.config.ts içinde ./src kullanılmalıdır. Biri kök klasörü gösterirse bileşen dosyaları bulunamaz.
• JavaScript şablonu seçip TypeScript adımlarını uygulamak: JavaScript projesinde tsconfig yerine jsconfig.json kullanılır ve components.json içinde tsx değeri false olmalıdır.

Sık Sorulan Sorular

Neden hem tsconfig hem vite.config.ts içinde takma ad tanımlıyorum?

İki dosya farklı araçlara hizmet eder. tsconfig dosyaları TypeScript'in ve editörünüzün yolu çözmesi içindir; vite.config.ts ise Vite'ın geliştirme sunucusu ve derleme sırasında içe aktarmaları bulması içindir. Belge her iki ayarı da zorunlu adım olarak listeler.

src klasörü olmadan kurabilir miyim?

Vite sayfası src klasörüne göre yazılmıştır. Farklı bir yapı kullanırsanız tsconfig, vite.config.ts ve components.json içindeki takma adları kendi yapınıza göre tutarlı biçimde ayarlamanız gerekir.

init beni hangi stili kullanmak istediğimi sormadı, neden?

Belgelere göre default stili kullanımdan kaldırılmıştır ve yeni projeler new-york stilini kullanır. Vite sayfası init sırasında yalnızca temel renk sorusunu örnek olarak gösterir.

Tailwind v3 kullanan eski bir Vite projem var, ne yapmalıyım?

Tailwind v4 sayfasına göre değişiklik geriye dönük uyumludur: Tailwind v3 ve React 18 ile çalışan mevcut uygulamalar çalışmaya devam eder. Güncel Vite sayfası ise Tailwind v4 içindir. Tailwind v3 ile kurulan shadcn/ui projelerinin belgeleri, Legacy sayfasında belirtilen ayrı adreste tutulur. Projeyi yükseltmek isterseniz Tailwind v4 geçişi yazısına bakın.

TanStack Router ya da TanStack Start ile de bu adımları mı izlemeliyim?

Hayır. Bu iki çatının belge sayfaları, projeyi kendi oluşturma araçlarıyla --tailwind --add-ons shadcn seçenekleri vererek kurar ve ardından doğrudan add komutuna geçer. Vite sayfasındaki elle yapılan tsconfig ve vite.config.ts adımları düz bir Vite + React projesi içindir.

Vite projesinde "use client" yönergesi gerekir mi?

Bu yönerge React Server Components içindir ve components.json içindeki rsc alanıyla yönetilir. Belgeye göre CLI, rsc değeri true olduğunda istemci bileşenlerine yönergeyi otomatik ekler. Konu Next.js kurulumu yazısında ayrıntılı anlatılıyor.

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 · Next.js kurulumu · Dark mode · components.json · TypeScript paths · Tailwind CSS v4