Micro Frontend

Micro frontend, bağımsız olarak yayınlanabilen frontend uygulamalarının tek bir bütün olarak birleştirildiği mimari stildir.¹ Her ekip kendi dikey dilimini (örneğin sepet sayfasını) fikirden canlıya kadar sahiplenir, kullanıcı ise tek bir ürün görür.¹ Bu rehber önce asıl soruyu cevaplıyor: buna gerçekten ihtiyacınız var mı? Sonra Module Federation ile Vite üzerinde en küçük çalışan kurulumu yapıyor.

Ne zaman gerekir, ne zaman gerekmez?

Micro frontend bir kod organizasyonu aracı değil, bir dağıtım kararıdır. Nx'in ölçütü net: bağımsız deploy zorunluysa kullanın.²

Sadece build süresini kısaltmak istiyorsanız çalışma zamanında birleştirme yanlış araç. Nx bu iş için başka yolları öneriyor.²

Konferans sahnesinde de aynı uyarı var. QCon'da Ruben Casas, karara önce sorunun gerçekten var olup olmadığını sorarak başlamayı öneriyor. Yoksa dağıtık bir mimariye ihtiyacınız yok. Sorun varsa belirtiler genellikle şunlar: kırılgan uygulama, hata izolasyonunun olmaması, yavaş CI/CD ve deploy, ekip sahipliğinin belirsizliği ve zor onboarding.⁴ Micro frontend'in asıl kazancı ekip özerkliği ve pazara çıkış hızı. Performans kazancı değil, dikkatsiz kurulursa performansı kötüleştirebilir.⁴

Bedeli de bilmek gerekiyor:

• Sürüm kayması: Yayınlar atomik değil. Uygulama sürümleri deploy'lar arasında birbirinden ayrışabilir, ekipler arası sözleşmeler derleme zamanı yerine çalışma zamanı anlaşmalarına dönüşür.²

• Tekrar eden yük: Her paket kendi bağımlılık kopyasını getirirse kullanıcı React'i n kez indirir. Bağımlılıkları paylaşmak ise sürüm bağımlılığını geri getirir.¹

• Gizli monolit: Global store veya her şeyi bilen bir kabuk, uygulamaları yine birbirine bağlar. Sonuç, iki yaklaşımın kötü yanlarını birleştiren bir dağıtık monolit olur.³ Casas'ın anlattığı örnekte yaklaşık 70 micro frontend'i olan bir ekibin deploy'u 5 saatin üzerine çıkıyor ve geri alma çok pahalıya geliyor.⁴

• Operasyon yükü: Ayrı deploy'lar CI/CD, feature flag ve sürümleme işini artırır.³

State of Frontend verilerine göre micro frontend kullanımı 2022'de %75,4 iken 2024'te %23,6'ya düştü. Module Federation kullanımı ise 2024'te %51,8'e ulaştı ve çoğu zaman monolitlerin içinde kullanılıyor.³

Önce daha ucuz yolları deneyin

Mimariyi sınıflandıran şey repo, container ya da ekip sayısı değil, parçaların birbirine ne kadar sıkı bağlı olduğu. Her zaman birlikte deploy edilen parçalar fiilen bir monolittir.³ Çoğu küçük ve orta ekip için en hızlı yol, net modül sınırlarına sahip bir modüler monolittir. Gerçek bir ihtiyaç doğduğunda modülü ayırırsınız.³

Casas bunu bir yelpaze olarak çiziyor ve yalnızca sorunun gerektirdiği kadar ilerlemenizi öneriyor:⁴

Sistem yeterince ayrıştırılmışsa yelpazede geri de dönebilirsiniz. Bağımsız deploy beklenenden çok sorun çıkarırsa tekrar entegre uygulamaya çekebilirsiniz.⁴ ByteDance'te Module Federation'ı geliştiren Zack Jackson da aynı yönde: monorepo ile başlayın, federasyon varmış gibi temiz sınırlar koyun, gerekirse sonra bölün. Sınırların karıştığı bir monorepo'yu sonradan bölmek çok zor.⁵ Kaba ölçüsü, federasyonu 10-15 parçaya yaklaştığınızda ciddi düşünmek.⁵

Pratikte basamaklar şöyle:

1. Feature tabanlı klasör yapısı ile sınırları kod içinde çizin.

2. Ortak kodu monorepo içinde paketlere ayırın.

3. Hâlâ bağımsız deploy gerekiyorsa micro frontend'e geçin.

Akademik tarafta 16 çalışmayı tarayan bir araştırma da şirketlerin kavramları, geliştirme yaklaşımlarını ve organizasyonel etkileri bilmedikleri için bu mimariden çekindiğini not ediyor.⁶

Entegrasyon yaklaşımları

Micro frontend'leri birleştirmenin birkaç yolu var:¹

Module Federation bu tablodaki "çalışma zamanında JavaScript" satırına denk gelir: kabuk, uzak uygulamanın modüllerini tarayıcıda çalışırken yükler. Derleme zamanı birleştirmenin kilit adımlı yayın sorunu da böylece ortadan kalkar.

Module Federation kavramları

Module Federation dokümanları iki rol tanımlıyor: bileşen sunan provider ve onu kullanan consumer.⁷ Topluluk ve bu rehber aynı rolleri remote (uzak uygulama) ve host (kabuk) olarak adlandırıyor.

Remote'un giriş noktası mf-manifest.json da olabilir.⁷ Vite eklentisinde manifest: true bu dosyayı da üretir.⁹

Vite ile kurulum

Örnek senaryo: e-ticaret kabuğu (shell, host) sepet widget'ını ayrı bir uygulamadan (cart, remote) yükleyecek. İki uygulama da sıradan birer Vite + React projesi. Monorepo rehberindeki gibi apps/shell ve apps/cart olarak aynı workspace'te durabilirler.

Eklentiyi iki uygulamaya da kurun:⁸

pnpm add -D @module-federation/vite

Bu rehberdeki kurulum Vite 8, React 19 ve @module-federation/vite 1.23 ile hem dev hem build + preview modunda denendi. Eklenti Vite 5, 6, 7 ve 8'i destekliyor.

Remote: sepet

// apps/cart/vite.config.ts
import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'
import { federation } from '@module-federation/vite'

export default defineConfig({
  server: { port: 5174, origin: 'http://localhost:5174' },
  plugins: [
    react(),
    federation({
      name: 'cart',
      filename: 'remoteEntry.js',
      exposes: {
        './CartWidget': './src/cart-widget.tsx',
      },
      shared: {
        react: { singleton: true },
        'react/': { singleton: true },
        'react-dom': { singleton: true },
        'react-dom/': { singleton: true },
      },
    }),
  ],
})

// apps/cart/src/cart-widget.tsx
export default function CartWidget({ count }: { count: number }) {
  return <button>Sepet ({count})</button>
}

Remote'ta server.origin ayarı gerekiyor. Böylece dev sunucusu, dosya adreslerini host'un anlayacağı tam URL ile veriyor.⁹

Host: kabuk

// apps/shell/vite.config.ts
import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'
import { federation } from '@module-federation/vite'

export default defineConfig({
  server: { port: 5173 },
  plugins: [
    react(),
    federation({
      name: 'shell',
      remotes: {
        cart: {
          type: 'module',
          name: 'cart',
          entry: 'http://localhost:5174/remoteEntry.js',
        },
      },
      shared: {
        react: { singleton: true },
        'react/': { singleton: true },
        'react-dom': { singleton: true },
        'react-dom/': { singleton: true },
      },
    }),
  ],
})

Remote'u normal bir dinamik import ile yükleyin. React.lazy ve Suspense, yüklenme durumunu React'e bırakır ve remote bileşeni normal JSX gibi kullanmanızı sağlar.¹⁰

// apps/shell/src/main.tsx
import { lazy, Suspense } from 'react'
import { createRoot } from 'react-dom/client'

const CartWidget = lazy(() => import('cart/CartWidget'))

createRoot(document.getElementById('root')!).render(
  <Suspense fallback="Yükleniyor...">
    <CartWidget count={2} />
  </Suspense>,
)

Çalıştırın: iki uygulamayı da dev ile ayağa kaldırıp localhost:5173 adresini açın. Sepet widget'ı kabuğun içinde görünür.

Tip desteği

