ADR-007: Frontend Framework Olarak Next.js App Router Secimi

Baglam

Zeus 2.0 frontend'i kurumsal bir enerji yonetim dashboard'udur. Gereksinimler:

Cok sayfalı uygulama: Dashboard, cihaz yonetimi, SLD (Tek Hat Semasi), alarmlar, raporlar, ayarlar — 20+ sayfa
Gercek zamanli veri: WebSocket ile anlik telemetri gosterimi
Karmasik UI bilesenleri: SLD editor (React Flow), grafikler (amCharts), tablolar, formlar
TypeScript: Tip guvenligi zorunlu
Responsive: Masaustu oncelikli, mobil destegi
Performans: Buyuk veri setlerinde akici kullanici deneyimi

Next.js 14 (App Router) frontend framework olarak secildi. UI bilesen kutuphanesi olarak shadcn/ui (Radix UI tabanli) tercih edildi.

Artilari: Daha dusuk ogrenme egrisi, Composition API, Nuxt ile SSR/SSG
Eksileri: Daha kucuk kurumsal ekosistem, React kadar genis bilesen kutuphanesi yok (ozellikle SLD/flow editoru icin)
Red nedeni: React Flow (SLD editoru) ve amCharts React wrapper'lari Vue'da karsiligi olmayan kritik bilesenler

Artilari: Kurumsal projeler icin olgun, built-in dependency injection, RxJS
Eksileri: Ogrenme egrisi cok yuksek, bundle boyutu buyuk, gelistirme hizi dusuk
Red nedeni: Gelistirme hizi onceligi ve ekip tercihi

Artilari: Daha olgun ve stabil, daha genis dokumantasyon
Eksileri: Nested layout destegi yok (her sayfada layout tekrari), React Server Components yok, _app.tsx ve _document.tsx karmasikligi
Red nedeni: App Router'in nested layout ve RSC avantajlari tercih edildi

Artilari: Hizli build, minimum abstraksiyon, tam kontrol
Eksileri: Routing manuel (react-router), SSR/SSG yok, API proxy yapilandirmasi ek is
Red nedeni: File-based routing, API rewrites ve built-in optimizasyonlardan vazgecmek gereksiz is yuku olusturur

Next.js App Router su temel avantajlari sundu:

App Router (nested layouts): Dashboard layout'u, sidebar, header gibi ortak bilesenler layout.tsx ile bir kez tanimlanir — sayfa gecislerinde yeniden render edilmez
File-based routing: app/devices/[id]/page.tsx → /devices/123 — routing konfigurasyonu gereksiz
API rewrites (CORS cozumu): next.config.js icinde rewrite kurallari ile FastAPI'ye proxy — frontend'te CORS sorunu yok
TypeScript native: Proje olusturma asamasinda TypeScript entegre — ek yapilandirma gerektirmez
shadcn/ui ekosistemi: Radix UI primitifleri + Tailwind CSS — erisilebilir, ozellestirilebilir, kopyala-yapistir bilesenleri
React Server Components (RSC): Statik icerik sunucuda render edilir — client bundle kuculur (kullanilan yerlerde)
Middleware: Auth kontrolu, redirect, header manipulasyonu — ek paket gerektirmez

Nested layout ile dashboard yapisi cok temiz — sidebar ve header bir kez tanimlanmis
20+ sayfa file-based routing ile kolayca yonetiliyor
API rewrite sayesinde CORS konfigurasyonu gereksiz — gelistirme ve production ortaminda ayni sekilde calisiyor
shadcn/ui bilesenleri Tailwind ile tutarli gorunum sagliyor
React Flow (SLD) ve amCharts entegrasyonu sorunsuz

NEXT_PUBLIC_* build-time bake sorunu: Environment variable'lar build sirasinda literal string olarak gomulur — runtime'da degistirilemez. Bu sorun siteConfig pattern'i ile cozulmustur (bkz. frontend/src/config/site.ts)
Ogrenme egrisi: App Router, Pages Router'dan farkli paradigma — Server Components vs Client Components ayrimi kafa karistirici olabilir
Build suresi: Next.js build suresi buyuk projelerde uzun olabilir — CI/CD'de 15 dakika timeout tanimlanmis
"use client" directive'inin nereye konulacagi bazen belirsiz — gereksiz client component olusturulma riski