Frontend Platformu için Golden Path: İskelet, Paylaşılan Paketler ve Görev CLI'si

Bir organizasyon çok sayıda küçük frontend uygulaması işlettiğinde, her ekip farklı bir iskeletten başlar ve build yapılandırması, lint kuralları ile dağıtım şekli birkaç sprint içinde birbirinden kayar. Bu kayma tembellikten değildir: bir uygulamayı başlatmanın standart yolunun aynı zamanda en hızlı yolu olduğu tek bir yer yoktur, bu yüzden her ekip temelleri yeniden kurar ve gözlemlenebilirliği, i18n’i ve dağıtımı biraz farklı şekilde yeniden uygular. Çözüm, üç temel taştan kurulan ince bir asfalt yoldur (bir golden-path iskeleti, sürümlü paylaşılan paketler ve bir görev CLI’si); işe yaradığını kanıtlayan tek ölçüt ise gönüllü benimsemedir, zorunlu kapsam değil.

Ekip Kayması Neden Birikir

Kaymanın yapısal bir nedeni vardır, disiplinle ilgili değil. Standart kurulum araçlarda değil dokümantasyonda yaşadığında, her yeni uygulama tüm kurulum maliyetini yeniden öder, bu yüzden ekipler en yakın mevcut repoyu kopyalar ve derlenene kadar düzenler. Özellikle dört maliyet üst üste binerek büyür:

• Build yapılandırması, lint kuralları ve test eşikleri, paylaşılan bir kaynaktan genişletilmek yerine kopyalandığı için birbirinden ayrışır. Bir kural değişikliği o zaman N repoda N düzenleme gerektirir.
• Gözlemlenebilirlik, i18n ve dağıtım manifestoları uygulama başına yeniden uygulanır, bu yüzden platform genelindeki bir değişiklik tek bir göç yerine N bağımsız göç haline gelir.
• Paylaşılan UI ve tasarım token’ları her uygulamaya çatallanır ya da kopyalanır, bu yüzden bir tasarım değişikliği hiçbir zaman her yere aynı anda inmez.
• Kimlik bilgilerini almanın, servis token’larını değişmenin ve dağıtım yapmanın adımları bir araçta değil birinin shell geçmişinde yaşar, bu yüzden yeni bir uygulamayı ya da mühendisi devreye almak günlerce kopyala-yapıştır-ve-ayıkla sürer.

Çözüm daha fazla dokümantasyon ya da daha sıkı bir inceleme listesi değildir. Çözüm, standart yolu en az direnç gösteren yol haline getirmektir; öyle ki bir ekip ona uzanır çünkü kendi yolunu kurmak daha yavaştır. Asfalt yol fikri budur ve Netflix bunu açıkça ifade eder: asfalt-yol araçlarının benimsenmesini zorunlu kılmaz, bunu “bu teknolojilerle geliştirme ve operasyonun, onları kullanmamaktan çok daha iyi bir deneyim olmasını sağlayarak” kazanır (Full Cycle Developers at Netflix). Spotify aynı fikri, parçalanmayı azaltan ve ekiplerin “daha az karar vermesini” sağlayarak yaratıcılığı daha yüksek hedeflere yönlendiren bir Golden Path olarak çerçeveler (How We Use Golden Paths).

Yolun sahibi platform ekibidir; ürün ekipleri onun üzerinde ilerler. Gözlemlenebilirlik, i18n, dağıtım şekli ve tasarımda tutarlılık, her ekibin yeniden icat ettiği bir şey olmaktan çıkıp varsayılan durum haline gelir. Yol bir üründür, Team Topologies anlamında: bir platform ekibi, onu tüketen ekiplerin “teslimatını hızlandıracak ikna edici bir iç ürün” kurar (Team Topologies Key Concepts). Aşağıdaki üç temel taş, o ürünün en ince versiyonudur.

Golden-Path İskeleti

