Bir Nav, İki Yığın: Replatforming Yapmadan Magento ve Laravel Arasında Bir Mikrofrontend

Gerçek bir referans implementasyonu, iki üretim seviyesindeki stack üzerinde (Magento 2.4 + Laravel 11) yapılmıştır. Aşağıda gösterilen barındırıcı entegrasyon şekli ve ilk gün gönderilen sunucu tarafından işlenen bir nav iskeleti ile çalışır – GSC paniğinden sonra retrofit edilmemiştir.

TL;DR

Orta ölçekli e-ticaret genellikle tek bir stack üzerinde yaşamaz. Bu endüstrinin yanıtı – “her şeyi tek bir stack üzerine yeniden platformlaştırın” – 100.000 ile 500.000 dolar arasında, 6-12 ay süren bir projedir ve çoğu bu maliyeti karşılayamaz.

Gerçek bir müşteri stack’inde daha küçük bir yanıt gönderdim: hem Magento 2.4 hem de Laravel 11’de bir manifest üzerinden mount edilen 15-20 kb’lık bir Preact mikrofrontend. Bu, bir Modül Federasyonu merhaba-dünyası değildir; iki gerçek ana entegrasyon ile yaklaşık 120 satırlık PHP kodu ve yaklaşık 90 satırlık Laravel kodu, bir pnpm build ile, her iki site de bir dakika içinde güncellenmektedir.

Önemli olan: mikrofrontendler bir ürün mimarisi olarak başarısız oldu ancak onarım stratejisi olarak iş görüyor. Yeni ürün ekipleri koordinasyon maliyetinde boğuluyor. Kültürel miras stackler arasında onarım yapmak, farklı bir problem ve bu desen bunu temiz bir şekilde çözüyor, eğer SEO sözleşmesini gönderimden önce doğru alırsanız.

Ispat noktası kasıtlı olarak somut: özdeş URL’lerde ve kullanıcı ajanlarında bir öncesi/sonrası crawler diffs. Modelleme bir SEO skoru değil, Lighthouse proxy değil, ham HTML gerçekleri – baytlar, bağlantı sayıları ve navigasyonun başlangıç işaretlemesinde mevcut olup olmadığıdır.

Kimsenin açıkça adlandırmadığı problem

Birden fazla markaya sahip orta ölçekli bir e-ticaret grubu ile yıllar içerisinde biriktirilmiş:

• A Magento 2.4 vitrin – katalog, sepet, ödeme.
• A Laravel 11 pazarlama sitesi – marka hikayesi, ödüller programı, editoryal içerik.
• Bir avuç tek amaçlı SPA üstünde.

Her stack’in kendi üst ve alt bilgisi var. Pazarlama yeni bir üst düzey kategori eklediğinde, bu bir stack’te bir haftada, diğerinde ise üç haftada gönderiliyor. Tasarım, logoyu değiştirdiğinde, her şeyde uygulamak iki sprint sürüyor.

Maliyet mühendislik saatleri değil. Maliyet, marka müşterilere görünür bir şekilde tutarsız hale geliyor, ekipler bunu biliyor ve menü üzerine her çapraz takım senkronizasyonu bir saat alıyor.

Neden “sadece bir stack üzerine konsolide ol” yanıt değildir

Standart tavsiye, monorepo veya headless yeniden yazım. Her ikisi de kağıt üzerinde doğru görünse de sahada yanlıştır.

Monorepos, birleşmek isteyen takımları varsayar. Miras takımları – bu stack üzerinde yedi yıl geçirmiş Magento ekipleri, bir edinimle gelen bir Laravel ekibi – birleşmek istemezler. Onların beceri yatırımları, yayın döngüleri ve çağrı döngüleri kendi stack’leri etrafında inşa edilmiştir. Monorepo geçişi, mühendislik öncesinde politik bir projedir ve çoğu orta ölçekli şirket bunu geçiremiyor.

Headless yeniden platformlaştırma da farklı bir kapsamada aynı projedir. On iki aylık bir sürede, üst düzey yönetim onayı ve eski sistemleri güvence altına alacak yeni bir ön uç gerektirir.

