{ "title": "Headless E-Ticaret Kurulum Rehberi: Next.js, MedusaJS ve Shopify ile Modern Web", "slug": "headless-e-ticaret-nextjs-medusajs-shopify-rehberi", "summary": "Next.js frontend, MedusaJS ve Shopify backend kullanarak modern headless e-ticaret altyapısı kurma rehberi. Dijital ajanslar ve geliştiriciler için mimari adımlar.", "content": "

Headless E-Ticaret Mimarisi Nedir?

Geleneksel e-ticaret platformları frontend ve backend katmanlarını sıkı sıkıya bağlar. Headless e-ticaret mimarisinde arayüz (sunum katmanı) veri ve iş mantığından (backend/veritabanı) tamamen ayrılır. İletişim REST veya GraphQL API üzerinden yürür. Modern web standartlarında bu yaklaşım; yüksek hız, tam tasarım esnekliği ve platform bağımsızlığı sağlar.

Trendler, monolitik yapıların yerini API-first ve edge-rendered mimarilerin aldığını gösteriyor. Dijital ajans ekipleri için headless altyapı, standart temalara mahkûm kalmadan özel müşteri deneyimleri tasarlamanın en hızlı yoludur.

Hangi Backend? MedusaJS vs Shopify Storefront

Shopify Storefront API: Güvenli ödeme altyapısı, hazır vergi/kargo motoru, sıfır sunucu bakımı. SaaS modeli.
MedusaJS: Açık kaynak, tam kod kontrolü, Node.js tabanlı, sıfır lisans maliyeti, özelleştirilebilir veritabanı. Self-hosted.

Adım 1: Next.js Frontend Projesini Başlatma

Frontend için modern web standardı: Next.js (App Router). Kurulum komutu:

npx create-next-app@latest store-front --typescript --tailwind --app --src-dir --no-eslint

Adım 2: API İstemcisini Yapılandırma

Gereksiz bağımlılık ekleme. Veri çekme işlemini yerel fetch ile yürüt.

Seçenek A: Shopify Storefront GraphQL API

src/lib/shopify.ts dosyasını oluştur:

const domain = process.env.SHOPIFY_STORE_DOMAIN;
const token = process.env.SHOPIFY_STOREFRONT_ACCESS_TOKEN;

export async function shopifyFetch({ query, variables = {} }: { query: string; variables?: Record<string, unknown> }) {
  const res = await fetch(`https://${domain}/api/2024-01/graphql.json`, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'X-Shopify-Storefront-Access-Token': token!,
    },
    body: JSON.stringify({ query, variables }),
    next: { revalidate: 3600 } // ISR: Saatlik önbellek yenileme
  });

  const json = await res.json();
  if (json.errors) throw new Error(json.errors[0].message);
  return json.data;
}

Seçenek B: MedusaJS REST API

MedusaJS için src/lib/medusa.ts:

const MEDUSA_URL = process.env.NEXT_PUBLIC_MEDUSA_BACKEND_URL || 'http://localhost:9000';

export async function medusaFetch({ endpoint, next }: { endpoint: string; next?: NextFetchRequestConfig }) {
  const res = await fetch(`${MEDUSA_URL}/store${endpoint}`, {
    headers: { 'Content-Type': 'application/json' },
    next: next || { revalidate: 60 }
  });
  if (!res.ok) throw new Error(`Medusa fetch hatasi: ${res.statusText}`);
  return res.json();
}

Adım 3: Ürün Listeleme (Server Component)

Next.js Server Component kullanarak ürünleri edge üzerinde işle. İstemciye sıfır JavaScript yükü bindir.

src/app/page.tsx:

import { shopifyFetch } from '@/lib/shopify';

const PRODUCTS_QUERY = `
  query GetProducts {
    products(first: 10) {
      edges {
        node {
          id
          title
          handle
          priceRange {
            minVariantPrice {
              amount
              currencyCode
            }
          }
        }
      }
    }
  }
`;

export default async function HomePage() {
  const data = await shopifyFetch({ query: PRODUCTS_QUERY });
  const products = data.products.edges;

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

Adım 4: Sepet Yönetimi ve State Stratejisi

Sepet işlemleri için cookies veya localStorage üzerinden ID sakla, mutasyonları Server Actions ile yürüt:

Oturum: Ziyaretçi ilk ürün eklediğinde API üzerinden sepet oluştur (cartCreate).
Kimlik Saklama: cart_id değerini HTTP-only cookie içine yaz.
Ödeme: Checkout aşamasında Shopify Hosted Checkout veya Medusa Stripe modülüne yönlendir.

Performans ve SEO için Pratik İpuçları

Görsel Optimizasyonu: next/image bileşenini harici CDN domain tanımlarıyla (Shopify CDN / S3) zorunlu kullan.
Önbellek (Cache) Katmanı: Ürün detay sayfalarında generateStaticParams kullanarak statik sayfalar üret (SSG). Stok değişimlerinde revalidateTag() ile anlık temizle (On-demand ISR).
Core Web Vitals: Harici izleme scriptlerini (Google Tag Manager, Meta Pixel) next/script ile strategy="lazyOnload" veya Web Worker üzerinde (Partytown) çalıştır.

", "schema_type": "HowTo", "suggested_tags": [ "rehber", "trendler", "dijital ajans", "modern web", "headless e-ticaret", "nextjs", "medusajs", "shopify" ] }