Sanity Sayfa Oluşturucu Hatalarında Sık Karşılaşılan 5 Yer: Bunları Önleyin

Sanity tabanlı pazarlama sitelerinde neredeyse herkesin kullandığı sayfa oluşturucuların arkasında aslında birbirine çok benzeyen bir yapı yatıyor. Bu yapı genellikle bölümlerden oluşan bir dizi, ekleme menüsü ve blok türlerini bileşenlere eşleştiren bir render döngüsünden oluşuyor. Maalesef herkes tarafından geliştirilen bu sistemler de aynı beş temel hatayı içeriyor.

Bu hataların en sinir bozucu yanıysa, her yeni projede aynı şekilde karşınıza çıkmaları. Her defasında baştan aşağı yeniden yazılan yapı, projeden projeye değişmediği için aynı sorunlar tekrarlanıyor.

Sayfa oluşturucuların gizli vergisi: Beş zorunlu adım

Sanity ile Next.js kullanan tipik bir sayfa oluşturucuda yeni bir bölüm eklemenin gerçek maliyeti aşağıdaki beş adımdan oluşuyor:

• Şema tanımı: Yeni bir *Section nesne türü oluşturulması ve şemanın indeksine kaydedilmesi.
• GROQ sorgusu: Sayfa oluşturucunun blok projeksiyonunda yeni bölümün alanlarının da dahil edilmesi.
• Bileşen geliştirme: O bölümün React bileşeninin oluşturulması.
• Render haritası: _type değerini bileşene eşleştiren bir haritanın güncellenmesi.
• Tür tanımı: Blok varyantının ön uçtaki birleşim türüne eklenmesi.

Bu adımlardan sadece ikincisini unuttuğunuzda bile bölümünüz boş olarak görüntüleniyor. Dördüncü adımı atladığınızdaysa, sistem sessizce atlıyor. Beşinci adımı unuttuğunuzdaysa TypeScript’in elinde kalitesiz bir birleşim türü oluşuyor. Üç farklı sessiz hata modu, hepsi de "benim makinemde çalışıyor" diye geçiştiriliyor — ta ki canlı yayında boş bir alanla karşılaşana kadar.

Peki bu beş adımın hangisi gerçekten projelerinize özgü?

Bileşen geliştirme kısmı. Tasarım sisteminize, marka renklerinize ve kullanıcı arayüzü kurallarınıza bağlı olan bu kısım aslında benzersizdir ve kimse tarafından yeniden kullanılmamalıdır.

Diğer dört adım ise aslında boru hattı görevi görüyor. _type değerini bir haritada aramak, bileşeni çağırmak ve haritayı şema ve sorgu ile senkron tutmak. Bu kod her projede neredeyse aynı şekilde yazılıyor. Peki neden elinizle beşinci kez yeniden yazılıyor?

Boru hattını ayırın, bölümleri kendinize saklayın

İşe yarayan çözüm: Bölümleriniz sizin olsun, ancak jenerik dağıtıcıyı bağımlılık olarak görüp artık düşünmek zorunda kalmayın. Bu yaklaşımın arkasında, aynı hatayı beşinci kez yaptığımda ortaya çıkardığım iki paket yatıyor: @maciejtrzcinski/sanity-page-builder-core (ön uç) ve @maciejtrzcinski/sanity-plugin-section-builder (Stüdyo).

Ancak paketlere odaklanmayın — asıl önemli olan tasarım kalıbı. Bu paketler sadece bu kalıbın pratik uygulamasından ibaret.

Tek bir kaynakta bölüm tanımı

Hatanın asıl nedeni, bir bölümün type, GROQ query ve render değerlerinin üç ayrı dosyada bulunması. Bu üç öğeyi tek bir yerde birleştirerek senkronizasyon sorununu ortadan kaldırabilirsiniz:

const defineSection = createSectionFactory<PageBuilderBlock, RenderContext, ReactNode>()

const hero = defineSection({
  type: 'heroSection',
  query: `title, subtitle, ctaHref`,
  render: (block) => <Hero {...block} />,
})

Artık type, query ve render aynı nesnede yer alıyor. Böylece bölüm eklerken projeksiyonu unutmanız mümkün değil — hepsi aynı yerde tanımlandı.

Hem render döngüsünü hem de GROQ sorgusunu aynı listeden oluşturun