Paylaşılan bir nav mikrofrontend, mimari olarak monorepo ile rekabet etmez. Hiçbir şey yapmamayı rekabet eder – belki de organizasyonun gelecek iki yıl boyunca yapacağı budur.

Neden onarım tasarımdan farklıdır

Spotify kamuya açık bir şekilde aşırı takım otonomisini geri aldı. Başarının şekli her zaman aynıdır: takımlar ürün seviyesinde dikey dilimlere sahiptir ve bu dilimler tek bir yüzeyde birleşir, koordinasyon maliyeti patlar, UX tutarsızlığı mimarinin bir özelliği haline gelir.

Bu gerçek bir ders. Hiçbir mikrofrontendin doğru olmayacağı anlamına gelmez.

Onarım, tasarımdan farklı bir problemdir. Yüzeyi inşa etmiyorsunuz – yüzey zaten mevcut, iki uyumsuz uygulama var. Onları görsel olarak hizaya sokan en dar ortak katmanı ekliyorsunuz. Nav tam olarak bu kadar dar: iş mantığı yok, yönlendirme yok, düz bağlantı ağacından başka veri bağımlılıkları yok.

Mikrofrontend eleştirisinin işaret ettiği her şey – tekrar eden çalışma zamanı, parçalanmış UX mülkiyeti, koordinasyon artırımı – 15 kb’lık bir kabuk için geçerli değil (çalışma zamanı ihmal edilebilir) veya mevcut duruma göre daha az geçerlidir (UX zaten parçalı; merkezi karar almayı azaltıyoruz).

Kabuk mimarisi: 15-20 kb, bir derleme, bir dosya

Vite’nin kitaplık modu kullanılarak 15-20 kb boyutunda bir Preact ağacı, tek bir IIFE script ve bir CSS dosyası olarak derlenmiştir, her ikisinin de içerik hash’li dosya adları vardır. Bir manifest.json mantıksal adları hash’li URL’lere eşler.

• Preact, React’a karşı – gzipped ~10 kb, ~45 kb’a karşı. 15-20 kb bütçesi açısından müzakere edilemez.
• IIFE, ES modüllerine karşı – Magento’nun RequireJS ortamında ekstra yapılandırma olmadan çalışır, ve her stack üzerindeki etiketinde.
• cssCodeSplit: false – bir dosya, bir istek, FOUC yok.
• Tailwind, ön ek ile – kapsamlı sınıflar, ana CSS ile çarpışma yok.
• İçerik hash’li URL’ler manifest aracılığıyla – değişmez önbellekleme. Ana barındırıcılar, render zamanında manifesti okur ve ifadesini gönderir.

Ana barındırıcı entegrasyonu: Magento 2.4

• Acme\Theme\Model\SharedNavManifest (~85 satır) – manifesti Magento’nun önbellek arka ucuyla HTTP ile çekiyor, çekim başarısız olursa nav asla kaybolmamakta, yalnızca önbellek aşındırması yaşanmakta.
• Acme\Theme\ViewModel\SharedNavAssets (~26 satır) – phtml şablonlarının konuştuğu ViewModel. CSS, statik layout XML’inden ziyade bir ViewModel aracılığıyla geçiyor çünkü URL içinde bir hash bulunuyor.
• Acme\Theme\etc\frontend\di.xml (~7 satır) – manifest URL’sini dağıtım konfigürasyonuna bağlamak için.

Ana barındırıcı entegrasyonu: Laravel 11

• App\Services\SharedNavManifest (~65 satır) – manifesti HTTP ile çekiyor, Cache::remember('shared_nav.manifest', 60, ...) aracılığıyla önbellekliyor, logluyor ve çekim başarısız olursa hashesiz pakete düşüyor.
• config/services.php – services.shared_nav.manifest_url‘yi çevresel değişken tarafından yönlendirilen konfigürasyon olarak üç satır ile açığa çıkarıyor.
• İki Blade taslağı – kamusal ve daha eski pazarlama sayfaları için ikincil bir taslak – manifest hizmetinden ve etiketlerini yayar.