Remote'un tipleri olmadan TypeScript cart/CartWidget modülünü bulamaz (TS2307). Module Federation tipleri otomatik üretir ve tüketici uygulama çalışırken bunları indirir. Tüketicinin tsconfig.json dosyasında bu klasörü göstermeniz yeterli:¹¹

// apps/shell/tsconfig.json
{
  "compilerOptions": {
    "paths": { "*": ["./@mf-types/*"] }
  },
  "include": ["src", "@mf-types"]
}

@mf-types üretilmiş bir klasör, .gitignore'a ekleyin. Tipler gelmiyorsa FEDERATION_DEBUG=true ile başlatın ve .mf/typesGenerate.log dosyasına bakın.¹¹

Paylaşılan bağımlılıklar

shared bölümü micro frontend'in en kırılgan noktası. Üç seçenek yeter:¹²

• singleton: true: Paylaşım kapsamında yalnızca tek sürüm yüklenir. Host ve remote farklı sürümler isterse yüksek olan yüklenir, düşük olan taraf konsolda uyarı alır.¹² React gibi tek kopya olması gereken kütüphaneler için bu şart.

• requiredVersion: İstenen sürüm aralığı. Mevcut sürüm bunun altındaysa konsolda uyarı çıkar. Varsayılanı uygulamanın kendi bağımlılık sürümüdür.¹²

• eager: Paylaşılan modülü hemen yükler ama giriş dosyasına gömdüğü için boyutu büyütür, dikkatli kullanın.¹²

Yalnızca gerçekten tek kopya olması gerekenleri paylaşın, örneğin UI framework'ü. Paylaşılmayan kütüphane her uygulamanın bundle'ına girer, paylaşılanlar ise sıkı yönetilmelidir.² 'react/' gibi sonu / ile biten anahtarlar react/jsx-runtime gibi alt yolları da paylaşır.⁸

Dikkat edilecekler

• Remote tipi: Vite ile üretilmiş remote'larda type: 'module' yazın. Yazmazsanız eklenti "var" değerine düşer ve uyarı verir.⁹

• Chunk ayarlarına dokunmayın: Eklenti chunk grafiğini kendisi yönetir. codeSplitting: false yok sayılır, Vite 8 ve sonrasında manualChunks yok sayılır ve uyarı verir.⁹

• Eski tarayıcılar: Chrome 89 altını hedefliyorsanız vite-plugin-top-level-await eklentisini kullanmanız gerekiyor.⁸

• Adresi koda gömmeyin: localhost:5174 yalnızca yerel geliştirme için. Ortama göre değişen bir değişkenden okuyun, aksi hâlde deploy'da adresleri elle değiştirmeniz gerekir.¹⁰ Daha ileri bir kalıp: remote adreslerini build ayarlarına yazmak yerine CI/CD'nin ürettiği, framework'ten bağımsız bir JSON keşif şemasından okumak.¹³ Mezzalira remote bağlantılarını webpack gibi yapılandırma dosyalarına statik gömmeyi üretim için uygun bulmuyor. Keşif şeması CDN ve edge üzerinde canary yayınına (örneğin trafiğin %10'unu yeni sürüme yönlendirmek) ve hızlı geri almaya da olanak tanıyor.¹⁴

• Kaba başlayın: Ekiplere önce büyük alanlar verin, gerekirse sonra bölün. Nadiren değişen alanları çok sayıda micro frontend'e bölmeyin.¹³ Aynı sayfaya çok sayıda küçük parça koymak yerine ilk seviye URL tabanlı yönlendirmeyle (örneğin /katalog) başlamak daha etkili.¹⁴

• Kabuğu ince tutun: Kabuk alandan bağımsız ve kararlı olmalı, uygulama mantığı barındırmamalı.¹³ Yalnızca ilk seviye yönlendirmeden sorumlu, sade bir yapı olarak kalmalı.¹⁵

• Farklı framework'leri uzun süre karıştırmayın: Mezzalira buna "micro frontend anarşisi" diyor. Karışım yalnızca geçici bir geçiş durumu olarak kabul edilebilir.¹⁶ Zack Jackson da çoklu framework'ün düzensizlik getirdiğini söylüyor.⁵

• Erken soyutlama yapmayın: Mezzalira'ya göre ortak kütüphane çoğu zaman yalnızca iki yerde kullanılıyor.¹⁶