İlk temel taş, ilk klonlamada üretime hazır olan bir başlangıç reposudur. Bir ekip onu klonlar, uygulamayı yeniden adlandırır ve herhangi bir özellik kodu yazmadan önce çalışan bir build, lint, test, bileşen atölyesi ve dağıtım manifestosuna sahip olur. İskelet, donmuş bir anlık görüntü üreten bir oluşturucu değil, klonla-ve-başla bir monorepodur; çünkü bir araya getirdiği şeyler, ürettiği dosya ağacından daha önemlidir.

Faydalı bir iskelette neler bulunur:

• Monorepo çalışma alanı araçları. Bu yerleşmiş değil, canlı bir tercihtir. lerna kendini artık “JavaScript monorepoları için orijinal araç” ve “Nx tarafından desteklenen hızlı, modern bir build sistemi” olarak tanıtır (lerna.js.org), yani modern hikâye “lerna’yı bırak” değil, lerna artı Nx önbelleğidir. Alternatifler, görev grafiği ve hesaplama önbelleği olan akıllı bir build sistemi olan tek başına Nx (Nx intro) ve önbellekleyen başka bir monorepo build sistemi olan Turborepo’dur (Turborepo docs). Bir görev çalıştırıcı ve bir sürümleme aracı seçin; başarısızlık modu, ikisi de yayını sahiplenmeye çalışan iki aracı birlikte çalıştırmaktır.
• Paylaşılan TypeScript ve lint/format yapılandırması, kopyalanmadan genişletilerek. İskelet, kuralları içine gömmek yerine paylaşılan kayıttan yayınlanan bir yapılandırmayı genişletir, böylece bir kural değişikliği bir kez gönderilir ve uygulamalar yükseltmede onu çeker.
• Kapsam eşikleri yerleşik test kurulumu. Yol tabanı zorunlu kılar; ekip, onun üzerinde neyi test edeceğine kendi karar verir.
• Önceden bağlanmış bir bileşen atölyesi. Storybook “UI bileşenlerini ve sayfalarını izole halde kurmak için bir frontend atölyesidir” (Storybook docs); mevcut ana sürüm hattı Storybook 10’dur ve npm create storybook@latest ile iskelet kurulur. Sabitlemeden önce araç zincirinizdeki tam yamayı doğrulayın.
• Standartlaştırılmış bir dağıtım manifestosu. Bunu, her uygulamanın gönderdiği bir delivery.yaml olarak genelleştirin; böylece gözlemlenebilirlik, i18n ve yönlendirme ekip başına değil varsayılan olarak bağlanır.

Bir iskelet kurma komutu, özel bir oluşturucu değil, sıradan bir klonlama artı bir yeniden adlandırma adımı gibi görünür:

git clone <skeleton-repo> my-app && cd my-app
node ./scripts/rename-app.mjs my-app
npm install
npm run dev

Bir dağıtım manifestosu, eskiden uygulama başına farklılaşan dağıtım şeklini taşır. Genelleştirildiğinde uygulamayı, çalışma zamanını ve yolun varsayılan olarak bağladığı kesişen kaygıları adlandırır:

# delivery.yaml
app: my-app
runtime: node-20
observability:
  tracing: enabled
  logs: structured
i18n:
  default: en
  locales: [en, tr]
routing:
  base_path: /my-app

Manifesto, uygulama ile yol arasındaki sözleşmedir. Her uygulama aynı şekli bildirdiği için, gözlemlenebilirliğin ya da yönlendirmenin nasıl sağlandığına dair platform genelindeki bir değişiklik, her uygulamayı değil yolu düzenler.

Sürümlü Paylaşılan Paketlerin Kaydı