Temsilî kod şekli (kısıtlı)

class SharedNavManifest
{
    public function getJsUrl(): string
    {
        return '/nav/' . ($this->manifest()['src/main.tsx'][] ?? $this->fallbackJs);
    }

    public function getCssUrl(): string
    {
        return . ($this->manifest()[][] ?? $this->fallbackCss);
    }

    // SSR fallback: fetched once from the shell, cached in Magento's cache
    // backend, and inlined into the mount div at render time.
    public function getHeaderHtml(): string
    {
        return $this->snapshotHtml();
    }

    public function getFooterHtml(): string
    {
        return $this->snapshotHtml();
    }

    private function manifest(): array
    {
        // 1) Read cached manifest
        // 2) on miss, fetch remote manifest URL
        // 3) cache parsed JSON
        // 4) on failure, log and fallback to unhashed asset names
    }

    private function snapshotHtml(string $key): string
    {
        // 1) read cached snapshot for $key
        // 2) on miss, fetch rendered HTML from the shell (e.g. /nav/header.html)
        // 3) cache body with a short TTL
        // 4) on failure, return '' so the shell still hydrates later
    }
}

class SharedNavManifest
{
    public function manifest(): array
    {
        return Cache::remember(, 60, function () {
            // GET config('services.shared_nav.manifest_url'), parse JSON.
            // On failure, log and return [] so fallback filenames kick in.
        });
    }

    public function jsUrl(): string
    {
        return . ($this->manifest()[][] ?? );
    }

    public function cssUrl(): string
    {
        return . ($this->manifest()[][] ?? );
    }

    public function headerHtml(): string
    {
        return $this->snapshotHtml();
    }

    public function footerHtml(): string
    {
        return $this->snapshotHtml();
    }

    private function snapshotHtml(string $key): string
    {
        return Cache::remember({}, 60, function () use ($key) {
            // fetch rendered HTML from the shell (e.g. /nav/header.html)
            // return '' on failure so the shell still hydrates later
        });
    }
}

Ana barındırıcı – shell sözleşmesi

 rel= href=>
 id= style=>{!! $nav->headerHtml() !!}
 id=>{!! $nav->footerHtml() !!} src=>

Shell sağlar:

• Build zamanı itibarıyla yayımlanan bir nav-fallback.html, ana barındırıcı tarafından mount div’lerine yerleştirilen üst ve alt bilgi parçalarına ayrılır (SSR fallback).
• #sa-header ve #sa-footer içine, interaktif ağacı (açılır menüler, mobil menü, durum) ile SSR anlık görüntüsünü değiştiren istemci tarafı montajı.
• Bir CSS dosyası, bir JS dosyası, global kirlilik yok (IIFE kapsamı).
• Magento veya Laravel hakkında hiçbir bilgi yok. Çalışma zamanı yapılandırması, özellik bayrakları yok.

Diğer her şey – yönlendirme, kimlik doğrulama, sepet durumu, ödeme – ana barındırıcıda kalır. Nav, ana barındırıcının var olduğunu bilmez. Ana barındırıcı, nav’ın Preact olduğunu bilmez. Bütün entegrasyon budur.

Başlık montajındaki min-height: 80px ifadesi, anti-CLS sigortasıdır – slot, hidrasyondan önce alanını rezerve eder, böylece Core Web Vitals gecikmeli render için ceza almaz.

SEO sorusu, dürüstçe cevaplandı

Bu, her mikrofrontend gönderisinin atladığı veya gözardı ettiği kısımdır. Ben atlamayacağım.

Ayrıca, bu bölüm kasten gözlemlenebilir crawler gerçeklerine dayanmaktadır, modelleme SEO metrikleri değil. Sentetik bir skordan bir sıralama artışı talep etmiyorum. Bir crawler’ın göndermeden önce ilk HTML’de neyi görebileceğini ve göremeyeceğini gösteriyorum.

Fallback olmadan, başlangıç HTML’i iki boş div’dır:

 id= style=>
 id=>

