Headless E-Ticaret Nedir?

Frontend (sunum katmanı) ile backend (veri/iş mantığı) ayrımı. İletişim GraphQL veya REST API üzerinden yürür. Monolitik CMS kısıtlamalarını kaldırır. Modern web standartlarında maksimum hız ve özelleştirme sağlar.

Teknoloji Karşılaştırması: Shopify vs MedusaJS

Shopify (Storefront API): Yönetilen SaaS backend. Sıfır sunucu bakımı. Yüksek ölçeklenebilirlik. Kısıt: Backend mantığında vendor lock-in.
MedusaJS: Açık kaynak Node.js headless engine. Tam veri mülkiyeti, esnek veritabanı şeması ve modüler eklenti yapısı. Kendi altyapında barındırma gerektirir.
Next.js (Frontend): React Server Components, ISR (Incremental Static Regeneration) ve Edge middleware ile hızlı sayfa yüklemeleri.

Adım Adım Kurulum

1. Backend Hazırlığı

MedusaJS projesi başlatma:

npx create-medusa-app@latest backend --starter default
cd backend
npm run start

Shopify Storefront API için: Partner dashboard üzerinden Custom App oluştur. Storefront API erişim tokenını al (X-Shopify-Storefront-Access-Token).

2. Next.js Frontend Kurulumu

npx create-next-app@latest frontend --typescript --tailwind --app
cd frontend
npm install @medusajs/medusa-js

3. API İstemcisi Yapılandırması

MedusaJS istemci örneği (lib/medusa.ts):

import Medusa from '@medusajs/medusa-js';

export const medusa = new Medusa({
  baseUrl: process.env.NEXT_PUBLIC_MEDUSA_BACKEND_URL || 'http://localhost:9000',
  maxRetries: 3
});

Shopify GraphQL istemcisi için native fetch kullanımı:

export async function shopifyFetch({ query, variables = {} }: { query: string; variables?: Record<string, unknown> }) {
  const res = await fetch(`https://${process.env.SHOPIFY_STORE_DOMAIN}/api/2024-01/graphql.json`, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'X-Shopify-Storefront-Access-Token': process.env.SHOPIFY_STOREFRONT_TOKEN as string,
    },
    body: JSON.stringify({ query, variables }),
    next: { revalidate: 3600 },
  });
  return res.json();
}

4. Ürün Listeleme (RSC Entegrasyonu)

Next.js App Router ile ürünleri sunucu tarafında çekme (app/products/page.tsx):

import { medusa } from '@/lib/medusa';

export default async function ProductsPage() {
  const { products } = await medusa.products.list();
  return (
    <main className="p-8">
      <h1 className="text-2xl font-bold mb-4">Ürünler</h1>
      <div className="grid grid-cols-1 md:grid-cols-3 gap-4">
        {products.map((product) => (
          <div key={product.id} className="border p-4 rounded">
            <h2 className="font-semibold">{product.title}</h2>
          </div>
        ))}
      </div>
    </main>
  );
}

Performans ve SEO Optimizasyonu

ISR Kullanımı: export const revalidate = 60 ile dinamik içerikleri önbelleğe al, veritabanı yükünü düşür.
Next/Image: Otomatik WebP/AVIF dönüşümü ve layout shift önleme.
Edge Caching: Vercel veya Cloudflare arkasında TTFB değerini 50ms altına çek.

Dijital ajans projelerinde headless mimari, müşteriye özel UX sunarken backend operasyonlarını standartlaştırmayı sağlar.