Feature-Sliced Design

Klasör Yapısı ve İsimlendirme rehberinde özelliğe göre dizilimi gördük. Feature-Sliced Design (FSD) bunun üstüne kural ekler: kodun hangi katmana ait olduğu ve neyi import edebileceği. Bu rehber FSD'nin modelini kısaca anlatıyor, Next.js'e uyarlamasını ve ViraStack Start'taki kullanımını gösteriyor.

Katmanlar

FSD, frontend uygulamaları için bir mimari yöntemdir: projeyi iş gereksinimleri değişirken anlaşılır ve kararlı tutmayı hedefleyen kurallar ve kurallar topluluğu.¹ Kod katmanlara ayrılır. Yukarıdan aşağıya:¹²

Eski bir processes katmanı da vardı. Spesifikasyon artık kullanılmamasını ve içeriğinin features ile app'e taşınmasını öneriyor.² Katmanların hepsi zorunlu değil: çoğu proje en az shared, pages ve app kullanır, widgets ile entities isteğe bağlıdır.²

Dilim ve bölüm

Her katman dilimlere (slice) ayrılır. Dilim kodu iş alanına göre gruplar, adı serbesttir. app ve shared dilimsizdir. Dilimin içi ise teknik amaca göre bölümlere (segment) ayrılır. Yaygın adlar ui, api, model (şema, store, iş mantığı), lib ve config'dir ama standart değildir.¹

features/
  add-to-cart/
    ui/
    api/
    model/
    index.ts

Tek kural: aşağıya doğru import

Bir katmandaki modül yalnızca kendi altındaki katmanlardan import edebilir. Aynı katmandaki dilimler de birbirini import edemez.¹² Yani features, entities ve shared'i bilir; tersi olmaz.

Her dilim dışarıya bir public API açar, genelde bir index dosyası. Dışarıdaki kod dilime yalnızca buradan ulaşır; böylece dilimin iç yapısı değişince geri kalan kod etkilenmez.³ İki uyarı: export * dilimin neyi sunduğunu gizler ve iç ayrıntıyı sızdırabilir, ayrıca dilim içinde göreli, dilimler arasında mutlak import kullanılmalıdır.³

Next.js ile

Next.js Next.js'in app ve pages adları FSD katmanlarıyla çakışır. FSD dokümanı iki katmanı _app ve _pages diye yeniden adlandırmayı, Next.js'in app/ klasörünü ise proje kökünde tutmayı önerir. Rota dosyaları FSD kodunu yeniden dışa aktaran ince dosyalar olur:⁴

app/                     # Next.js rotaları (kök)
  example/page.tsx       # @/_pages/example'dan re-export
src/
  _app/  _pages/  widgets/  features/  entities/  shared/

Bir dilim hem istemci hem yalnızca sunucuda çalışan modül içeriyorsa, sunucuya özel dışa aktarımları index.ts yerine index.server.ts'e koymanız önerilir.⁴

ViraStack Start'ta

ViraStack Start şablonları (Next.js ve TanStack Start) "Feature-Sliced" yapıyla gelir. ViraStack AI'nın mimari kuralına göre kod önce features/<feature>/ altında başlar. Her özellik api, components, hooks, schemas, stores, types gibi bölümleri ve bir index.ts (public API) içerir. Özellikler birbirini import etmez, dışarıdan yalnızca index.ts üzerinden erişilir. Rota dosyaları yalnızca veri yükler ve bir feature component'i çizer.⁵

FSD'nin tam modelinden farkı şu: pages, widgets ve entities katmanları yok, ortak kod src/ altında düz klasörlerde duruyor. Yani Start, FSD'nin dilim ve public API fikrini sadeleştirerek kullanıyor. FSD kademeli benimsenebildiği için bu kısmi kullanım meşru; ekip ve kod büyürse katman kuralı eklenebilir.¹ Bu karşılaştırma bu rehberin yorumudur.

Ne zaman gerekmez?