shadcn/ui Next.js Kurulumu: init, rsc Alanı ve "use client"

init: yeni proje mi, mevcut proje mi?

Next.js kurulum sayfası diğer çatılardan daha kısadır, çünkü hazırlığın büyük kısmını CLI üstlenir. Belgeye göre init komutu ya yeni bir Next.js projesi oluşturur ya da mevcut bir projeyi kurar. Changelog'daki Ağustos 2024 kaydı da komutun çatı algılaması yaptığını ve tek komutla yepyeni bir Next.js uygulaması başlatabildiğini söyler.

npx shadcn@latest init

Komutu proje dosyası bulunmayan bir klasörde çalıştırdığınızda proje türü sorulur. Monorepo sayfası bu soruyu şöyle gösterir:

? Would you like to start a new project?
    Next.js
❯   Next.js (Monorepo)

Next.js tek bir uygulama oluşturur. Next.js (Monorepo) ise web ve ui adlı iki workspace ile Turborepo tabanlı bir yapı kurar; bu seçenek monorepo kurulumu yazısının konusudur. Aynı seçimi soruyu beklemeden -t next ya da -t next-monorepo seçeneğiyle de yapabilirsiniz. --src-dir ve --no-src-dir seçenekleri de belgeye göre yalnızca yeni proje oluşturulurken etkilidir ve kodun src klasöründe tutulup tutulmayacağını belirler.

npx shadcn@latest init -t next
npx shadcn@latest init -t next --src-dir

Mevcut bir Next.js projesinde ise init, proje oluşturma adımını atlar ve doğrudan yapılandırmaya geçer: bağımlılıkları kurar, cn yardımcısını ekler ve CSS değişkenlerini global CSS dosyanıza işler. Changelog'a göre mevcut bir uygulamaya kurulurken Tailwind dosyalarınızın üzerine yazılmaz, güncellenir.

init sonrasında projede neler değişir?

Next.js projesinde init tamamlandığında shadcn/ui'ye ait dosyalar varsayılan takma adlara göre yerleşir: proje kökünde components.json, lib/utils.ts içinde cn fonksiyonu, global CSS dosyanızda tema değişkenleri ve ilk add komutundan sonra components/ui klasörü. Tailwind v4 kullanan bir projede global CSS dosyasının başı, manuel kurulum sayfasında gösterilen yapıya benzer:

@import "tailwindcss";
@import "tw-animate-css";

@custom-variant dark (&:is(.dark *));

:root {
  --background: oklch(1 0 0);
  --foreground: oklch(0.145 0 0);
  /* ... diğer değişkenler ... */
}

Buradaki tw-animate-css içe aktarması bileşen animasyonları içindir; belgelere göre eski tailwindcss-animate eklentisi bu paket lehine kullanımdan kaldırılmıştır. @custom-variant dark satırı ise .dark sınıfı altındaki öğeler için karanlık mod varyantını tanımlar. Değişkenlerin tam listesini tema ve CSS değişkenleri yazısında, CSS değişkenlerinin genel mantığını ise CSS değişkenleri yazısında bulabilirsiniz.

Projenizde src klasörü kullanıyorsanız components.json belgesindeki önemli bir uyarıyı hatırlayın: src klasörü tsconfig.json dosyanızdaki paths ayarında yer almalıdır. CLI, bileşenleri doğru yere koymak için aliases değerlerini bu paths ayarıyla birlikte okur.

Bileşen ekleme ve sayfada kullanma

Kurulumdan sonra bileşen eklemek her çatıda olduğu gibi add komutuyla yapılır:

npx shadcn@latest add button

Belgedeki örnek, bileşeni App Router'ın ana sayfası olan app/page.tsx dosyasında kullanır. Etiketi Türkçeleştirdiğimiz hâli şöyledir:

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

export default function Home() {
  return (
    <div>
      <Button>Tıklayın</Button>
    </div>
  )
}

Bu dosyada "use client" yönergesi yoktur; sayfa varsayılan hâliyle bir Server Component olarak kalır ve Button bileşenini içe aktarabilir. Bunun nedeni, depodaki button.tsx dosyasının da bir "use client" yönergesi taşımamasıdır. App Router'daki Server ve Client Component ayrımının kendisi Next.js'in konusudur; ayrıntı için Next.js 15 App Router yazısına bakabilirsiniz.

rsc alanı ve "use client" yönergesi

components.json dosyasındaki rsc alanı, React Server Components desteğinin açık olup olmadığını belirtir. Belgeye göre bu alan true olduğunda CLI, istemci bileşenlerine "use client" yönergesini otomatik olarak ekler. Haziran 2023 changelog kaydı bunu biraz daha açar: React Server Components desteklemeyen bir çatı kullanıyorsanız rsc değerini false yaparsınız ve CLI bileşen eklerken yönergeyi ekler ya da kaldırır. Next.js App Router projelerinde bu değer true olur. Tema belgesindeki örnek components.json dosyası bu kullanıma uygun bir yapılandırmayı gösterir:

