Nuvi ile geliştir

Nuvi, dakikalar içinde şık ve production'a hazır bir mağazayı çalışır hale getirmek üzere kurgulandı (domain/DNS daha uzun sürebilir). Beş adım:

1. Kaydol usenuvi.com/register — e-posta + parola, kart yok.
2. Tema seç. Her tema örnek ürünler ve 8–12 önceden yapılandırılmış bölümle gelir. İçeriğini kaybetmeden istediğin zaman tema değiştirebilirsin.
3. Domain bağla (opsiyonel ama önerilir). Panelden ara ya da elindeki domaini yapıştır — DNS otomatik kurulabilir; SSL genellikle dakikalar içinde inişer.
4. Stripe ya da Iyzico bağla. Tek tıkla OAuth ya da Nuvi üzerinden taze merchant hesabı aç.
5. Hero'nu düzenle Tema Editöründe — yeni bölüm sürükle, başlığı değiştir, renkleri ayarla. Yayınla'ya bas.

Hepsi bu. Artık checkout, müşteri hesabı, blog ve AI asistanlı tam çalışan bir mağazan var.

Nuvi dört kavramsal katmandan oluşur. Aralarındaki ilişkiyi anlamak her şeyi kolaylaştırır:

Modüller

Platformun yetenekleri: blog, sayfa, teklif, arama, tema, para birimi, vs. 22 tane var, her planda dahil. Modül = bir yetenek için veri + API + admin UI. Modülleri kurmazsın ya da yapılandırmazsın — her zaman açıklar.

Temalar

Mağazanın görünüşü. Tema; tasarım token'larını (renk, font, boşluk), bölüm tanımlarını ve varsayılan ayarları paketler. Tema değiştirmek içeriği kaybetmeden görünümü değiştirir.

Bölümler

Birleştirilebilir görsel bloklar: hero, özellik grid'i, fiyat, referanslar, SSS, CTA. Her bölüm içeriğini JSON ayarlarından okuyan bir React komponenti. Editör üzerinden sürükleyip sıralarsın.

Sayfalar

Storefront'undaki rotalar. Ana sayfa, ürün detayı, blog yazısı ve özel sayfalar (hakkında, kariyer vs.) sayfadır. Sayfa = bölüm listesi + içerik verisi (başlık, slug, SEO meta). Sayfalar page modülünde tutulur.

Her modül bağımsız bir NPM paketidir — @nuvi/module-blog, @nuvi/module-quote, vs. packages/modules/ altında yaşarlar; kendi veri modeli, servis sınıfı, manifest ve admin route'ları ile gelirler.

Modüller standartları paylaşır ama bağımsızdır: birini etkinleştirmek/kapatmak (module-setting üzerinden) diğerlerini bozmaz. Çoğu modülün sıkı bağımlılığı yoktur; olanlar bunu manifest.json'da belirtir.

Yaşam döngüsü

Platform boot olduğunda module loader ENABLED_MODULES env değişkenini okur, her modülün MikroORM entity'lerini kaydeder, admin ve storefront API route'larını mount eder ve servis sınıfını cross-module çağrılar için açar.

Cross-module çağrılar

Bir modül başka modülün servisini Medusa container üzerinden çağırabilir; örn. quote modülü page modülünden veri okuyup template render eder. HTTP atlama yok — servisler DI container'ından çözülen JS sınıfları.

Üç kimlik bağlamı ile çalışırsın:

Publishable API anahtarı

Her storefront isteğinde x-publishable-api-key olarak gönderilir. Çağrının hangi mağaza / bölgeye ait olduğunu belirler; istemci kodda paylaşmak güvenli. Her site için otomatik oluşturulur — Panel'inde bulabilirsin.

Müşteri JWT

POST /auth/customer/emailpass ile alınır. Giriş yapmış alıcıyı tanımlar. /store/customers/me, /store/orders/me, /store/subscriptions uçları için gerekli. Authorization: Bearer ... olarak gönder.

Admin token

Sunucu tarafı admin araçları ve entegrasyonlar için. İstemci kodda asla paylaşma. Sadece kendi backend'inden ya da CLI'dan kullan.

curl https://usenuvi.com/api/store/customers/me \
  -H "x-publishable-api-key: pk_live_..." \
  -H "Authorization: Bearer <customer-jwt>"

Modüller packages/modules/<ad>/ altında bağımsız NPM paketleridir. En temiz referans @nuvi/module-blog — şekli kopyala, adı değiştir. Minimum beş dosya yeterli.

1. Paket düzeni

packages/modules/loyalty/
├── manifest.json              # metadata, bağımlılık, route
├── package.json               # "main": "./src/index.ts"
├── tsconfig.json
└── src/
    ├── index.ts               # modül + servis + model re-export
    └── module/
        ├── index.ts           # Module() kaydı
        ├── service.ts         # MedusaService sınıfı
        └── models/
            └── loyalty-account.ts

2. manifest.json

@nuvi/module-sdk'nin validateManifest()'i tarafından okunur. Alanlar: name, version, displayName, description, icon, category, isCore, dependencies (diğer modül paket adları) ve modules, adminRoutes, apiRoutes bildiren bir medusa bloğu.

3. MikroORM modeli

Medusa'nın model.define() DSL'ini kullan. Multi-tenant izolasyon için store_id'yi her zaman koy ve indexle:

import { model } from "@medusajs/framework/utils"

const LoyaltyAccount = model.define("loyalty_account", {
  id: model.id().primaryKey(),
  store_id: model.text().default("default").searchable(),
  customer_id: model.text(),
  points: model.number().default(0),
}).indexes([{ on: ["store_id", "customer_id"], unique: true }])

export default LoyaltyAccount

