BelgelerGeliştirici KılavuzuHızlı Özelleştirme Tarifleri (Recipes)

Özelleştirme Tarifleri ve Yeni Özellik Geliştirme

Bu kılavuz, proje kaynak kodunu edinen ve yeni özel özellikler eklemek, ürün seçeneklerini çok dilli hale getirmek veya özel görsel bileşenler oluşturmak isteyen geliştiriciler için hazırlanmıştır.

Tarif 1: Ürün Seçeneklerini ve Renk Dairelerini (`color`) Yönetme ve Çevirme

Renk Anahtarı İçin Değiştirilemez Kural (Color Swatches)

Medusa yönetici panelinde, renge atanan seçenek başlığı istisnasız color (veya Color) olmalıdır. Next.js ön yüzü, Hex renk kodlarını tanımak, etkileşimli renk daireleri ve görsel filtreler oluşturmak için bu anahtarı kullanır.

Strapi ile seçenek başlıklarını çok dilli hale getirme süreci:

Diğer seçenekler (beden, malzeme, marka gibi) için herhangi bir dilde serbestçe adlandırma yapılabilir.
Seçenek başlıklarının yerelleştirilmiş karşılıkları (örneğin color için "Renk" veya Size için "Beden") Strapi CMS panelinde dinamik olarak tanımlanır.
Next.js ön yüzü, kullanıcının mevcut Yerel Ayarına (Locale) göre başlık çevirisini Strapi'den çekerken, filtreleme anahtarı color olarak kalır.

Ön yüzde Strapi'den seçenek çevirisini çekme örneği

typescript

// store/src/lib/strapi-client/get-option-translations.ts
export async function getOptionTranslation(optionKey: string, locale: string = "fa") {
  const res = await fetch(
    `${process.env.NEXT_PUBLIC_STRAPI_URL}/api/option-translations?filters[key][$eq]=${optionKey}&locale=${locale}`,
    { headers: { Authorization: `Bearer ${process.env.STRAPI_API_TOKEN_FOR_FRONT}` } }
  )
  const json = await res.json()
  return json.data?.[0]?.translated_name || optionKey
}

Tarif 2: Medusa v2'de Yeni Bir İş Akışı (Workflow) ve REST API Uç Noktası Ekleme

Medusa v2'de iş mantığı Adımlar (Steps) ve İş Akışları (Workflows) olarak ayrılmıştır:

store-admin/src/workflows/daily-deals.ts

typescript

import { createWorkflow, createStep, StepResponse, WorkflowResponse } from "@medusajs/framework/workflows-sdk";
 
const fetchDealsStep = createStep("fetch-deals-step", async () => {
  const deals = [{ id: "deal_1", title: "Günün Özel Fırsatı", discount: "25%" }];
  return new StepResponse(deals);
});
 
export const getDailyDealsWorkflow = createWorkflow("get-daily-deals", function () {
  const deals = fetchDealsStep();
  return new WorkflowResponse(deals);
});

store-admin/src/api/store/daily-deals/route.ts

typescript

import { MedusaRequest, MedusaResponse } from "@medusajs/framework/http";
import { getDailyDealsWorkflow } from "../../../workflows/daily-deals";
 
export async function GET(req: MedusaRequest, res: MedusaResponse) {
  const { result } = await getDailyDealsWorkflow(req.scope).run();
  res.json({ deals: result });
}

Tarif 3: Anasayfa İçin Yeni Bir Blok Oluşturma

Anasayfa blokları store/src/modules/home/components/ dizininde yer alır. Her blok üç kısımdan oluşur: homepage.ts dosyasında bir tür tanımı, Strapi'de bir Bileşen (Component) şeması ve bir React bileşen klasörü.

Gerçek Proje Yapısı

FeaturesBlock, BlogPostsBlock, ProductShowcase ve ProductSplitView gibi mevcut blokların her biri bağımsız bir klasöre sahiptir ve BlockRenderer içinde Strapi tarafından döndürülen __component ile tanımlanır.

Örnek: Bir "Geri Sayım" (Countdown) Bloğu Ekleme

TypeScript Türünü Tanımlayın — store/src/lib/data/homepage.ts dosyasına yeni blok arayüzünü ekleyin ve ana birleşim (union) türüne dahil edin:

store/src/lib/data/homepage.ts

typescript

export interface CountdownBlock {
  __component: "ui.countdown-block"
  id: number
  title?: string
  target_date: string
}
 
// Ana birleşim türüne ekleyin
export type HomepageBlock =
  | ProductSplitViewBlock
  | ProductShowcaseBlock
  | FeaturesBlock
  | BlogPostsBlock
  | CategoryCollectionBlock
  | CountdownBlock   // <-- buraya eklendi

Klasör ve React Bileşenini Oluşturun — store/src/modules/home/components/ dizininde CountdownBlock adında bir klasör oluşturun:

store/src/modules/home/components/CountdownBlock/index.tsx

tsx

import React from "react"
import type { CountdownBlock as CountdownBlockType } from "@lib/data/homepage"
 
 
interface CountdownBlockProps {
  block: CountdownBlockType
}
 
export default function CountdownBlock({ block }: CountdownBlockProps) {
  return (
    <section className="py-16 text-center">
      <h2 className="text-xl font-bold mb-4">{block.title}</h2>
      <p className="text-gray-500">{block.target_date}</p>
    </section>
  )
}

BlockRenderer'a Kaydedin — store/src/modules/home/components/BlockRenderer/index.tsx dosyasını açın ve switch ifadesine yeni bir case ekleyin:

store/src/modules/home/components/BlockRenderer/index.tsx

tsx

import CountdownBlock from "../CountdownBlock"
 
// BlockRenderer içindeki switch(block.__component):
case "ui.countdown-block":
  BlockContent = <CountdownBlock block={block} />
  break

Strapi'de Bileşen Şeması Oluşturun — website-admin/src/components/ui/ klasöründe yeni bir JSON dosyası oluşturun:

website-admin/src/components/ui/countdown-block.json

json

{
  "collectionName": "components_ui_countdown_blocks",
  "info": {
    "displayName": "Countdown Block",
    "icon": "clock",
    "description": "A countdown timer block for the homepage"
  },
  "options": {},
  "attributes": {
    "title": { "type": "string" },
    "target_date": { "type": "datetime", "required": true }
  }
}

Son Adım

Strapi'yi yeniden başlattıktan sonra, yönetici panelinde Homepage > Dynamic Zone bölümüne gidin. Yeni "Countdown Block" eklenebilir bloklar listesinde görünecektir.

Tarif 4: Yeni Bir Ödeme Sağlayıcısı Bağlama (Payment Provider)

Yeni bir ödeme geçidi eklemek için store-admin/src/modules/payment/ klasöründe AbstractPaymentProvider sınıfını uygulayan bir servis tanımlayın ve ödeme modülünün providers bölümü altında medusa-config.ts dosyasına kaydedin.