Luminary'ın Next.js Dönüşümünde Kazanılan 5 Kritik Ders

Luminary, kadınların bilimden sanata, aktivizmden teknolojiye kadar farklı alanlarda değişim yaratmasını kutlayan küresel bir topluluk platformu. Dört haftalık yoğun bir sprint sonunda tamamen sıfırdan geliştirilen proje, kullanıcıların aday gösterme ve kendi kendine başvuru yapabilmesine olanak tanıyan basit bir HTML/CSS/JS uygulaması olarak hayata geçirilmişti. Ancak büyümeyle birlikte bakım ve ölçeklenebilirlik sorunları ortaya çıkmaya başladı. Geliştirme ekibi, platformu modern bir mimariye taşımaya karar verdi ve böylece ikinci bir sprint başladı.

Bu yeniden yapılandırma projesi, Luminary’yi statik sayfalardan dinamik bir Next.js uygulamasına dönüştürmeyi hedefliyordu. Projenin çekirdeği, Turborepo monorepo yapısı altında Next.js (App Router) + TypeScript tabanlı bir frontend ve Express + Supabase destekli bir backend olarak yeniden tasarlandı. Stillerde Tailwind CSS kullanılırken, erişilebilir bileşenler için Base UI tercih edildi. Veri çekme işlemlerinde TanStack Query kullanıldı ve tüm ekip, tasarım sistemiyle uyumlu ortak bileşenler geliştirdi.

Yeniden Yapılandırmanın İlk Haftası: Formların Modernleştirilmesi

İlk haftada ekip, aday gösterme akışını baştan sona ele aldı. Eski versiyonda elle yazılmış DOM manipülasyonuna dayanan form, artık bileşen odaklı bir React uygulamasına dönüştürüldü. Bu süreçte dikkat çeken başlıca iyileştirmeler şunlardı:

• Bileşenlerin yeniden kullanılması: Eski formun her bir girişi ayrı ayrı elle yazılmıştı. Yeni sistemde, FormField, TextField, FormLabel ve Base UI’nin SelectField bileşenleriyle tüm girişler merkezi bir yapıya kavuştu. Bu sayede etiketler ve giriş alanları her yerde aynı şekilde kullanılabilir hale geldi.

• Verinin bileşenlerden ayrılması: Formun başlangıç durumu, sekmeler ve alan seçenekleri gibi sabit veriler, bileşenlerden veri katmanına taşındı. Böylece bileşenler sadece render işlemine odaklandı.

• Tasarım bütünlüğü: Eski sistemde HTML’in button ve div etiketleriyle elle oluşturulan düğmeler ve açılır pencereler, tasarım sisteminin standart Button ve Drawer bileşenleriyle değiştirildi. Bu sayede tüm arayüzde tutarlı bir görünüm sağlandı.

• Servis katmanının güçlendirilmesi: Gömülü toPayload metoduna sahip NominationService ve UploadService gibi servisler oluşturuldu. Ayrıca hata mesajlarının standartlaştırılması için ortak bir hata yardımcı programı eklendi.

• Veri gönderim akışının basitleştirilmesi: Eski try/catch blokları, TanStack Query’nin mutation onError özelliğiyle değiştirildi. API hataları, tip güvenli yanıt şekline dönüştürüldü.

Bu hafta boyunca karşılaşılan en büyük zorluklardan biri, eski imperative kod yapısının bileşen odaklı bir yaklaşıma nasıl uyarlanacağıydı. Eski form, doğrudan DOM manipülasyonuna dayanıyordu ve bu yapıyı bileşenlere dönüştürmek, özellikle etiketler, giriş alanları ve düğmeler gibi tekrar eden öğelerin yeniden kullanılabilir hale getirilmesini gerektirdi. Ayrıca, Isaac adlı ekip üyesinin yaptığı kod incelemelerine yanıt vermek de önemli bir zaman aldı. İncelemeler, projenin React Compiler’la çalıştığı için gereksiz memoization’ların kaldırılması ve ortak yardımcı programların kullanılması gibi iyileştirmeleri içeriyordu.

İkinci Hafta: Veri Entegrasyonu ve Profil Sayfalarının Taşınması

İkinci hafta, projenin veri katmanına odaklandı. Ekip, direktörlük ve profil sayfalarını canlı API’ye bağlamak için çalıştı. Bu süreçte yapılan başlıca iyileştirmeler şunlardı:

