Headless WordPress: Next.js ile Decoupled Mimari Nasıl Kurulur?

Geleneksel WordPress, hem içerik yönetimini hem de frontend sunumunu tek başına üstlenir. Headless mimaride ise WordPress yalnızca backend CMS olarak çalışır, frontend'i Next.js gibi modern bir framework üstlenir. Sonuç: daha hızlı sayfa yükleme, daha iyi geliştirici deneyimi ve sınırsız frontend esnekliği. Bu rehberde WordPress'i headless CMS olarak yapılandırma, WPGraphQL ile veri çekme ve Next.js ile production-ready bir frontend oluşturma adımlarını ele alıyoruz.

Headless WordPress Nedir?

Headless WordPress, WordPress'in tema katmanını (frontend) devre dışı bırakıp yalnızca REST API veya GraphQL üzerinden içerik sunan bir mimaridir. İçerik editörleri alışık oldukları WordPress admin panelini kullanmaya devam eder; ancak ziyaretçilere sunulan sayfa WordPress tarafından değil, ayrı bir frontend uygulaması tarafından oluşturulur.

WPGraphQL ile Veri Katmanı

WordPress yerleşik REST API sunar ancak GraphQL, frontend geliştirme için daha verimlidir. WPGraphQL eklentisi, WordPress verilerinizi GraphQL endpoint'i üzerinden sunar. Tek bir sorguyla yazı, yazar, kategori ve öne çıkan görseli birlikte çekebilirsiniz - REST API'de bu 3-4 ayrı istek gerektirir.

query GetPosts {
  posts(first: 10, where: { status: PUBLISH }) {
    nodes {
      id
      title
      slug
      excerpt
      date
      featuredImage {
        node {
          sourceUrl
          altText
        }
      }
      author {
        node {
          name
          avatar { url }
        }
      }
      categories {
        nodes { name slug }
      }
    }
  }
}

WPGraphQL Kurulumu ve Yapılandırma

WordPress admin panelinden Eklentiler > Yeni Ekle yolunu izleyerek WPGraphQL'i kurun. Alternatif olarak Composer ile kurulum yapabilirsiniz:

# Composer ile WPGraphQL kurulumu
composer require wp-graphql/wp-graphql

# GraphQL endpoint'i test et
curl -X POST https://cms.example.com/graphql \
  -H "Content-Type: application/json" \
  -d '{"query": "{ generalSettings { title } }"}'

Kurulumdan sonra https://siteniz.com/graphql endpoint'i aktif olur. WordPress admin panelinde GraphQL > Settings bölümünden GraphiQL IDE'yi etkinleştirerek sorguları tarayıcıda test edebilirsiniz. Güvenlik için production ortamında introspection'ı kapatmanız önerilir.

Next.js ile Frontend Kurulumu

Next.js, headless WordPress için en popüler frontend framework'üdür. SSG (Static Site Generation), ISR (Incremental Static Regeneration) ve SSR (Server-Side Rendering) desteği ile hem performans hem SEO açısından güçlü bir kombinasyon sunar. Projeyi oluşturup WordPress'e bağlayalım.

# Next.js projesi olustur
npx create-next-app@latest headless-wp --typescript --app

# GraphQL istemcisi kur
npm install graphql-request graphql

WordPress GraphQL endpoint'ine bağlanmak için bir istemci modülü oluşturun:

import { GraphQLClient, gql } from 'graphql-request';

const client = new GraphQLClient(
  process.env.WORDPRESS_GRAPHQL_ENDPOINT!
);

export async function getAllPosts() {
  const query = gql`
    query AllPosts {
      posts(first: 20, where: { status: PUBLISH }) {
        nodes {
          slug
          title
          excerpt
          date
          featuredImage {
            node { sourceUrl altText }
          }
        }
      }
    }
  `;
  const data = await client.request(query);
  return data.posts.nodes;
}