İkinci temel taş, uygulamaların semver ile tükettiği bir paylaşılan paket kaydıdır: bir UI bileşen kütüphanesi, bir tasarım-token paketi ve bir istek istemcisi ile sunucu ara katmanı gibi küçük paylaşılan yardımcılar. Anahtar özellik, bağımsız sürümlemedir. Platform yeni bir sürüm gönderir; ekipler onu kendi temposunda çeker. Özerkliği koruyan budur, çünkü yol zorla küresel bir yeniden inşa değil, sürümlüdür.

Bağımsız sürümleme, changelog otomasyonu gerektirir. changesets “monorepolara odaklanarak sürümleme ve changelog’ları yönetmek için bir araçtır” (changesets); bir katkıda bulunan bir niyet kaydeder ve araç, sürüm anında sürümleri ve changelog’ları hesaplar. Proje birden fazla dal sürdürdüğü için benimsemeden önce kurulumunuzda hangi sürüm hattının GA olduğunu doğrulayın. lerna da aynı iş için lerna version ve lerna publish sunar. Birini seçin ve ikisini birlikte çalıştırmayın, yoksa sürüm artışları birbiriyle çatışır.

Bir changesets adımı, sürüm akışının kısa, çalıştırılabilir bir parçasıdır:

npx changeset            # bir niyet kaydet: hangi paketler degisti, hangi artisla
npx changeset version    # artislari uygula ve changelog'lari yaz
npx changeset publish     # degisen paketleri kayda yayinla

Semver sözleşmesi yük taşıyan kısımdır. Ayrıştırılmış benimseme, paylaşılan UI kütüphanesindeki bir düzeltmenin bir kez yayınlandığı ve uygulamaların onu yükselttiklerinde benimsediği, her uygulamanın aynı anda yeniden inşa etmediği anlamına gelir. Maliyeti sürüm dağınıklığıdır ve bunu bir sonraki bölüm ele alır, ama asıl mesele özerkliktir: sürümlü bir yol, ekibin üzerinde ilerlemeyi seçtiği bir yoldur, ayaklarının altından kayan bir yol değil.

Görev CLI’si

Üçüncü temel taş, tekrarlayan büyüleri saran bir görev CLI’sidir: kimlik bilgilerini almak, servis token’larını değişmek, kümeyle etkileşmek ve ortak build ile dağıtım adımlarını çalıştırmak. CLI yolun giriş rampasıdır; “doğru yolun kolay yol olması”nın gerçeğe dönüştüğü yer, ezberlenen bir shell dizisi yerine tek bir komut.

Düz çizgi yoldur; kesik çizgi, yol olmadan ne olduğudur. CLI önemlidir çünkü kabile bilgisini shell geçmişinden çıkarıp tüm organizasyonun paylaştığı ve platform ekibinin sürdürdüğü bir araca taşır. Dağıtım yolu, birinin hatırladığı bir dizi değil, dokümante edilmiş bir deploy alt komutu olduğunda, o diziye yapılan platform genelindeki bir değişiklik CLI’de gönderilir ve her ekip bir sonraki çekişte onu alır.

Bu, Netflix ergonomisini tam olarak yansıtır: yolu kullanma deneyimi, onu kullanmama deneyiminden daha iyidir, bu yüzden benimseme bir not olmadan gelir. CLI, bu deneyimin ilk günden hissedildiği yerdir.

İnce Yolu Ne Zaman Geçmeli

İnce yol varsayılandır, tek şekil değil. İki geçiş durumu adlandırmaya değer.

Keşfin kendisi bir maliyet haline geldiğinde bir geliştirici portalı ekleyin. Backstage, bir yazılım kataloğu üzerine kurulu, “yeni projeleri başlatmak ve araçları standartlaştırmak” için Software Templates ve dokümantasyon için TechDocs içeren, “geliştirici portalları kurmak için açık kaynaklı bir çerçevedir” (What is Backstage?). Bir portal, çok sayıda uygulama arasında doğru uygulamayı, sahibi ya da şablonu bulmak başlı başına bir sorun haline geldiğinde ağırlığını hak eder. O eşiğin altında, bir iskelet reposu artı bir CLI daha hafif ve daha hızlıdır ve portal kimsenin istemediği bir yüktür. Tetik tek başına uygulama sayısı değil, keşif maliyetidir: net sahipliği olan on uygulamanın portala ihtiyacı olmayabilir, sahipliği belirsiz dağınık bir mülkün ise vardır.