4. Servis sınıfı

service.ts her modeli MedusaService({...}) ile genişletir — CRUD metodları (listLoyaltyAccounts, createLoyaltyAccounts, …) bedava gelir. module/index.ts bunu Module("loyalty", { service }) ile sarar ve LOYALTY_MODULE = "loyalty" sabitini export eder.

5. Bağla

1. bootstrap/medusa/package.json'a ekle: "@nuvi/module-loyalty": "file:../../packages/modules/loyalty".
2. bootstrap/medusa/src/lib/module-registry.ts'a resolve, key, frontendId, apiRoutes, adminRoutes, isCore ile kaydet.
3. Cross-module çağrı için bootstrap/medusa/src/types/module-services.ts'a tipli arayüz ekle.
4. Yeniden kur: cd bootstrap && docker compose up -d --build medusa.

En hızlı yol: Panel → Ürünler → Yeni ürün. Dolduracağın alanlar:

• Başlık + handle. Handle URL slug olur (/products/your-handle).
• Açıklama. Görsel gömme destekli rich-text editör. PDP'de olduğu gibi render olur.
• Varyantlar. Ürünün seçenekleri varsa (boy, renk) varyant satırları olarak ekle. Her varyantın kendi fiyatı ve SKU'su var.
• Görseller. Sürükle-bırak yükleme. İlk görsel kapak olur; sürükle ile sırala.
• SEO. Opsiyonel meta başlık + açıklama. Boşsa ürün başlığı + ilk 160 karakter açıklamaya düşer.

Yayınla'ya bas. Ürün https://magazan.com/products/your-handle'de saniyeler ila birkaç dakika içinde canlı — Next.js sayfayı statik olarak regenerate eder.

İki yol var:

Nuvi üzerinden satın al

Panel → Domain'ler'de domain ara. 500+ TLD arasından seç. Yıllık $15–30 (fiyatlara bak). Ödeme onaylandıktan sonra DNS otomatik kurulabilir; SSL genellikle dakikalar içinde inişer.

Kendi domainini getir

Zaten başka yerde domainin var mı? Aynı ekrandan ekle. Registrar'ında eklemen gereken CNAME / A kayıtlarını gösteririz. Yayılma tamamlanınca (genellikle 10–30 dk) SSL otomatik kurulur.

Başka platformdan taşınıyorsan, Redirect modülü eski URL'lerine 301 önceden üretir; SEO değeri yeni URL'lere akar.

Kendi domain'inde profesyonel e-posta ([email protected]) — 15 GB alan, tam IMAP/SMTP/POP3, webmail, takvim & kişiler.

1. Mailbox oluştur

Panel → Ayarlar → E-posta'dan domain'ini ekle ve mailbox oluştur. Mailbox $5/ay ek hizmettir (hizmete bak). DNS kayıtları (MX, SPF, DKIM, DMARC) Nuvi-yönetilen domain'lerde otomatik eklenir; harici domain'de registrar'ına yapıştıracağın kayıtları gösteririz.

2. Webmail

mail.usenuvi.com'u aç ve tam e-posta adresin + şifrenle giriş yap. Webmail'de mail, takvim, kişiler, filtreler ve spam kontrolü var.

3. Kendi uygulamana bağla

Apple Mail, Outlook, Gmail ya da telefonunun mail uygulamasını mı tercih ediyorsun? Şu ayarları kullan:

Sunucu:   mail.op-email.eu
Port:     993
Güvenlik: SSL/TLS
Kullanıcı: [email protected]
Şifre:    mailbox şifren

Sunucu:   mail.op-email.eu
Port:     587
Güvenlik: STARTTLS
Kullanıcı: [email protected]
Şifre:    mailbox şifren

iPhone / iPad: Ayarlar → Mail → Hesaplar → Hesap Ekle → Diğer → Posta Hesabı Ekle, sonra yukarıdaki değerleri gir. Apple Mail / Outlook / Gmail app / Android: "Diğer" / "IMAP" seç, aynı ayarları kullan. POP3 da 995 (SSL) portunda mevcut.

4. Şifre, 2FA & alias

Mailbox panelinden şifreni değiştir, iki adımlı doğrulamayı aç ya da uygulama-başı şifre oluştur. Alias'lar (örn. satis@ → gelen kutun) ücretsiz — Ayarlar → E-posta → Yönlendirme'den ekle.

Panelden Tema Editörü'nü aç. Genelden özele üç katman özelleştirme:

1. Token'lar (site geneli)

Vurgu rengini, font ailesini, köşe yuvarlamayı değiştir. var(--color-primary) kullanan her bölüm anında güncellenir. Inspector'da bir renge tıkla ya da hex yapıştır.

2. Bölümler (sayfa bazlı)

Her sayfa bir bölüm yığınıdır. Sol panelden yeni bölüm sürükle; sırayla taşı; satır menüsünden çoğalt ya da gizle. Bölümlerin kendi ayarları var (başlık, görsel, hizalama, vs.).

3. Bölüm ayarları (bölüm bazlı)

Bölüme tıkla, inspector açılsın. Başlığı düzenle, görsel değiştir, padding ayarla. Canlı önizleme yazdıkça güncellenir. Değişiklikler taslak olarak otomatik kaydedilir; Yayınla'ya basınca canlıya gider.

Bugün: yerleşik workflow'lar

Her Nuvi tenant'ı gömülü bir workflow motoru ile gelir. Panel → Workflows (admin route: bootstrap/medusa/src/admin/routes/workflows/) altında açılır. Bir Nuvi trigger'ı seç — sipariş oluştu, ödeme alındı, müşteri oluştu, teklif gönderildi — ve action bloklarından birini bağla (HTTP, Slack, Sheets, özel kod).