Googlebot JavaScript’i (biraz gecikmeyle) işler ve nav’ı görür – ama GPTBot, ClaudeBot ve PerplexityBot JavaScript’i işleme yeteneğine sahip değildir. Onlar boş divleri görür. AI aramaları açısından, site nav olmadan kalmaktadır.

Bunu gönderimden önce SSR fallback’i göndermeden ve önce ölçtüm. Üç sayfa, beş kullanıcı ajanı, özdeş curl çağrıları. Aynı URL’ler, aynı tarama yöntemi, aynı ayrıştırma kuralı – tek değişiklik fallback’tı.

SSR fallback’inden önce:

Her sayfa, yapısal olmayan aynı on iki inline gövde bağlantısını açığa çıkardı. Site mape.xml, URL keşfini kapsıyordu; ancak nav’ın keşiften daha öte işler yaptığı dört şey yoktu:

1. Bağlantı seli – çok seviyeli bir nav, kategorilere yönelik sayfada yüzlerce dahili bağlantıdır. Bunu yapmadığınızda, kategori sayfaları otorite kaybeder.
2. Taramaya ayırma bütçesi – Googlebot sayfaları, gelen bağlantı yoğunluğu ile önceliklendirir. Sadece sitemap olan sayfalar daha az taranır.
3. Konu hiyerarşisi – sitemap düz. Nav, anlamsal yapıyı sinyalize eder (“Dükkan -> Erkekler -> Ayakkabılar”).
4. AI yardımcı bağlamı – ChatGPT ve Perplexity, HTML’den zihinsel modeller oluşturur ve genellikle sitemap’ları göz ardı eder. HTML’de nav yoksa, AI URL’lerinizi bilse de yapınızı bilmez.

Üç seviyeli hafifletme merdiveni:

1. fallback, montaj divinin içine kritik bağlantıları yerleştirir (saatlerce çalışma).
2. SSR iskeleti – Vite, build zamanı itibarıyla bir nav-fallback.html yayımlar; ana barındırıcılar bunu hidrasyonun yerini alması için montaj div’lerine dahil eder (bir gün veya iki).
3. Tam SSR servisi – bir Node süreci, her nav isteğini sunucu tarafında işler (bir hafta, ek bir üretim bağımlılığı ile).

Seviye 2, bu boyuttaki bir e-ticaret grubu için tatlı noktadır. İlk üretim sürümünden önce gönderdik. Aynı curl çağrıları, dört gün sonra:

SSR fallback’inden sonra:

Bütün beş kullanıcı ajanı, byte olarak özdeş HTML aldı (tek isteğe özel değişken, Laravel CSRF meta token’ı). Nav ve footer ağacı başlangıç HTML’inde – her sayfa için 100 ek bağlantı, her sayfada değişmez, HTML’yi işleyebilen her crawler için görünür hale geldi.

Bu metodolojik olarak önemli. Bir crawler, SEO etkisi üzerindeki yorumlarım konusunda benimle aynı fikirde olmayabilir; ama 35,050 -> 98,881 bayt veya 12 -> 112 bağlantılar konusundaki aynı tarama koşullarında bana katılmak zorundadır. Bu, yeniden kullanılabilir bir denetim yöntemi, bir kezlik bir anekdot değil.

Serbest bırakma gününde boşluk kapandı. Retroaktif GSC paniği yok, “bir düşüş ölçtük ve işte nasıl düzelttik” anlatısı yok. Dürüst çerçeve, “riski biliyorduk, gönderimden önce kapattık” dır.

Bu makalenin bugün kanıtladığı şeyler – ve henüz kanıtlamadığı neler

Bu makale üç şey kanıtlıyor:

1. Entegrasyon deseni gerçek iki üretim seviyesinde PHP stack üzerinde.
2. SEO riski gerçek eğer shell, yalnızca boş montaj noktaları ile gönderilirse.
3. Seviye 2 fallback, başlangıç gününde o crawler-görünür boşluğu kapatıyor.