Riskler düzenleyici ya da güvenlik açısından kritik olduğunda teşvik etmek yerine zorunlu kılın. Tez teşvik etmeden yanadır, ama bazı bağlamlarda zorunlu kılma meşrudur. Standartlaştırma gücü üzerine yazılanlar, asfalt yolları ve golden path’leri, daha güçlü biçimlerin yalnızca teşvik etmek yerine kısıtladığı korkuluklardan ve raylardan ayırır (mia-platform: Paved Roads, Golden Paths, Guardrails and Railroads). Düzenlemeye tabi bir alanda, zorunlu bir dağıtım şekli ya da gerekli bir denetim kancası, katılığına değen bir korkuluktur. Pratik kural: ayrışmanın gerçek risk yarattığı yerlerde kapsam tabanlarını ve dağıtım şeklini zorunlu kılın; bileşen kompozisyonunu ve iş mantığını ekiplere bırakın.

Teşvik etmek önerilen daldır çünkü zorunlu bir yol, aynı zamanda daha kolay yol değilse gölge iskeletler üretir. Zorunlu kılmak risk dalıdır ve yalnızca risklerin katılığı haklı çıkardığı yerlerde meşrudur.

Bu, frontend’e özgü bir asfalt yoldur: iskelet kurma, sürümlü UI paketleri ve bir görev CLI’si; genel bir altyapı self-servis platformu değil. Sağlama, ad alanları ve küme erişimi gibi altyapı platformu kaygıları komşudur ve zaten var olabilir; frontend yolu onların üzerinde oturur ve hesabın nasıl sağlandığını değil, uygulamaların nasıl kurulduğunu ve gönderildiğini standartlaştırır.

Trade-off’lar

Her temel taş, baştan adlandırmaya değer bir maliyet taşır.

Temel taş	Ana fayda	Ana maliyet / başarısızlık modu
Golden-path iskeleti	Dakikalar içinde üretime hazır klon	Anlık görüntü çürümesi: iskelet dogfood edilmedikçe iskeletler eskir, üretilen uygulamalar güncel yoldan ayrışır
Sürümlü paketler	Bağımsız, ayrıştırılmış benimseme	Sürüm dağınıklığı: platform genelindeki bir düzeltme yine de ekiplerin yükseltmesini gerektirir, böylece eski sürümler kalır
Görev CLI’si	Kabile bilgisi paylaşılan bir araca dönüşür	Tek hata noktası ve bakım yükü; soyutlama, bir mühendisin hata ayıklarken görmesi gerekeni gizleyebilir

İskelet trade-off’u en keskin olanıdır. Donmuş bir anlık görüntü üreten bir iskelet, üretildiği anda eskir ve uygulamalar yeniden özel yapıma doğru kayar. Hafifletme, iskeleti dogfood etmek (platform ekibi ondan gerçek uygulamalar kurar) ve yapılandırmayı kopyalanmış yerine kayıttan-genişletilmiş biçimde tutmaktır, böylece yükseltmeler çatallanmak yerine akar.

Sık Yapılan Hatalar

Dört hata tekrar eder, her biri somut bir düzeltmeyle.

