Headless E-Ticaret Nedir? Neden Şimdi?

Geleneksel monolitik sistemler frontend ve backend katmanlarını kilitler. Headless mimari bu bağı koparır. Veri API ile akar, arayüz bağımsız çalışır.

Dijital ajans projelerinde modern web standartları yüksek hız, tam tasarım özgürlüğü ve çoklu kanal desteği gerektirir. Çözüm: Headless stack.

Mimari Seçimi: Shopify Storefront vs MedusaJS

Shopify Storefront API: Altyapı yönetimi sıfır, checkout Shopify güvencesinde, GraphQL tabanlı. SaaS modeli.
MedusaJS: Açık kaynak, Node.js tabanlı, tam veri kontrolü, Postgres/Redis bağımlı. Özelleştirilebilir modüler yapı.

Adım 1: MedusaJS Backend Kurulumu

Terminalde backend sunucusunu başlat:

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

Postgres bağlantısını medusa-config.js içinde doğrula. Sunucu http://localhost:9000 portunda dinler.

Adım 2: Next.js 14+ Frontend Başlatma

App Router ve Tailwind CSS kullanarak frontend oluştur:

npx create-next-app@latest storefront --typescript --tailwind --app
cd storefront
npm i @medusajs/medusa-js

Adım 3: MedusaJS İstemci Yapılandırması

lib/medusa.ts dosyası oluştur:

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

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

Alternatif Adım 3: Shopify Storefront API Entegrasyonu

Shopify kullanılıyorsa GraphQL istemcisi lib/shopify.ts içine eklenir:

const domain = process.env.NEXT_PUBLIC_SHOPIFY_STORE_DOMAIN;
const storefrontAccessToken = process.env.NEXT_PUBLIC_SHOPIFY_STOREFRONT_TOKEN;

export async function shopifyFetch({ query, variables = {} }: { query: string; variables?: Record<string, any> }) {
  const res = await fetch(`https://${domain}/api/2024-01/graphql.json`, {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "X-Shopify-Storefront-Access-Token": storefrontAccessToken!,
    },
    body: JSON.stringify({ query, variables }),
    next: { revalidate: 3600 },
  });
  const json = await res.json();
  if (json.errors) throw new Error(json.errors[0].message);
  return json.data;
}

Adım 4: Ürün Listeleme & Server Components

app/products/page.tsx dosyasında sunucu taraflı veri çekimi:

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

export default async function ProductsPage() {
  const { products } = await medusa.products.list();

  return (
    <main className="max-w-7xl mx-auto p-6">
      <h1 className="text-2xl font-bold mb-6">Ürünler</h1>
      <div className="grid grid-cols-1 md:grid-cols-3 gap-6">
        {products.map((item) => (
          <div key={item.id} className="border p-4 rounded">
            <h2 className="font-semibold">{item.title}</h2>
            <p className="text-gray-600">{item.description}</p>
          </div>
        ))}
      </div>
    </main>
  );
}

Adım 5: Sepet Senkronizasyonu & Checkout

İstemci tarafında sepet ID'si çerezlerde saklanır. MedusaJS Cart API veya Shopify Checkout URL kullanılır.

Not: Shopify Checkout sayfasına harici yönlendirme yapılır. MedusaJS tarafında Stripe entegrasyonu doğrudan Next.js içinde tamamlanabilir.

Performans İpuçları (Dijital Ajans Standartları)

Incremental Static Regeneration (ISR): Ürün sayfalarında revalidate: 60 kullanarak dinamik önbellek yönetimi yapın.
Next.js Image: Görselleri WebP/AVIF formatına otomatik dönüştürün, LCP skorunu düşürün.
Edge Middleware: Coğrafi konuma göre para birimi ve dil yönlendirmesini Edge katmanında çözün.