Next.js App Router Entegrasyonu

@copypatch/next paketi, CopyPatch v2'yi Next.js App Router (React Server Components) ile doğrudan entegre eder. Same-origin rota işleyicilerini sağlar ve sunucu tarafı render sırasında doğrudan veritabanından yayınlanmış metinleri okur.

1. Paylaşılan Backend Singleton Nesnesini Tanımlayın

Kalıcılık adaptörünü ve CopyPatch backend çalışma zamanını başlatan bir sunucu modülü oluşturun:

// lib/copypatch.ts
import { createCopyPatchBackend } from '@copypatch/backend';
import { createSQLitePersistence } from '@copypatch/storage-sqlite';

const persistence = createSQLitePersistence('./data/copypatch.sqlite');
await persistence.migrate();

export const copypatch = createCopyPatchBackend({
  persistence,
  passphraseHash: process.env.COPYPATCH_PASSPHRASE_HASH!,
});

2. Same-Origin Rota İşleyicisini (Route Handler) Mount Edin

app/%5F%5Fcopypatch/api/v2/[...path]/route.ts dosya yolunda catch-all bir rota işleyicisi oluşturun:

// app/%5F%5Fcopypatch/api/v2/[...path]/route.ts
import { createCopyPatchRouteHandlers } from '@copypatch/next/server';
import { copypatch } from '@/lib/copypatch';

export const { GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS } =
  createCopyPatchRouteHandlers(copypatch, {
    // İsteğe bağlı: oturum çözümleme veya hız sınırlaması için istemci IP'si alma
    resolveContext: async (request) => ({
      clientAddress: request.headers.get('x-forwarded-for')?.split(',')[0].trim(),
    }),
  });

Neden %5F%5Fcopypatch? Next.js dosya sisteminde alt çizgi ile başlayan klasörleri (örn. _copypatch) özel (private) kabul eder ve bunları URL yönlendirmesinden hariç tutar. Alt çizgileri yüzde kodlamasıyla (URL percent-encoding) %5F%5Fcopypatch olarak adlandırarak, Next.js'in standart genel /__copypatch/api/v2/... yolunu sorunsuz sunması sağlanır.

3. Sunucu Bileşenlerinde Önceden Render Etme (SSR/RSC)

Sayfa veya Sunucu Bileşenlerinizde readPublishedSnapshot() fonksiyonunu çağırın. Bu fonksiyon dahili bir HTTP isteği yapmadan doğrudan depolama katmanından okuma yapar ve anlık görüntüyü NextCopyPatchProvider sağlayıcısına aktarır:

// app/[locale]/page.tsx
import { NextCopyPatchProvider, EditableText } from '@copypatch/next';
import { readPublishedSnapshot } from '@copypatch/next/server';
import { copypatch } from '@/lib/copypatch';

export default async function Page({
  params,
}: {
  params: Promise<{ locale: string }>;
}) {
  const { locale } = await params;

  // Sunucu Bileşeni içinde doğrudan veritabanı okuması (Sıfır HTTP gecikmesi)
  const initialSnapshot = await readPublishedSnapshot(copypatch, locale, {
    fallback: { 'home.hero.title': 'Platformumuza Hoş Geldiniz' },
  });

  return (
    <NextCopyPatchProvider locale={locale} initialSnapshot={initialSnapshot}>
      <main className="container">
        <EditableText contentKey="home.hero.title" as="h1">
          Platformumuza Hoş Geldiniz
        </EditableText>
      </main>
    </NextCopyPatchProvider>
  );
}

Next.js Entegrasyonunun Avantajları

• Sıfır Yerleşim Kayması (Zero Layout Shift): Metinler sunucu tarafında oluşturulan ilk HTML yanıtına gömülür.
• Sıfır HTTP Ek Yükü: Sunucu bileşeni localhost adresine istek göndermeden doğrudan bellek veya veritabanı havuzundan okur.
• Proxy veya Rewrite İhtiyacı Yok: Rota doğrudan Next.js uygulamanızın içinde yaşadığı için next.config.js içinde karmaşık yönlendirme kuralları gerekmez.

Statik Dışa Aktarma (Static Export) Uyarısı

Önemli: CopyPatch bir sunucu çalışma zamanı (Node.js veya serverless/edge) gerektirir. Next.js projeniz output: 'export' olarak yapılandırılmışsa, dinamik düzenleme API'si ve veritabanı bağlantısı çalıştırılamaz.