{
  "style": "new-york",
  "rsc": true,
  "tailwind": {
    "config": "",
    "css": "app/globals.css",
    "baseColor": "neutral",
    "cssVariables": true
  },
  "aliases": {
    "components": "@/components",
    "utils": "@/lib/utils",
    "ui": "@/components/ui",
    "lib": "@/lib",
    "hooks": "@/hooks"
  },
  "iconLibrary": "lucide"
}

Burada tailwind.css alanı Next.js'in app/globals.css dosyasını gösterir; tailwind.config ise Tailwind v4 kullanıldığı için boştur. Diğer alanların ayrıntısı components.json ayarları yazısında.

Hangi bileşenler istemci bileşeni?

Depodaki new-york-v4/ui klasörüne baktığımızda dosyaların bir kısmının ilk satırında "use client" yönergesi bulunduğunu, bir kısmında bulunmadığını görürüz. Listeye bakınca açılır pencerelerin, menülerin ve form kontrollerinin ilk grupta; kart, rozet, iskelet gibi yalnızca görünüm üreten bileşenlerin ise ikinci grupta toplandığı görülür.

Bu tablo depo kopyasındaki kaynak dosyalardan çıkarılmıştır; kendi projenizdeki dosyalar, rsc ayarınıza göre CLI tarafından düzenlenir. Örneğin dialog.tsx dosyası şu satırlarla başlar:

"use client"

import * as React from "react"
import * as DialogPrimitive from "@radix-ui/react-dialog"

Böyle bir bileşeni bir Server Component sayfasında içe aktarabilirsiniz; bileşenin kendisi istemci tarafında çalışır. Ancak bileşene onClick gibi bir olay işleyicisi ya da useState ile tutulan bir durum bağlamak istiyorsanız, bu kodu kendi istemci bileşeninize taşımanız gerekir. Aşağıdaki küçük örnekte components/sayac.tsx dosyası bunu yapar:

"use client"

import * as React from "react"

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

export function Sayac() {
  const [sayi, setSayi] = React.useState(0)

  return (
    <Button variant="outline" onClick={() => setSayi(sayi + 1)}>
      Tıklama: {sayi}
    </Button>
  )
}

Sayfanız Server Component olarak kalabilir ve Sayac bileşenini içe aktarıp kullanabilir. variant="outline" değeri Button'ın belgelenmiş varyantlarından biridir; diğerleri için Button varyantları yazısına bakın.

Mevcut bir Next.js projesine kurarken

Yeni bir projede init her şeyi sıfırdan hazırlar; uzun süredir geliştirdiğiniz bir projede ise birkaç noktayı önceden düşünmek işinizi kolaylaştırır. İlk olarak çalışmanızı sürüm kontrolüne kaydedin: init global CSS dosyanızı ve package.json dosyanızı değiştirir, değişiklikleri sonradan karşılaştırabilmek önemlidir. İkinci olarak Tailwind sürümünüzü bilin. Tailwind v4 sayfasına göre 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 biçiminde gelir; yükseltme adımları Tailwind v4 geçişi yazısında. Üçüncü olarak components/ui adında kendi bileşenlerinizi tuttuğunuz bir klasör varsa, çakışmayı önlemek için aliases.ui değerini farklı bir klasöre yönlendirmeyi düşünebilirsiniz.

Kurulumla birlikte blok eklemek

Next.js projesine sıfırdan başlıyorsanız init komutuna doğrudan bileşen ya da blok adı verebilirsiniz. Changelog'daki Ağustos 2024 kaydı bunun örneğini verir: aşağıdaki komut projeyi kurar ve sidebar-01 ile login-01 bloklarını ekler. Bir blok yalnızca tek bir dosyadan ibaret olmayabilir; kullandığı bileşenleri de bağımlılık olarak getirebilir. Monorepo sayfası aynı mantığı login-01 örneğiyle anlatır: CLI button, label, input ve card bileşenlerini ve bir login-form bileşenini kurar.

npx shadcn init sidebar-01 login-01

Bloklar hazır sayfa iskeletleridir ve yönetim paneli ya da giriş ekranı gibi işlerde hızlı bir başlangıç sağlar. Hangi blokların bulunduğunu ve nasıl özelleştirildiğini Blocks: hazır sayfa şablonları yazısında anlatıyoruz.

Next.js 15 ve React 19 notları

Belgelerde Next.js 15 ve React 19 için ayrı bir sayfa bulunur. Sayfanın başındaki not, React 19 ve Tailwind v4 desteğinin latest sürümüne tam olarak eklendiğini ve rehberin güncelliğini yitirmiş olabileceğini belirtir. Yine de npm kullananlar için önemli bir uyarı içerir: React 19'u peer dependency olarak listelemeyen paketler npm ile kurulurken hata verebilir. pnpm, bun ve yarn için ek bir bayrak gerekmez. npm kullandığınızda CLI size şu seçimi sunar:

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

