Headless WordPress migration: %35 hız artışına giden yol

Headless WordPress 2-3 yıldır popüler. WordPress’in content yönetim gücü ile modern frontend’in performansı birleşiyor. Ama headless migration herkesin yaptığı kadar hafif değil. 6 aylık bir migration projesinden öğrendiklerim.

Proje bağlamı

Müşteri: B2C markası, trafiği aylık 1M visitor, WordPress + WooCommerce kombinasyonu. Sorunları:

TTFB yüksek (1.2-1.8s)
Plugin ağırlığı (18 aktif plugin)
Theme çok karmaşık (custom theme 25K LOC)
Mobile Core Web Vitals fena

Tercih: headless migration. WP content’i arka planda, Next.js frontend.

Hedef mimari

[CMS Editor] → WordPress (headless, no theme)
                    ↓ (WP REST API)
               [Next.js frontend]
                    ↓ (ISR/SSG)
                 [CDN edge]
                    ↓
                [End user]

WP sadece content repository. Next.js frontend build-time’da fetch ediyor, static pages generate, ISR (Incremental Static Regeneration) ile periyodik update.

Order/checkout flow yine WP tarafında (WooCommerce), sadece product listing, blog, static pages Next.js tarafında.

İlk aşama: WP’yi hazırlama

WP’nin frontend’ini tamamen kullanmayacağız ama backend hala aktif. Değişiklikler:

1. Custom theme’yi minimal yapın. Frontend render yok, sadece admin ve REST API. wp_head/wp_footer boşaltılıyor, scripts/styles enqueue yapılmıyor.

2. Plugin audit. Frontend’i etkileyen plugin’ler (caching, SEO frontend, UI widget’lar) kaldırılıyor. Backend plugin’ler (ACF, WooCommerce admin, WPML) kalıyor.