Arka planda workflow motoru, ileride outbound webhook'ları besleyecek aynı Medusa event bus'ına abone olur — bugün kurduğun akışlar gerçek webhook çıkışı şipşırlanınca da çalışmaya devam eder.

Yarın: imzalı outbound webhook'lar

Planlanan event'ler:

• order.placed — sepet siparişe dönüşür.
• order.payment_captured — ödeme alındı.
• order.fulfilment_shipped — hazırlama kargolandı.
• customer.created, subscription.renewed, quote.submitted.

Her teslimat x-nuvi-signature header'ı taşıyacak — endpoint'inin imza secret'ı ile raw body'nin HMAC-SHA256'sı. Node.js alıcısında doğrulama:

import crypto from 'node:crypto'

export function verifyNuviSignature(rawBody: Buffer, header: string, secret: string) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(rawBody)
    .digest('hex')
  // Yanıt süresinden sızdırmamak için timingSafeEqual kullan
  const a = Buffer.from(expected, 'hex')
  const b = Buffer.from(header, 'hex')
  return a.length === b.length && crypto.timingSafeEqual(a, b)
}

Nuvi, Medusa v2'nin payment provider plugin modelini miras alır. Repo iki örnek taşır — Stripe (resmi @medusajs/payment-stripe) ve iyzico (bootstrap/medusa/src/modules/iyzico-payment/ içinde). Yeni bir sağlayıcı eklerken iyzico'yu kopyala.

1. Modül şekli

Provider, payment modülüne kayıtlı bir Medusa module provider'ıdır:

import { ModuleProvider, Modules } from "@medusajs/framework/utils"
import MyProvService from "./service"

export default ModuleProvider(Modules.PAYMENT, {
  services: [MyProvService],
})

2. Yaşam döngüsü metodları

AbstractPaymentProvider<Options>'i bir static identifier ile genişlet ve checkout sırasında Medusa'nın çağırdığı metodları yaz:

• initiatePayment — gateway'inle session aç, token / redirect URL döndür.
• authorizePayment — geri dönen token'ı doğrula (redirect / 3DS sonrası).
• capturePayment — yetkili tahsilatı sonlandır.
• refundPayment — tam ya da kısmi iade.
• retrievePayment / getPaymentStatus — mevcut durumu oku.
• cancelPayment, deletePayment, updatePayment — bitmemiş oturumlar için bakım.

3. 3DS / redirect callback

Hosted-page sağlayıcılar (iyzico, PayTR, Mollie) redirect sonrası token doğrulamak için public callback ister. Kalıp bootstrap/medusa/src/api/store/iyzico-callback/route.ts'de: token formatını doğrula, beklenen cart'a ait olduğunu kontrol et, sonra sağlayıcının retrieve API'sini çağır.

4. medusa-config'e kaydet

bootstrap/medusa/medusa-config.ts'teki @medusajs/medusa/payment providers array'ine, sağlayıcının yapılandırıldığını gösteren env'e bağlı koşullu bir giriş ekle. iyzico çalışan bir şablon:

...(process.env.MYPROV_API_KEY ? [{
  resolve: "./src/modules/myprov-payment",
  id: "myprov",
  options: {
    apiKey: process.env.MYPROV_API_KEY,
    secretKey: process.env.MYPROV_SECRET_KEY || "",
  },
}] : []),

5. Test

Stripe için Stripe CLI: stripe listen --forward-to localhost:9000/hooks/payment/stripe. iyzico için IYZICO_URI'yi https://sandbox-api.iyzipay.com'a yönlendir. Tam akışı storefront cart sayfasından sür — authorize → capture → fulfilment hepsinin döndüğünü gör.

Import modülü Shopify export'unu okur ve her şeyi içeri çeker. Adımlar:

1. Shopify'dan export al: Ayarlar → Hesap → Mağaza verisini dışa aktar (ya da ürünler için Storefront API'yi, siparişler için Admin API'yi kullan).
2. Nuvi'de: Panel → Import → Yeni import → Shopify. Dosyayı yükle ya da doğrudan çekme için API bilgilerini yapıştır.
3. Alan eşleştirmesi otomatik. Önizlemeyi gözden geçir, çakışmaları (örn. tekrarlayan handle'lar) düzelt.
4. Import'u çalıştır'a bas. Ürünler, varyantlar, müşteriler ve siparişler import edilir. Medya Nuvi storage'a yeniden yüklenir.
5. Redirect modülü eski Shopify URL'lerinden otomatik 301 üretir (/products/foo → Nuvi'de aynı path) — SEO korunur.

Yardım gerekir mi? Premium Destek birebir geçiş yardımı içerir.

WooCommerce geçişi Shopify ile aynı şekilde ilerler, bir farkla: WordPress hem storefront'u hem blog içeriğini barındırır, ikisini de import edersin.

1. WordPress admin'den Customer / Order / Coupon export eklentisini kur ve tam export çalıştır.
2. Blog yazılarını WP REST API ile çek: /wp-json/wp/v2/posts.
3. Nuvi'de: Panel → Import → Yeni import → WooCommerce. Her iki dosyayı yükle.
4. Import çalıştır. Ürün + siparişler ticarete; yazılar yazar + kategori korunarak Blog modülüne gider.
5. Hem /product/slug hem /blog/slug kalıpları için redirect'ler otomatik üretilir.

Bootstrap konfigürasyonunu bootstrap/.env'deki tek bir dosyadan okur — bootstrap/.env.example'tan kopyalanır. docker-compose.yml değerleri otomatik alır ve her servise geçirir.

Çekirdek (her zaman zorunlu)