• Zorunlu ama daha kolay değil. Platform gereklidir ama kendi yolunu kurmaktan daha yavaştır, bu yüzden ekipler isteksizce uyar ya da gölge iskeletlerle etrafından dolaşır. Düzeltme: giriş rampası süresini ana sinyal olarak ele alın, yönetişim eklemeden önce sürtünmeyi giderin ve benimsemeyi gönüllü bırakın; böylece direnç, gizli geçici çözümler yerine düşük benimseme olarak yüzeye çıkar.
• Büyük patlama platformu. Kimsenin istemediği, varsayılan ihtiyaçlara göre tasarlanmış “tam” bir platform göndermek. Düzeltme: en ince uygulanabilir platformu gönderin ve onu gerçek talepten büyütün; Team Topologies’in Thinnest Viable Platform fikri.
• Eşzamanlı yükseltmeler. Her uygulamayı aynı anda en son paket sürümüne zorlamak, semver sözleşmesinin korumaya çalıştığı özerkliği yok eder. Düzeltme: semver artı bağımsız benimseme; uygulamaların ne kadar geride çalıştığına dair görünürlükle, böylece platform ekibi zorlamadan teşvik edebilir.
• Platformu ürün değil proje saymak. Yolu, iç müşterileri olan sürekli bir ürün değil, tek seferlik bir teslimat olarak ele almak. Düzeltme: platform-as-a-product; başarı ölçütü gönüllü benimseme ve ürün ekipleri, talepleri geri besleme döngüsü olan müşterilerdir.

Dördünün ortasından geçen ipliği tez oluşturur: zorunlu ama aslında daha kolay olmayan bir asfalt yol başarısız olur, çünkü yolun işe yaradığının tek kalıcı kanıtı ekiplerin onu seçmesidir.

Kapanış

Ekip kayması biriken, çok sayıda frontend uygulaması işleten bir organizasyon için ince asfalt yol; bir golden-path iskeleti, sürümlü paylaşılan paketler ve bir görev CLI’si; doğru varsayılandır ve işe yaradığını kanıtlayan ölçüt gönüllü benimsemedir. Bir geliştirici portalına yalnızca uygulamalar arası keşif başlı başına bir maliyet haline geldiğinde uzanın ve zorunlu kılmaya yalnızca ayrışmanın düzenleyici ya da güvenlik riski yarattığı yerde başvurun. Tek bir sonraki adım, bugün yeni bir uygulamanın giriş rampası süresini ölçmektir; dakikalar yerine günler sürüyorsa, o boşluk yolun ilk işidir.

Kaynaklar

• Full Cycle Developers at Netflix - Kanonik asfalt-yol duruşu: araçlar zorunlu kılınmaz, onları daha iyi deneyim haline getirerek teşvik edilir.
• Spotify Engineering: How We Use Golden Paths to Solve Fragmentation - “Golden path” çerçevesinin kökeni: parçalanmayı azalt, daha az karar.
• Team Topologies Key Concepts - Dört ekip türü; iç ürün olarak platform ekibi; Thinnest Viable Platform fikri.
• What is Backstage? - Yazılım kataloğu, Software Templates ve TechDocs içeren geliştirici-portalı çerçevesi; büyük organizasyonlar için geçiş durumu.
• What is platform engineering? - İç geliştirici platformu disiplininin topluluk tanımı.
• Nx: What is Nx? - Görev grafiği, hesaplama önbelleği ve modül-sınırı uygulaması olan akıllı monorepo build sistemi.
• Turborepo docs - Önbellekleyen alternatif monorepo build sistemi.
• Storybook docs - “UI bileşenlerini ve sayfalarını izole halde kurmak için bir frontend atölyesi”; mevcut ana sürüm hattı Storybook 10.
• changesets - Monorepolara odaklanan sürümleme ve changelog aracı; benimsemeden önce GA sürüm hattını doğrulayın.
• lerna - Orijinal JavaScript monorepo aracı, artık Nx ekibi tarafından sürdürülüyor ve “Nx tarafından destekleniyor”.
• mia-platform: Paved Roads, Golden Paths, Guardrails and Railroads - Standartlaştırma gücünün bir sınıflandırması; zorunlu-kılma ile teşvik-etme gerilimi için faydalı.