export async function getPostBySlug(slug: string) {
  const query = gql`
    query PostBySlug($slug: ID!) {
      post(id: $slug, idType: SLUG) {
        title
        content
        date
        author { node { name } }
        categories { nodes { name slug } }
        seo { title metaDesc }
      }
    }
  `;
  const data = await client.request(query, { slug });
  return data.post;
}

Blog Listeleme ve Detay Sayfaları

Next.js App Router ile blog listeleme sayfasını oluşturun. generateStaticParams fonksiyonu build zamanında tüm yazı slug'larını çeker ve statik sayfalar oluşturur:

import { getAllPosts, getPostBySlug } from '@/lib/wordpress';

export async function generateStaticParams() {
  const posts = await getAllPosts();
  return posts.map((post) => ({ slug: post.slug }));
}

export default async function BlogPost({ params }) {
  const post = await getPostBySlug(params.slug);

  return (
    <article>
      <h1>{post.title}</h1>
      <div dangerouslySetInnerHTML={{ __html: post.content }} />
    </article>
  );
}

ISR ve SSG ile Performans Stratejisi

Headless WordPress'in en büyük avantajı, sayfaları build zamanında statik HTML olarak oluşturabilmesidir. Ancak sık güncellenen içerikler için her seferinde yeniden build almak pratik değildir. ISR (Incremental Static Regeneration) bu sorunu çözer: sayfalar statik olarak sunulur, arka planda belirli aralıklarla yeniden oluşturulur.

On-Demand Revalidation ile Anında Güncelleme

WordPress'te bir yazı güncellendiğinde Next.js'e webhook göndererek ilgili sayfayı anında yeniden oluşturabilirsiniz. Bu yöntem, ISR'ın bekleme süresini ortadan kaldırır:

import { revalidatePath } from 'next/cache';
import { NextRequest, NextResponse } from 'next/server';

export async function POST(request: NextRequest) {
  const secret = request.headers.get('x-revalidate-secret');

  if (secret !== process.env.REVALIDATE_SECRET) {
    return NextResponse.json({ error: 'Unauthorized' }, { status: 401 });
  }

  const { slug } = await request.json();
  revalidatePath(`/blog/${slug}`);
  revalidatePath('/blog');

  return NextResponse.json({ revalidated: true });
}

Deployment ve Sunucu Mimarisi

Headless WordPress mimarisinde iki ayrı sunucu bileşeni vardır: WordPress backend (CMS) ve Next.js frontend. Bu bileşenleri aynı sunucuda veya ayrı sunucularda barındırabilirsiniz. Ayrı sunucu yaklaşımı, bağımsız ölçekleme ve güvenlik izolasyonu sağlar.

Next.js uygulamasını production ortamında PM2 ile çalıştırmanızı öneriyoruz. Build ve başlatma komutları:

module.exports = {
  apps: [{
    name: 'headless-wp',
    script: 'node_modules/.bin/next',
    args: 'start',
    instances: 'max',
    exec_mode: 'cluster',
    env: {
      NODE_ENV: 'production',
      PORT: 3000
    }
  }]
};

Sunucu Boyutlandırma Rehberi

Headless WordPress projelerinde sunucu ihtiyacı, trafik hacmine ve içerik miktarına göre değişir. Aşağıdaki tablo farklı ölçekler için önerilen yapılandırmaları gösterir:

Headless mimari için Hosted Cloud bulut sunucuları idealdir. NVMe SSD diskler ve anlık kaynak artırımı ile hem WordPress backend hem Next.js frontend için yüksek performans elde edersiniz. WordPress staging ortamı kurulumu hakkında WordPress Staging rehberimizi inceleyebilirsiniz.

Sıkça Sorulan Sorular

Sonuç

Headless WordPress, içerik yönetiminin gücünü modern frontend teknolojileriyle birleştirir. WPGraphQL ile verimli veri çekimi, Next.js ISR ile statik performans ve on-demand revalidation ile anlık güncelleme sağlarsınız. Bu mimari özellikle yüksek performans hedefleyen, çoklu platform desteği gereken ve özel UI tasarımı isteyen projeler için güçlü bir çözümdür.