• POSTGRES_USER, POSTGRES_PASSWORD, POSTGRES_DB_MEDUSA — veritabanı bağlantısı.
• MEDUSA_JWT_SECRET, MEDUSA_COOKIE_SECRET — auth secret'ları. Dev dahil her ortamda zorunlu.
• STORE_CORS, ADMIN_CORS, AUTH_CORS — Medusa'nın izin verdiği virgülle ayrılmış origin'ler.
• REDIS_PASSWORD — cache + kuyruk.
• NUVI_INTERNAL_TOKEN + INTERNAL_API_KEY — servisler arasında eşleşmeli.

Nesne depolama (Hetzner)

S3_ACCESS_KEY_ID, S3_SECRET_ACCESS_KEY, S3_BUCKET, S3_FILE_URL. Bucket ürün medyası + tema varlıklarını taşır; S3_FILE_URL, Medusa'nın image yanıtlarında ürettiği public URL önekidir.

Modüller

ENABLED_MODULES, boot edecek modül paket adlarının virgülle ayrılmış listesi. Boş bırakılırsa tüm modüller yüklenir. Çekirdek modüller (theme, page, module-setting) yazmasan da her zaman yüklenir.

ENABLED_MODULES=@nuvi/module-blog,@nuvi/module-quote,@nuvi/module-media,@nuvi/module-form

Production vs development

Aynı değişkenler, farklı kaynaklar. Dev'de bootstrap/.env düz metin — lokal için sorun değil. Production'da:

• Sunucudaki deploy.sh repo dışında yönetilen bir .env tutar ve docker compose up'a bağlar.
• Tenant başına override'lar (Stripe key, OAuth token, GA ID) OPS_ENCRYPTION_KEY (Fernet key) ile şifrelenip control plane tarafından saklanır, her tenant container'ı başlarken runtime'da enjekte edilir.
• Cloudflare ve SHARED_HOST_IP değerleri ayrı bir ops vault'tan gelir, asla katkıcı laptopundan değil.

Nuvi'de tema iki yarımdan oluşur: JSON config (token, bölüm, varsayılan) packages/modules/theme/src/lib/theme-configs/<slug>.json ve React komponent ağacı bootstrap/tenant-front/src/themes/<slug>/. İkisi beraber bir mağazanın nasıl görüneceğini ve render olacağını tanımlar.

Adım 1 — Starter'ı kopyala

Mevcut starter teması üzerinden başla — en temiz minimal şekli o:

# JSON config
cp packages/modules/theme/src/lib/theme-configs/starter.json \
   packages/modules/theme/src/lib/theme-configs/mybrand.json

# React komponentler
cp -r bootstrap/tenant-front/src/themes/sdk \
      bootstrap/tenant-front/src/themes/mybrand

Adım 2 — Kimlik bilgisini güncelle

Yeni mybrand.json'u aç. id, name, description, author alanlarını değiştir. id alanı her yerde kullanılan URL-güvenli slug — küçük harf ve tire kullan.

Adım 3 — Token'ları ayarla

tokens.colors içinde vurgu paletini değiştir. CSS katmanı her giriş için var(--color-primary), var(--color-foreground) vb. otomatik üretir. Dark mode destekliyorsan tokens.colorsDark'ı da güncelle.

Adım 4 — Bölümleri bağla

bootstrap/tenant-front/src/lib/section-map.ts'i aç ve bölümlerini temana ait yorum bloğu altında kaydet:

// ── Mybrand sections ──
'mybrand-header': () => import('@/themes/mybrand/MybrandHeader'),
'mybrand-hero': () => import('@/themes/mybrand/MybrandHero'),

Adım 5 — Önizle

Dev stack'i ayağa kaldır: cd bootstrap && docker compose up -d. http://localhost:3000'a gir, http://localhost:9000/app admine giriş yap, Ayarlar → Temalar → Mybrand seç. Değişiklikler hot-reload olur.

Tam bir tema repo'da dört yere dokunur:

packages/modules/theme/src/lib/theme-configs/
  └── mybrand.json                # JSON config — tek kaynak

bootstrap/tenant-front/src/themes/mybrand/
  ├── manifest.ts                 # Section'ları kendisi bildirir + tema metadata
  ├── tokens.ts                   # cs helper — radius / padding / tipografi
  ├── schemas.ts                  # Bu temaya ait Zod şemaları
  ├── locales/
  │   ├── en.json                 # Tema-spesifik string override'ları
  │   └── tr.json
  └── sections/
      ├── MybrandHeader.tsx       # Her bölüm tipi için React komponent
      ├── MybrandHero.tsx
      └── MybrandFooter.tsx

bootstrap/medusa/src/lib/
  └── section-schemas/mybrand.ts  # Admin form alanları

JSON config tek kaynak. Temanın kimliğini, tasarım token'larını ve varsayılan bir sections array'ini bildirir — bu temayla render olan her sayfa buradan başlar. Runtime'da DB override'ları (admin özelleştirmeleri) üstüne biner.

React komponentler dummy render'lardır. Konfigürasyonlarını prop'tan okur (section.settings) ve JSX render eder. State yok, data fetch yok — sadece layout ve stil.

Zod şemaları admin ve storefront arasındaki sözleşmedir. Build sırasında ve API sınırlarında JSON config'i doğrular; admin section-editor form alanlarını da bunlar yönetir.

Token'lar runtime'da CSS custom property'lere dönen JSON değerleri. Şekil:

{
  "tokens": {
    "colors": { "primary": "#000", "background": "#FFF", "foreground": "#000", … },
    "colorsDark": { "primary": "#FFF", "background": "#000", "foreground": "#FFF", … },
    "typography": {
      "fontFamily": { "sans": "Inter, sans-serif", "serif": "Lora, serif" },
      "fontSize": { "xs": "0.75rem", "base": "1rem", "5xl": "3.5rem" }
    },
    "spacing": { "xs": "0.25rem", "md": "1rem", "3xl": "4rem" },
    "borderRadius": "0.5rem",
    "shadows": { "sm": "...", "lg": "..." },
    "layout": { "containerMax": "1200px", "headerHeight": "64px" }
  }
}

