Tecof temaları Next.js App Router, @tecof/theme-editor ve backend’in /api/store/* katmanı üzerine kuruludur. Tema sayfa JSON’unu backend’den alır, TecofRender ile render eder; panel aynı sayfayı temanın editör rotasında TecofEditor ile düzenletir. Yeni bir tema genelde tecof-theme-core’dan türetilir ve CLI ile geliştirilip yayınlanır.

Tema Runtime Akışı#

sequenceDiagram
    participant Theme as Next.js Theme
    participant StoreAPI as /api/store
    participant Backend as Tecof Backend
    participant Editor as Tecof Editor

    Theme->>StoreAPI: POST /render?themeId&locale
    StoreAPI->>Backend: merchant + theme + slug çözümle
    Backend-->>Theme: publishedData + CMS data
    Theme->>Theme: TecofRender(data, config)
    Editor->>StoreAPI: GET /editor/:pageId
    Editor->>StoreAPI: PUT /editor/:pageId

Diyagram

Tema tarafındaki temel dosyalar:

Dosya	Görev
`lib/api/store.ts`	Sayfa, merchant info ve sayfa listesi fetch fonksiyonları
`lib/api/ecommerce.ts`	Ürün, sepet, checkout, müşteri hesabı ve push API helper'ları
`app/components.tsx`	Tema bileşen registry'si
`app/editor-config.tsx`	Editor config ve component map
`components/RenderClient.tsx`	`TecofRender` sarmalı
`components/global/TecofAnalyticsWrapper.tsx`	Analytics runtime script enjeksiyonu

Zorunlu Ortam Değişkenleri#

.env

NEXT_PUBLIC_BASE_URL=https://api.tecof.com
NEXT_PUBLIC_CDN_URL=https://cdn.tecof.com
NEXT_PUBLIC_MERCHANT_SECRET_KEY=merchant_secret_key
NEXT_PUBLIC_THEME_ID=merchant_theme_id

tecof theme dev bu değerleri mağazanızdan alıp .env.local dosyasına yazar. NEXT_PUBLIC_MERCHANT_SECRET_KEY public bundle içinde yer alır. Bu nedenle canlı storefront için uygundur, fakat editör yazma işlemlerinde tek başına yeterli değildir; backend PUT /api/store/editor/:id için JWT/team doğrulaması da ister.

Tecof Studio entegrasyonu#

Tema üç noktada @tecof/theme-editor kullanır: tüm uygulamayı saran TecofProvider, panelin iframe ile açtığı editör rotası (app/editor/[id]/page.tsx → TecofEditor, ?token= ile gelen JWT accessToken olur) ve yayın sayfalarındaki TecofRender. Kurulum, prop’lar ve örnek kodlar: Tecof Studio’ya giriş.

Bileşen kaydı (registry)#

Her tema bileşeni registry'de bir key ile yayınlanır. Kaydedilmiş sayfa verisindeki content[].type değeri bu key ile eşleşmelidir.

TSX

import { Header } from "@/components/sections/Header";
import { HeroSection } from "@/components/sections/HeroSection";

export const components = {
  Header,
  HeroSection,
};

Bileşen config'i en az şu yapıyı taşımalıdır:

TSX

export const HeroSection = {
  label: "Hero",
  fields: {
    title: { type: "text", label: "Başlık" },
  },
  defaultProps: {
    title: "Yeni başlık",
  },
  // className kök elemana basılmalı; yoksa bileşen editörde seçilemez
  render: (props: any) => <section className={props.className}>{props.title}</section>,
};

Alan tiplerinin tamamı Alanlar, bileşen yapılandırmasının tamamı (defineSection, slotlar, kök className sözleşmesi) Bileşen yapılandırması sayfasındadır.

Public API'ler#

Tema oluştururken verilmesi gereken temel public API yüzeyi:

Amaç	Endpoint
Yayındaki sayfayı render et	`POST /api/store/render?themeId=:themeId&locale=:locale`
Editör için sayfa oku	`GET /api/store/editor/:pageId`
Editör için sayfa kaydet	`PUT /api/store/editor/:pageId`
Merchant dil/logo/script bilgisi	`GET /api/store/merchant-info`
Link alanı için sayfa listesi	`GET /api/store/pages`
Upload	`POST /api/store/upload`
Medya listesi	`GET /api/store/uploads`
Otomatik çeviri	`POST /api/store/translate`
CMS canlı içerik	`POST /api/store/cms/collections/:slug/items`
E-ticaret ürün listesi	`GET /api/store/ecommerce/products`
Checkout session	`POST /api/store/ecommerce/checkout-session`

Tam tablo için Public API Referansı sayfasına bakın.

Analytics Entegrasyonu#

tecof-theme-core, TecofAnalyticsWrapper ile backend’in servis ettiği runtime betiğini yükler (betik ve olay adresi NEXT_PUBLIC_BASE_URL’den türetilir). Aynı işi bir pakette isterseniz @tecof/analytics TecofAnalyticsProvider ve useTecofAnalytics().track() sunar:

TSX

<TecofAnalyticsWrapper merchantId={merchantId} />

Script kaynağı:

Metin

/public/analytics/client.js

Event endpoint'i:

Metin

POST /api/analytics/event

Varsayılan event tipleri pageview, web-vital, cart_add, cart_remove ve checkout_start olarak doğrulanmıştır. Tema bileşenleri sepet ve checkout etkileşimlerinde trackCartAdd, trackCartRemove, trackCheckoutStart helper'larını çağırabilir.

Tema Oluşturma Kontrol Listesi#

NEXT_PUBLIC_BASE_URL, NEXT_PUBLIC_MERCHANT_SECRET_KEY, NEXT_PUBLIC_THEME_ID değerlerini tanımla.
TecofProvider ile app'i sar.
app/components.tsx içinde tüm render edilebilir component key'lerini kaydet.
app/editor-config.tsx içinde component config'i export et.
Dynamic route'larda getPageData(slug, locale, showDraftData) ile /api/store/render çağır.
Public sayfada TecofRender, editör sayfasında TecofEditor kullan; ikisi aynı editorConfig’i paylaşsın ve her bileşen className’i kökte bassın.
E-ticaret componentleri için lib/api/ecommerce.ts helper'larını kullan.
Analytics için TecofAnalyticsWrapper ve checkout event helper'larını ekle.