• Profil sayfalarının dinamik olarak oluşturulması: Eski profile.html sayfası, Next.js’in dinamik rotaları kullanılarak yeniden yapılandırıldı. /directory/[id] rotası oluşturuldu ve profil başlığı, hakkında bölümü ve ilgili bağlantılar bileşenlere dağıtıldı. Resimler için next/image kullanıldı ve orijinal dekoratif çerçeve korundu.

• Veri eşleştirme katmanının eklenmesi: API’den gelen tutarsız URL alanlarını normalize etmek için toNomineeProfile adlı bir eşleştirici oluşturuldu. Bu eşleştirici, hem direktörlük listesinde hem de yeni getProfileById fonksiyonunda kullanıldı.

• Resim konfigürasyonunun ayarlanması: Profil ve avatar resimlerinin Next.js görüntü hattından geçebilmesi için uzak resim kaynakları izin listesine eklendi.

Bu hafta karşılaşılan zorluklardan biri, direktörlük kartlarının nominee ID üzerinden anahtarlanırken, detay endpoint’in nomination ID üzerinden arama yapmasıydı. Bu uyumsuzluk nedeniyle bağlantılar hiçbir zaman çözümlenemiyordu. Ortak eşleştiriciyle her iki ID tipi de nomination ID olarak standartlaştırıldı.

Başka bir sorun da yerel geliştirme ortamında backend’in çalışmamasıydı. Ortam dosyası eksik olan backend, Supabase istemcisinin Node.js 22’nin native WebSocket desteklemediği için hata vermesine neden oluyordu. Bu sorun, ws paketinin eklenmesiyle çözüldü. Ayrıca, port 5000’in işletim sistemi tarafından rezerve edildiği ve uygulamanın yerine kernel’in yanıt verdiği anlaşıldı. Geliştirme portunun değiştirilmesiyle sorun hızla giderildi.

Dönüşümden Çıkarılan Kritik Dersler

Bu iki haftalık sprint boyunca Luminary ekibi, modern web geliştirme uygulamalarının önemini bir kez daha gördü. En değerli dersler şunlardı:

1. Bileşen odaklı geliştirme, tutarlılığı ve bakım kolaylığını artırıyor. Eski sistemdeki elle yazılmış DOM manipülasyonu, bileşenlerin yeniden kullanılabilirliğini ve bakımını zorlaştırıyordu. Yeni sistemde, her bileşen tek bir sorumluluğa sahip ve tasarım sistemiyle uyumlu hale geldi.

1. Veri katmanını bileşenlerden ayırmak, kodun okunabilirliğini ve esnekliğini artırıyor. Sabit verilerin bileşenlerden bağımsız olarak yönetilmesi, kodun daha temiz ve anlaşılır olmasını sağladı.

1. Tip güvenliği, API entegrasyonunu basitleştiriyor ve hata riskini azaltıyor. TypeScript’in sunduğu tip güvenliği sayesinde API yanıtları ve istekleri standartlaştırıldı. Bu da hem geliştirme sürecini hızlandırdı hem de hata oluşma olasılığını düşürdü.

1. Veri çekme ve gönderme işlemlerinde TanStack Query kullanmak, kod karmaşıklığını azaltıyor. Manuel hata yönetimi ve yanıt işleme yerine, TanStack Query’nin sunduğu araçlar sayesinde veri akışı daha basit ve anlaşılır hale geldi.

1. İnceleme geri bildirimlerine yanıt vermek, kod kalitesini doğrudan etkiliyor. Ekip liderinin yaptığı kod incelemeleri, projede standartlara uyumun ve en iyi uygulamaların benimsenmesini sağladı.

Geleceğe Yönelik Adımlar

Luminary’ın bu modern mimariye geçişi, sadece teknik bir yenilik değil, aynı zamanda topluluk platformlarının nasıl daha ölçeklenebilir ve kullanıcı dostu hale getirilebileceğine dair önemli bir örnek teşkil ediyor. Gelecekte ekip, kullanıcı deneyimini daha da iyileştirmek ve platformun küresel etkisini artırmak için yeni özellikler ve performans iyileştirmeleri üzerinde çalışmaya devam edecek. Bu süreçte edinilen dersler, hem Luminary hem de diğer geliştiriciler için değerli bir kaynak olmaya devam edecek.