CSS'e nasıl iniyor

SSR tema helper'ı her yaprak değeri --<namespace>-<key>'a açar. tokens.colors.primary → --color-primary; tokens.layout.headerHeight → --layout-header-height. Dark varyantlar kullanıcı modu karanlıkken (ya da tema dark-only olduğunda) uygulanır.

Bölümde kullanım

<div style={{
  background: 'var(--color-background)',
  color: 'var(--color-foreground)',
  padding: 'var(--spacing-lg)',
  borderRadius: 'var(--border-radius)',
}}>
  …
</div>

Bir bölüm üç bağlı parçadan oluşur. Bu sırayla yap:

1. Zod şeması (storefront)

themes/mybrand/schemas.ts içinde:

import { z } from 'zod'
import { BaseSectionPropsSchema } from '@/themes/shared/schemas'

export const MybrandHeroSectionSchema = BaseSectionPropsSchema.extend({
  type: z.literal('mybrand-hero'),
  settings: z.object({
    badge: z.string().optional(),
    headline: z.string(),
    subheading: z.string().optional(),
    primaryCtaText: z.string().optional(),
    primaryCtaHref: z.string().optional(),
  }),
})
export type MybrandHeroSection = z.infer<typeof MybrandHeroSectionSchema>

2. React komponenti

themes/mybrand/sections/MybrandHero.tsx içinde:

'use client'
import type { z } from 'zod'
import type { MybrandHeroSectionSchema } from '@/themes/mybrand/schemas'
import { SectionComponentProps } from '@/lib/theme-types'

type Props = SectionComponentProps<z.infer<typeof MybrandHeroSectionSchema>>

export default function MybrandHero({ section }: Props) {
  const { settings } = section
  return (
    <section style={{ padding: '4rem 1.5rem', textAlign: 'center' }}>
      {settings.badge && <span>{settings.badge}</span>}
      <h1>{settings.headline}</h1>
      {settings.subheading && <p>{settings.subheading}</p>}
    </section>
  )
}

3. Kaydet

Section'ı tema kendi manifest.ts'ine ekler (artık merkezi bir registry düzenlemiyoruz — runtime her temanın manifest'inden global section map'i oluşturuyor):

// themes/mybrand/manifest.ts
import type { ThemeManifest } from '@/themes/sdk/types'

export const mybrandManifest: ThemeManifest = {
  id: 'mybrand',
  displayName: 'My Brand',
  namespaces: ['mybrand-'],
  sections: {
    'mybrand-hero': () => import('./sections/MybrandHero'),
    // …diğer section'lar
  },
}

Sonra mybrandManifest'i src/themes/index.ts'teki THEME_MANIFESTS'a ekle. Admin editör desteği için bootstrap/medusa/src/lib/section-schemas/mybrand.ts'a form alanlarını bildiren eşleşen şemayı da ekle.

Çoğu bölüm alt öğe listesine ihtiyaç duyar: feature kartı, müşteri sözü, fiyat tier'i, footer kolonu. Desteklenen iki kalıp:

Kalıp A — inline settings array (legacy)

Listeyi settings'e Zod array olarak tanımla:

settings: z.object({
  heading: z.string().optional(),
  features: z.array(z.object({
    icon: z.string().optional(),
    title: z.string(),
    description: z.string(),
  })).default([]),
})

Kalıp B — block ağacı (önerilen)

Bölümdeki blocks array'ini kullan. Her block'un kendi type'ı ve tipli settings'i var:

{
  "id": "features-1",
  "type": "mybrand-feature-grid",
  "settings": { "heading": "Neden biz" },
  "blocks": [
    { "type": "feature-item", "order": 0, "settings": { "title": "Hızlı", "description": "Saniye altı yükleme" } },
    { "type": "feature-item", "order": 1, "settings": { "title": "Sessiz", "description": "Upsell yok" } }
  ]
}

Komponentte @/lib/blocks-resolver'dan resolveBlockItems() kullan:

import { resolveBlockItems } from '@/lib/blocks-resolver'

const features = resolveBlockItems<{ title: string; description: string }>(
  section.blocks,
  settings.features,        // legacy fallback
  'feature-item',
)

Temalar config'i fork etmeden dile göre metin override'ı destekler. İki parça:

1. Helper'ı bağla

Bölüm komponentinde useUsenuviLocale() (ya da tema eşdeğeri) çağırarak ut() fonksiyonunu al:

import { useUsenuviLocale } from './use-usenuvi-locale'

export default function MybrandHero({ section }: Props) {
  const { ut } = useUsenuviLocale()
  const headline = ut(section.id, 'headline', section.settings.headline)
  return <h1>{headline}</h1>
}

2. Locale girdileri ekle

bootstrap/tenant-front/src/locales/tr.json'da (gerekirse en.json'da):

{
  "mybrand": {
    "hero-1": {
      "headline": "Her türlü web sitesi inşa et",
      "subheading": "AI destekli, tek tıkla kurulum."
    }
  }
}

ut() çağrısı aktif locale'de mybrand.<sectionId>.<field>'a bakar; override yoksa JSON config'teki değere düşer. Yazarlar koda dokunmadan dil bazlı override yapabilir.

Lokal önizleme