3. REST API extensions. Default /wp-json/wp/v2/* endpoint’leri yetmez, custom field’lar exposure gerekiyor.

add_action('rest_api_init', function() {
    register_rest_field('post', 'acf_data', [
        'get_callback' => function($post) {
            return get_fields($post['id']);
        }
    ]);
});

Veya WPGraphQL plugin ile GraphQL endpoint.

4. Preview. Editor draft preview görmek istiyor. Next.js’te preview mode endpoint’i + WP’de “Preview” butonu Next.js URL’ine yönlendiriyor.

REST vs GraphQL

Headless WP’nin iki yaklaşımı:

REST API (built-in):
– Pros: zero setup, default WP feature
– Cons: over-fetching, multiple request gerekiyor, complex field selection yok

WPGraphQL (plugin):
– Pros: single request, field selection, type-safe
– Cons: plugin dependency, öğrenme eğrisi, bazı edge case

Bu projede GraphQL tercih ettim. Frontend 1 request’te sayfanın tüm data’sını alıyor (product + category + related + meta), REST’te 4-5 request olurdu.

Next.js tarafında

Build strategy: SSG + ISR.

Product detail sayfaları build-time’da static generate. Product update olursa ISR ile 60 saniye içinde yenileniyor.

export async function getStaticProps({ params }) {
    const product = await fetchProduct(params.slug);
    return {
        props: { product },
        revalidate: 60  // ISR: 60 saniye
    };
}

export async function getStaticPaths() {
    const slugs = await fetchPopularProductSlugs(1000);
    return {
        paths: slugs.map(slug => ({ params: { slug } })),
        fallback: 'blocking'
    };
}

Popüler 1000 ürün build’de generate, kalanı on-demand fallback.

Image optimization. Next.js component automatic. WP medya library’deki görseller URL ile çağrılıyor, Next.js edge’de resize/optimize yapıyor.

CSS approach. Tailwind + component-scoped CSS. WP theme’in CSS’i hiç taşınmıyor, baştan tasarlanıyor.

Deployment

WordPress VPS’te devam. Next.js Vercel’de (veya kendi host’unda). İki ayrı deployment.

Content update → WP admin → WP REST/GraphQL değişiyor → Next.js ISR revalidation tetikleniyor → CDN cache purge → user refresh edince yeni görüyor.

Revalidation webhook:

add_action('save_post', function($post_id) {
    wp_remote_post('https://nextjs-site.com/api/revalidate', [
        'body' => ['slug' => get_post_field('post_name', $post_id)]
    ]);
});

Next.js endpoint:

export async function POST(request) {
    const { slug } = await request.json();
    await revalidatePath(`/product/${slug}`);
    return Response.json({ revalidated: true });
}

WooCommerce entegrasyonu

WooCommerce checkout Next.js’e taşınmıyor – çok karmaşık, compliance risk. Two-site approach:

Product listing / detail: Next.js
Sepet / checkout / account: WordPress (native WC)
“Add to cart” butonuna basınca WC AJAX endpoint’ine POST, cart fragment update

Deneyim akıcı ama iki sistem tutmak bakım yükü.

Alternatif: Next.js tarafında headless commerce (BigCommerce, Shopify Hydrogen gibi), WooCommerce’ten ayrılmak. Bu proje için çok büyük scope’tu.

Performance: öncesi vs sonrası

Öncesi:
– TTFB: 1.4s average
– LCP p75 (mobile): 3.8s
– CLS p75: 0.15
– Lighthouse Performance: 52

Sonrası (6 ay sonra):
– TTFB: 120ms (CDN edge)
– LCP p75 (mobile): 2.4s
– CLS p75: 0.05
– Lighthouse Performance: 87

LCP %37 iyileşme, TTFB dramatic. Core Web Vitals yeşil.

Migration’ın gizli maliyetleri

1. Dual-system maintenance. WP admin + Next.js frontend iki codebase, iki deployment, iki monitoring.

2. Content editor workflow. Editor’lar Next.js preview’e alışmalı. WP’deki “preview” direkt frontend göstermiyor, Next.js’ten fetch ediyor.

3. Third-party integration. Gravity Forms, newsletter plugin’leri frontend side’ta çalışıyordu, Next.js’e taşınmalı veya API’den çağrılmalı.

4. SEO migration. Yoast’ın output’u Next.js’e manuel taşınmalı. yoast_head_json REST field’ı kullanılıyor ama tüm schema markup migrate etmesi emek.

5. A/B testing, analytics. GTM, Hotjar, Google Analytics setup baştan. Plugin ile olmuyor.

6. Build time. 1000 ürün build 5-10 dakika. CI’da iteration yavaşlıyor. ISR ile production’da çözüldü ama dev experience zayıf.

Ne zaman headless mantıklı değil

Sadece WordPress blog, WooCommerce yok: overkill. WP native + caching yeter.
Dev ekibi sadece 1 PHP developer: frontend stack öğrenmek ek yük.
Trafik az (aylık <100K visitor): performance kazancı marginal.
Content editor workflow değişmesinden rahatsız: risk.
Plugin-heavy site (20+ frontend plugin): hepsi migrate edilmeli veya terk edilmeli.

Ne zaman headless mantıklı

Performance kritik (ecommerce, news, high-traffic)
Dev ekibi React/Next.js seviyor
Rich frontend interactivity gerekli (app-like UX)
A/B testing, personalization yoğun
Multi-channel (web + mobil app aynı API)

6 ay sonraki değerlendirme

Müşteri memnun. Performance iyileşti, conversion rate %8 arttı, mobile bounce %15 azaldı.

Ama bakım yükü arttı: dev team Next.js dev + WP dev seti lazım. Küçük içerik değişiklikleri hala kolay (WP admin) ama feature development iki yerde.

2 milyon TRY civarında implementation cost, migration süresi 6 ay. ROI 18 ay projection’ında pozitif.

Son tavsiye

Headless WordPress “silver bullet” değil. Hype’a uyarak migrate etmek risk. Önce şunu sor:

Traditional WP optimization’ı zorladın mı? (caching, CDN, plugin audit)
Frontend dev kapasitesi var mı?
Bakım yükü artışını taşıyabilecek misin?

Cevaplar “evet” ise headless anlamlı. Değilse traditional WP + proper optimization çoğu case’te yeterli. %35 iyileşme için 6 ay + 2M TRY yatırım her proje için anlamlı değil.