Bu iki seçeneğin anlamı, belgenin önerdiği diğer çözümler ve hangi bağımlılığın durumu ne React 19 peer dependency hatası yazısında ayrıntılı anlatılıyor. Hangi yolu seçerseniz seçin, belge kurulumdan sonra uygulamanızı dikkatle test etmenizi önerir.

Next.js projesinde sonraki adımlar

• Karanlık mod: Next.js için belge next-themes paketini kurar, bir ThemeProvider bileşeni oluşturur ve onu kök layout'a ekler; html etiketine suppressHydrationWarning özelliği verilir. Ayrıntısı dark mode kurulumu yazısında.
• Formlar: Next.js'e özel form rehberi useActionState ve Server Actions ile doğrulama, bekleme durumları ve hata gösterimini anlatır (Server Actions ile form).
• Yerleşim: Bir yönetim paneli kuruyorsanız Sidebar ve hazır bloklar iyi bir başlangıçtır.
• Yayınlama: Uygulamanızı kendi sunucunuza almak için Next.js VPS deploy rehberi yazısına bakabilirsiniz.

Changelog'a göre Aralık 2025'te duyurulan npx shadcn create akışı Next.js için de kullanılabilir; bu yeni akışı yenilikler yazısında özetliyoruz.

Sık yapılan hatalar

• Her sayfaya "use client" eklemek: shadcn/ui bileşenlerini kullanmak için sayfanın istemci bileşeni olması gerekmez. Yönergeyi yalnızca durum ya da olay işleyicisi kullanan kendi bileşenlerinize ekleyin.
• rsc değerini yanlış ayarlamak: Changelog'a göre rsc false olduğunda CLI bileşen eklerken "use client" yönergesini kaldırır. React Server Components kullanan bir Next.js App Router projesinde istemci bileşenlerinin bu yönergeyi taşıması beklendiği için değer true olmalıdır.
• Yanlış CSS dosyasını göstermek: tailwind.css alanı, uygulamanızın gerçekten yüklediği global CSS dosyasını, çoğunlukla app/globals.css dosyasını göstermelidir. Aksi hâlde tema değişkenleri başka bir dosyaya yazılır.
• npm uyarısını rastgele geçmek: --force ve --legacy-peer-deps farklı şeyler yapar. Seçmeden önce farkı okuyun ve kurulumdan sonra uygulamayı test edin.
• Monorepo içinde yanlış klasörde add çalıştırmak: Monorepo şablonunda add komutu uygulamanın klasöründe, örneğin apps/web içinde çalıştırılmalıdır.
• Karanlık mod kurarken html etiketini unutmak: Next.js karanlık mod belgesi ThemeProvider eklerken kök layout'taki html etiketine suppressHydrationWarning verilmesini ister. Bu adım atlanırsa belgenin önerdiği kurulum eksik kalır.

Sık Sorulan Sorular

Pages Router kullanan bir projeye kurabilir miyim?

Next.js kurulum sayfası init'in mevcut projeleri de kurabildiğini söyler ama Pages Router için ayrı bir adım vermez. React Server Components kullanmayan bir yapıda rsc değerinin false olması gerektiğini changelog kaydı belirtir.

init yeni projeyi hangi sürümlerle oluşturur?

Belgeler kesin sürüm numarası vermez. Tailwind v4 sayfasına göre yeni projeler Tailwind v4 ve React 19 ile başlar; monorepo sayfası da monorepo şablonunun React 19 ve Tailwind CSS v4 kullandığını not eder.

shadcn/ui'nin kendi sitesi Next.js ile mi çalışıyor?

Evet. Changelog'daki Mayıs 2025 kaydına göre ui.shadcn.com Next.js 15.3 ve Tailwind v4'e yükseltildi ve site güncellenmiş new-york bileşenlerini kullanıyor. Bu serinin dayandığı belge dosyaları da depodaki apps/v4 klasöründe durur.

Button neden "use client" içermiyor?

Depodaki button.tsx dosyası durum ya da tarayıcıya özgü bir API kullanmaz; yalnızca sınıf adlarını hesaplar ve bir button ya da asChild ile başka bir öğe döndürür. Bu yüzden depo kopyasında yönergesiz durur ve Server Component içinde doğrudan kullanılabilir.

Next.js projesi için components.json elle yazılabilir mi?

Evet. Manuel kurulum sayfası dosyanın tamamını gösterir; Next.js App Router için rsc değerini true, tailwind.css değerini de app/globals.css olarak ayarlarsınız. Manuel kurulum sayfası da bu dosyayı ve diğer hazırlıkları tamamladıktan sonra projenize bileşen eklemeye başlayabileceğinizi söyler; CLI her add komutunda bu dosyadaki ayarları kullanır. Ayrıntı manuel kurulum yazısında.

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 · Dark mode · Server Actions ile form · Next.js App Router · Next.js deploy