1. Dosyalar yerinde: JSON config, React komponentler, section-map kaydı, Zod şemalar, admin section-schemas.
2. cd bootstrap && docker compose up -d --build medusa tenant-front — ikisi de değişikliklerinle yeniden kurulur (medusa yeni JSON + admin şemayı, tenant-front komponentleri + Zod şemayı alır).
3. http://localhost:9000/app → Ayarlar → Temalar → Mybrand → Etkinleştir.
4. http://localhost:3000'a gir — temanın render olur. Next.js dev mod tenant-front için hot-reload yapar; modül paketindeki değişiklik için container rebuild gerekir.

Canlı tenant'a yayınlama

1. Monorepo'ya PR aç. CI tenant-front + medusa için tsc --noEmit çalıştırır, path'leri değişen servisler için image build başlatır.
2. main'e merge et. GitHub Actions yeni ghcr.io/<org>/medusa ve ghcr.io/<org>/tenant-front imajlarını push'lar.
3. Production sunucudaki deploy.sh bu imajları çeker, her tenant'ın container'larını yeniden oluşturur (örn. medusa-usenuvi, front-usenuvi).
4. Tenant'ta: Ayarlar → Temalar → Mybrand → Etkinleştir. Tema JSON'u yeni medusa imajında bundle'lı olduğu için galeride otomatik görünür.

Şu an OLMAYANLAR

• nuvi theme dev / nuvi theme build CLI yok — bugün Next.js dev server + docker compose kullanılıyor.
• create-nuvi-theme generator yok — yeni tema başlatmanın yolu starter'ı ya da en yakın production temayı kopyalamak.
• Tema marketplace'i yok — temalar şu an repo katkısı şeklinde.
• @nuvi/module-sdk paketi var (modül yazarları için manifest validator + tipler) ama bu kütüphane, CLI değil.

Bir CLI / paket modeli senin için engelliyse, iletişim sayfasında haber ver — yol haritası önceliğini etkiler.

AI asistan, Skill'ler etrafında kuruludur — bir ad, açıklama, Gemini function declaration'ları, executor eşleştirmesi ve system prompt parçasını paketleyen Python nesneleri. Repo, bootstrap/nuvi-agent/app/skills/ altında SEO, tema editörü, pazarlama, dropshipping ve daha fazlasını kapsayan ~24 skill taşır. Yenisini eklemek tek dosya ve tek satır kayıt.

1. Yeni dosya bırak

bootstrap/nuvi-agent/app/skills/<skilladi>.py oluştur. Temiz bir referans olarak seo_auditor.py'yi kullan. Skill instance'ını oluştur ve üzerinde register_skill() çağır:

from ..tools.declarations import list_products, update_product
from .base import Skill
from .registry import register_skill

inventory_helper = Skill(
    id="inventory_helper",
    name="Stok Yardımcısı",
    description="Düşük stoklu ürünleri bulur ve güncellemeyi önerir.",
    icon="package",
    category="commerce",
    model_tier="flash",
    quick_actions=(
        {"label": "Düşük stok", "prompt": "Düşük stoklu ürünleri listele",
         "icon": "alert-triangle"},
    ),
    translations={
        "en": {"name": "Inventory Helper",
               "description": "Find low-stock products and propose updates."},
    },
    declarations=(list_products, update_product),
    tool_map={
        "list_products":  ("medusa.read",  "list_products"),
        "update_product": ("medusa.write", "update_product"),
    },
    system_prompt="""Sen bir stok asistanısın. Sorulduğunda inventory_quantity < 10
filtreli list_products çağır, ardından özetle.""",
    required_modules=("inventory",),
)

register_skill(inventory_helper)

2. Alan referansı

Şekil app/skills/base.py'da. Anahtar alanlar:

• id — küçük harf, rakam, alt çizgi (regex zorlanır). Eşsiz olmalı.
• name, description, icon, category — panel skill seçicisinde gözükür.
• declarations — app/tools/declarations.py'dan Gemini function declaration tuple'ı.
• tool_map — her declaration adını (executor, action)'a eşler; agent bir fonksiyon çağrısını doğru backend'e (medusa.read, medusa.write, theme, vb.) böyle yönlendirir.
• system_prompt + localized_prompts — bu skill aktifken model'in system instruction'ına eklenir.
• required_modules — listede yer alan herhangi bir modül mağaza için kapalıysa skill UI'da gizlenir.
• model_tier — günlük hızlı işler için "flash", daha ağır akıl yürütme için "pro".

3. Import edilebilir yap

Skill'ler import sırasında register_skill() ile kaydolur. Dosyanı app/skills/__init__.py'dan import et (mevcut skill'ler aynı kalıbı izler) — agent boot ederken yüklensin.

4. Lokal stack'te test et

1. cd bootstrap && docker compose up -d --build nuvi-agent — yeni dosya ile Python imajı tekrar kurulur.
2. Medusa admin'de AI asistanı aç (http://localhost:9000/app/ai) ve skill'in seçicide göründüğünü doğrula.
3. Bir quick action tetikle; docker compose logs -f nuvi-agent'tan function call dispatch satırını izle.

Resmi Nuvi JS SDK storefront API'yi tipli metodlarla sarar. Kur:

npm install @nuvi/storefront-sdk

import { NuviClient } from '@nuvi/storefront-sdk'

const nuvi = new NuviClient({
  baseUrl: 'https://yourstore.com/api',
  publishableKey: 'pk_live_...',
})

const { products, count } = await nuvi.products.list({ limit: 20 })

Müşteri kapsamlı metodlar için kimlik doğrulama:

const { token } = await nuvi.auth.login({ email, password })
nuvi.setCustomerToken(token)
const me = await nuvi.customers.me()

Çoğu B2B satıcı fiyatı açıkça listelemez — pazarlık eder. @nuvi/module-quote paketi tüm teklif-tahsilat döngüsünü sarar: genel talep endpoint'i, admin inceleme ekranı, markalı PDF'ler ve e-posta gönderimi. Veri modeli packages/modules/quote/src/module/models/ altında quote, quote-item, service-template, service-category ve isg-config olarak yaşar.

1. Müşteri talebi gönderir

Herhangi bir sayfaya teklif-talep formu koy (modül quote-request storefront bölümünü hazır verir) ve genel endpoint'e POST at. Handler ad, e-posta ve telefonu sunucuda doğrular, fiyatları hizmet şablonlarından yeniden hesaplar, benzersiz quote_number üretir ve quoteRequestWorkflow ile taslağı kaydeder.

await fetch('/store/quote-requests', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    customer_name: 'Acme Ltd',
    customer_email: '[email protected]',
    customer_phone: '+90 555 000 00 00',
    customer_company: 'Acme Ltd',
    items: [
      { service_template_id: 'st_01H...', title: 'Risk Analizi', quantity: 1, unit_price: 2500 },
    ],
  }),
})