Henüz düşündüğüm şey 90 günlük bir iş sonuç hikayesini kanıtlayamıyorum. Bu taslağa bir “üç ay sonra, işte CrUX ve GSC delta tabloları” ekleyemem çünkü bu, yayın sonrası pencerenin olgunlaşmasını gerektirir. Uygulama desenini ve crawler kanıtını dürüst bir şekilde yayınlamak, sahip olmadığım etki sayılarıyla oynamaktan daha iyi.

Bu, bir yapım ve yayımlama vaka çalışması yapar, bitmiş bir büyüme anlatısı değil. Yayın sonrası arama konsolu ve saha performans verileri olgunlaştığında bu bilgileri bir takip makalesinde göstermek gerekir.

Bu biçim neyi çözmüyor

Abartmadan: paylaşılan nav, minimum uygulanabilir ortak yüzeydir – bu, gücü ve tavanıdır.

• Birincil sayfa içeriği hala şaşmaz. Magento ürünleri işliyor; Laravel pazarlama kopyası işliyor.
• Paylaşılan ödeme – çözülmedi. Ödeme Magento’da yaşamaktadır; pazarlama bunun üstüne, ortak bir üst etki alanında çerezler aracılığıyla bağlanmaktadır.
• Paylaşılan kimlik doğrulama – çözülmedi. Çerezler, yönlendirmeler, OAuth el sıkışmaları – her biri ana barındırıcıya özeldir.
• Paylaşılan arama – shell’in üzerine inşa edilebilir, ama biz bunu yapmadık. Arama UX, Magento’ya özgü katalog verilerine bağlıdır.

Paylaşılan bir nav, dağınık bir ön uç stratejisi değildir. İyileştirilmiş bir kırılma üzerinde yarayla kaplı bir bandajdır. Dağınık bir ön uç istiyorsanız, farklı bir mimari gereklidir.

Bu desenin ne zaman uyduğu

Kısa kontrol listesi. Üç kutudan azını işaretliyorsanız, başka bir şey yapın.

• Mevcut iki veya daha fazla stack’iniz var ve gerçekte onları taşımak istemiyorsunuz.
• Şu anda tam bir ön uç birleştirmeye yönelik bütçe veya istek yok.
• Ana ağrı UX tutarsızlığıdır, performans veya mimari borç değildir.
• Üst düzeyde kimsenin “birleşik portal” programını sahiplenmeye istekli olmadığını biliyorsunuz.
• AI ajanı hazır olmalısınız – bu, nav’ın başlangıç HTML’sinde yer alması gerektiği anlamına gelir, yalnızca JS çalıştıktan sonra değil.

Eğer bunların beşi de geçerliyse, desen kendini haftalar içinde öder, çeyrekler içinde değil.

Sonraki adım ne

Aynı shell, aynı gruptaki iki stack’e daha gidecek – yeni bir Magento vitrin yeniden yazımı ve tam bir Laravel pazarlama yeniden yazımı. İkisi de mevcut manifest.json’ı değişmeden tüketecek. Hiçbir ek shell çalışması yok, her ana barındırıcı için aynı entegrasyon izini. Bu, taşınabilirlik kanıtıdır.

Desenin stack’inize uyması durumunda, ilginç tartışma “bir shell nasıl inşa edilir değil” – Vite’nin kütüphane modu belgeleri sizi bir günde oraya götürür. İlginç tartışma, SEO sözleşmesi ve Google Search Console sizi cezalandırmadan önce Seviye 2’yi ilk günde göndermeye yönelik olmalıdır.

Orta ölçekli bir takım için bu genellikle gerçek karar çerçevesidir:

• Seviye 1: linkleri, risk penceresi küçükken ve nav sığ olduğunda.
• Seviye 2: tam bir crawler-görünür yapı için build zamanı SSR fallback’ı, Node servisi eklemeden.
• Seviye 3: nav dinamik olduğunda ve statik yedek HTML bakım problemleri yaratacak kadar karmaşıklaştığında tam bir SSR servisi.

Dışsal bir perspektif genellikle burada faydalıdır ve danışmanlık süremin çoğunu burada harcıyorum.