const pb = createPageBuilderFromSections([hero, /* … */], { strict: true })

pb.renderBlock  // Blokları render ediciye yönlendirir
pb.query        // `_type == "heroSection" => { title, subtitle, ctaHref }, …`

Birleşik GROQ projeksiyonu artık manuel olarak yazılmak yerine, bölümlerinizden otomatik olarak türetiliyor. Eskiden sessizce senkron dışı kalan bu sorgular artık render edicilerle aynı kaynaktan geliyor. Bu da "bölümünüzün sorgusu unutulduğu için boş görüntülendiği" hataların tamamını ortadan kaldırıyor.

strict: true seçeneğiyle _type değerine karşılık gelen bir render edici bulunamazsa sistem sessizce atlamak yerine hata fırlatıyor. Bölümünüzün kaydedilmesini unuttuğunuzda artık sistem sizi uyarıyor.

Derleyiciyi paralelliği zorunlu kılmak için kullanın

Jenerik dağıtıcı, sizin blok birleşiminizin üzerine kuruludur. Bu sayede render haritası, block._type üzerine otomatik olarak eşlenir. Derleyici her varyant için doğru şekilde yazılmış bir render ediciyi zorunlu kılar — her render edici daraltılmış bloğu alır, herhangi bir tip dönüşümü gerekmez. Birleşime yeni bir bölüm ekleyip render ediciyi unuttuğunuzda derleme aşamasında hata alırsınız ve canlı yayına asla boş bir alan gönderemezsiniz.

Tip sisteminin göremediği kısımlar için (kayıtlı şema türleri, çalışma zamanı GROQ dizgisi) tek bir testle bütünlüğü doğrulayabilirsiniz:

assertPageBuilderIntegrity({
  renderers,
  registeredTypes,
  query: pageBuilderFields
})

Bu test, render haritanız, kayıtlı bölümleriniz ve projeksiyonunuz arasındaki senkronizasyonu bozan herhangi bir değişiklikte anında başarısız olur. Artık beş adımlık hata modelleri, canlı sayfalardaki boşluklar yerine CI sürecinde yakalanıyor.

Bu paketin çekirdeği bağımlılık içermez — düğüm tipi jenerik bir parametredir, bu yüzden React ya da Sanity’yi dahil etmez. Tüm kodu tek oturumda okuyabilirsiniz. Bu kasıtlı bir tercihtir: Bu, boru hattıdır ve sıkıcı ve küçük olması gerekir.

Kullanımı kolay bir Stüdyo arayüzü: Ekleme menüsünü basitleştirin

Render döngüsü ön uç için. Diğer tekrarlanan vergi ise Stüdyo tarafında — yalnızca tür adlarının bulunduğu ekleme menüsü ve her bölüm şeması için kopyala-yapıştır yapılan components: { preview: … } bloğu.

Eklenti, önizlemeleri küresel olarak ekler ve bölümlerinizi otomatik olarak algılar:

// sanity.config.ts
plugins: [sectionBuilder(SECTIONS)]

// sayfa döküman alanları
fields: [sectionField(SECTIONS, { group: 'content' })]

*Section türünü eklediğinizde otomatik olarak algılanır. Önizlemeler dosya adı kuralına göre çözümlenir — bölümünüzün adını heroSection olarak belirlerseniz ve hero-section.png dosyasını önizlemeler klasörüne eklediğinizde, bu önizleme hem dizi editöründe hem de düzenleme bölmesinde görüntülenir. Elle harita oluşturmanıza gerek kalmaz. Editörleriniz görsel bir ızgaraya sahip olurken, siz de kodunuzu silersiniz.

Sonuç: Bütüncül bir yaklaşım

Her iki taraf için de tek bir kaynak — bölüm listesi — ve paketler otomatik bağlantıyı sağlıyor. Artık her projeye beşinci kez aynı boru hattını yazmak zorunda kalmıyorsunuz. Bunun yerine, bölümlerinize odaklanabilir ve sisteminizin arka planda düzgün çalışmasını sağlayabilirsiniz.

Bu kalıbın en büyük avantajıysa, projeden projeye değişmeyen ve yeniden kullanılabilen bir altyapı sunması. Gelecekteki projelerinizde de aynı hataları yapmaktan kurtulacaksınız — ve bu, en değerli kazançlardan biri olacaktır.