2. Admin inceler ve fiyatlandırır

Admin /app/quotes'u açar, satır kalemlerini düzenler ve durumu günceller (draft → sent → accepted). Yaşam döngüsü durumları quote modelindeki status enum'unda: draft, sent, accepted, rejected, expired. Süre valid_until ile yönetilir.

3. PDF + e-posta gönderimi

GET /admin/quotes/:id/pdf markalı PDF'i render eder. Mağaza-tarafı paylaşım linki workflow'da üretilen imzalı pdf_token'u kullanır — müşteri giriş yapmadan teklifini çekebilir. Bildirim alıcıları POST /admin/quotes/notification-recipients ile yapılandırılır.

4. ISG fiyatlandırma — çalışılmış örnek

Türk İSG firmaları çalışan sayısı ve tehlike sınıfına göre ücretlendirir. isg-config modeli service_durations, fulltime_thresholds, nurse_durations ve default_tax_rate'i tutar. Talep risk_class + employee_count içeriyorsa rota calculateIsgPrice()'ı sunucu tarafında çağırır — frontend fiyatları yok sayılır. Matrisi /app/services'ten ya da PUT /admin/quotes/isg-config ile düzenle.

5. Teklif-tahsilat devri

Teklif accepted olduğunda, quote.metadata ile Medusa order veya subscription'a bağla. Yaygın desen: quote_items'ı taslak order satırlarına kopyala, sonra Stripe / Iyzico ödeme linki gönder. Tekrarlanan servis sözleşmeleri — kabul edilen teklifi subscription modülünün subscription_plan'ı ile eşleştirip aylık tahsilata geç.

@nuvi/module-subscription paketi Medusa üzerine tekrarlayan tahsilat, müşteri portalı ve yaşam döngüsü hook'ları ekler. Her şeyi üç model yönetir: subscription_plan, customer_subscription ve subscription_payment (geçmiş). Stripe varsayılan sağlayıcı — plan üzerindeki stripe_price_id iki sistemi bağlar.

1. Plan oluştur

Planlar /app/subscriptions'tan ya da POST /admin/subscriptions/plans ile yönetilir. interval enum'u daily | weekly | monthly | yearly, interval_count ile çarpılır. trial_days deneme süresini, billing_cycles toplam yenileme sayısını sınırlar (sürekli için null).

{
  "name": "Pro Aylık",
  "price": 49,
  "currency": "USD",
  "interval": "monthly",
  "interval_count": 1,
  "trial_days": 14,
  "stripe_price_id": "price_1Ox..."
}

2. Müşteri kaydolur

Storefront POST /store/subscriptions/checkout'a plan_id, success_url, cancel_url ile çağrı yapar. Handler yönlendirme URL'lerini STORE_CORS / ADMIN_CORS'a karşı doğrular (açık-yönlendirme koruması) ve Stripe Checkout Session açar. Ödeme sonrası Stripe webhook'u customer_subscription kaydını trialing veya active durumunda ekler.

3. Deneme ve dunning

Müşteri deneme süresindeyken trial_end set edilir. Başarısız yenilemelerde durum past_due'a döner ve dunning politikası (varsayılan Stripe smart retries) devreye girer. Tükendiğinde durum canceled ya da expired olur.

4. Yaşam döngüsü endpoint'leri — müşteri portalı

Müşteri portalı dört yaşam döngüsü rotasını çağırır:

POST /store/subscriptions/:id/pause
POST /store/subscriptions/:id/resume
POST /store/subscriptions/:id/change-plan   { plan_id }
POST /store/subscriptions/:id/cancel        { at_period_end?: boolean }

at_period_end: true ile iptal kayıtta cancel_at_period_end'i set eder — abonelik current_period_end'e kadar active kalır, sonra canceled'a döner. Pause paused_at'ı set eder; resume temizler ve sonraki tahsilat tarihini yeniden verir.

5. Yenileme webhook'ları

Her başarılı yenileme bir subscription_payment kaydı yazar. Modülün event bus'ında subscription.payment.succeeded olayını dinleyerek kendi mantığını ekle — e-posta gönder, kullanım kredisi yükle ya da kendi ledger'ını mutabakat et.

6. Ürünlerle eşleme

subscription_plan.product_id Medusa ürününü işaret edebilir, böylece aynı SKU hem tek seferlik hem tekrarlayan satışı destekler. Plan'ın features JSON sütunu serbest bir torba — site_limit, mailbox_limit vb. — uygulamanın diğer yerlerinde yetkilendirme kontrolü için kullanılır.