• Dinamik remote'larda tip güvenliği zor: Remote'lar çalışma zamanında yüklendiği için statik analiz edilemiyor. ByteDance bunu geliştirme sırasında çalışan bir tip motoruyla çözmüş.⁵

• Deploy sırası: Remote'u yeniden yayınlamak host'u yeniden derlemeden güncel haliyle yükletir.¹⁰ Bu bağımsızlığın bedeli, uyumsuz sürümlerin yalnızca üretimde karşılaşıp hata vermesi olabilir.²

• Sorun yalnızca mimari değil: Sürtüşmenin kaynağı çoğu zaman mimari, mühendislik kültürü ve ekip yapısının uyumsuzluğu. Yalnızca mimariyi değiştirmek sorunları çözmez, ekiplerin karar alma özerkliği de desteklenmeli.¹⁴¹⁵

• CSS izolasyonunu planlayın: Paylaşılan kütüphanelerin (CSS, analitik, UI) çalışma zamanında yüklenmesi riskli. Mezzalira ön ek/son ek kuralları veya Tailwind gibi araçları karışıklığı önlemek için uygun çözümler olarak görüyor.¹⁵

• Yönetişimi otomatikleştirin: CI/CD'ye "fitness function" ekleyin: bundle boyutu bütçesi ve bağımlılık güncellemeleri gibi kontroller. Böylece kod hızla ve güvenle canlıya çıkar.¹⁴¹⁵

• Haberleşmeyi en aza indirin: Uygulamalar arası iletişim gerekiyorsa custom event, yukarıdan geçilen callback veya URL kullanın. Ortak state ve ortak veri modeli ağır bağımlılık yaratır.¹ Mezzalira da global state'ten uzak durup (global state kapsüllemeyi bozar) olay tabanlı iletişimi, geçici veriler için query string, cookie veya API kullanmayı öneriyor.¹³

• Ekibi dikey kesin: Ekipleri stil ya da form gibi teknik kabiliyetlere göre değil, sepet gibi ürün dilimlerine göre kurun.¹

Mevcut uygulamayı parça parça taşımak

Elinizde büyük bir monolit varsa Mezzalira'nın önerdiği yol strangler yaklaşımı: edge compute veya CDN üzerinden istekleri yönlendirin. Taşınan sayfalar yeni micro frontend'e gider, geri kalanı eski monolitte kalır.¹⁶ Önce hedefi (ekip özerkliği, ölçeklenebilirlik, hız) belirleyin, sonra kütüphaneyi seçin. Dikey bir dilimle başlayıp tek bir micro frontend'i tasarım, test, deploy ve gözlemlenebilirlik dahil uçtan uca bitirin.¹⁶ Rollout'u kullanıcı yüzdesi, ülke veya tarayıcıya göre kademeli yapabilir, geri almayı kodu yeniden deploy etmeden dışarıdaki bir yapılandırmayı değiştirerek yapabilirsiniz. Eski ve yeni sayfa arasındaki geçişin tam sayfa yenilemesi gerektirmesi ise bu yaklaşımın en büyük eksisi.¹⁶

Kendin dene

1. Yukarıdaki shell ve cart uygulamalarını oluşturun ve ikisini de dev ile çalıştırın. Sepet widget'ının kabukta göründüğünü doğrulayın.

2. cart içindeki butonun metnini değiştirin. Kabuğu yeniden derlemeden, sayfayı yenileyince güncellendiğini görün.

3. shell içindeki shared ayarından react satırını silip tekrar deneyin. Konsol uyarılarına ve ağ sekmesindeki yüklenen bundle boyutlarına bakın.

4. tsconfig.json'daki paths ayarını kaldırın ve TS2307 hatasını görün. Sonra geri ekleyip hatanın gittiğini doğrulayın.

5. Kendinize sorun: bu uygulamada iki ekibin gerçekten bağımsız deploy etmesi gerekiyor mu? Cevabınız hayırsa bu kurulumu bir modüler monolite çevirin.

6. Mezzalira'nın The Dark Side of Micro-Frontends konuşmasını (29 dk) izleyin ve kendi kurulumunuzdaki anti-pattern'leri işaretleyin.¹³ Ardından Why Your Micro-Frontends are a Distributed Monolith konuşmasıyla karşılaştırın.¹⁴