@nuvi/module-travel Nuvi'yi tur operatör platformuna dönüştürür. Veri modeli tur işletmelerinin düşünüş şeklini yansıtır: bir tour itinerary günlerine, included / excluded dizilerine, highlights'a, rehber bloğuna ve fiyatlandırmaya sahiptir. Turlar destination kayıtlarına (çoktan-çoğa, tour-destination üzerinden) ve tour-category taksonomisine bağlanır.

1. Tour varlığı

packages/modules/travel/src/module/models/tour.ts içinde tanımlı. Önemli alanlar: slug (mağaza başına benzersiz), duration_days, max_group_size, price_from, price_per_guest ve itinerary, included, excluded, quick_facts için zengin JSON sütunları. Durum enum'u draft | published | archived.

2. Destinasyonlar ve kategoriler

Destinasyonlar tekrar kullanılabilir yerler — Kapadokya, Patagonya, Fuji. Genel listeleme GET /store/destinations, detay GET /store/destinations/:slug. Kategoriler (şehir turu, macera, aile) kenar çubuğu filtrelerini GET /store/tour-categories ile besler.

3. Rezervasyon akışı

Rezervasyonlar Medusa sepetini yeniden kullanır. Adanmış cart line endpoint'i ile bir tur ekle:

POST /store/carts/:id/tour-items
{
  "tour_id": "tour_01H...",
  "departure_date": "2026-07-15",
  "guest_count": 2,
  "options": { "transfer": true }
}

Satır kalemi tur verisini standart Medusa checkout'undan geçirir — ödeme, adres, onay. Sipariş verildikten sonra siparişin metadata'sını tur kaydına bağlayıp rezervasyon onayını render edebilirsin.

4. Yorumlar

Storefront onaylanmış yorumları GET /store/tours/:slug/reviews ile çeker. Handler yalnızca status: 'approved' filtreler — taslak ya da reddedilmiş yorumlar asla sızmaz. Tour üzerindeki rating ve review_count moderasyon akışıyla güncellenen denormalize toplamlardır.

5. Admin tarafında içerik

/app/travel editörü sağlar. Slug benzersizliği GET /admin/tours/check-slug ile kontrol edilir. Fiyatlandırma ve kalkış-bazlı override'lar /admin/tours/:id/pricing altında; moderasyon kuyruğu /admin/tours/:id/reviews'da.

6. Travel teması ile eşleme

Travel teması bu veriye uyan bölüm bileşenlerini hazır verir: destinasyon aramalı hero, tour grid, gün-gün itinerary, dahil/dahil-değil checklist'leri ve rehber kartı. bootstrap/tenant-front/src/lib/section-map.ts'e kaydet — manifest'te listelenen tour-grid bölümü editörde görünür.

@nuvi/module-events etkinlik yayını ve biletleme verir. Üç temel model: event (etkinlik), event-ticket-type (fiyat seviyeleri + kapasite) ve event-registration (satılan koltuk). Storefront genel etkinlik sayfasını görür; admin katılımcı listesi, satış raporu ve check-in görür.

1. Event varlığı

packages/modules/events/src/module/models/event.ts içinde tanımlı. Model zamanlama (starts_at, ends_at, timezone, is_all_day), mekan (venue_name, venue_address, venue_city), online_url ile online flag ve üst-seviye capacity taşır. Durum: draft | published | cancelled | completed. registration_enabled sayfayı yayından kaldırmadan bilet satışını kapatır.

2. Bilet türleri

Her etkinlik birden çok event_ticket_type'a sahip: Early Bird, Genel Giriş, VIP. Her seviyenin price, capacity ve registered_count'u stok hesaplar. sales_start_at ve sales_end_at satış pencerelerini uygular. Store-tarafı endpoint türetilmiş flag'leri storefront yerine kendisi hesaplar:

{
  "registration_enabled": true,
  "ticket_types": [
    {
      "id": "ett_01H...",
      "name": "Early Bird",
      "price": 49,
      "available": 23,
      "is_sold_out": false,
      "is_within_sales_window": true
    }
  ]
}

3. Sepet + checkout

Biletler standart Medusa sepetinden geçer, adanmış event-line endpoint'i ile:

POST /store/carts/:id/event-items
{
  "event_id": "evt_01H...",
  "ticket_type_id": "ett_01H...",
  "quantity": 2,
  "attendee_name": "Ayşe Yılmaz",
  "attendee_email": "[email protected]"
}

Sipariş tamamlandığında modül her bilet için benzersiz confirmation_number ile bir event_registration oluşturur. Durum akışı: pending_payment → confirmed → checked_in (ya da cancelled).

4. Katılımcı listesi ve giriş

Admin katılımcı listesini GET /admin/events/:id/registrations, satış toplamlarını GET /admin/events/:id/stats ile çeker. Kapı görevlileri check-in endpoint'ine basar — durum checked_in'e döner ve checked_in_at damgalanır.

5. Müşteri portalı — biletlerim

Giriş yapmış müşteriler tüm biletlerini — geçmiş ve gelecek — tek endpoint'ten görür:

// Auth gerekli. Sunucu müşterinin e-postasını oturumdan
// çözer, sonra attendee_email ile kayıtları arar.
{
  "registrations": [
    {
      "id": "reg_01H...",
      "confirmation_number": "EVT-2026-00042",
      "status": "confirmed",
      "event": { "title": "Spring Summit", "starts_at": "..." },
      "ticket_type": { "name": "VIP" }
    }
  ]
}

6. Etkinlik sonrası iletişim

Email-marketing modülü ile birleştirip katılımcılara mesaj at: event_registrations'ı event_id ve status: 'checked_in' ile filtrele, sonra kayıt linki veya geri bildirim anketi gönder. Etkinliği iptal etmek için status'u cancelled'a çevir — my-registrations endpoint'i yeni durumu anında yansıtır.