İçeriğe geç
Docs

Sorun Giderme

Tecof Studio ve TecofRender için sık sorunlar ve çözümleri — seçilemeyen bileşen, yayında görünmeyen stil veya bileşen, boş repeat şablonu, API/CORS/yükleme hataları, iframe mesajları ve üretim kontrol listesi.

Son güncelleme:

Bileşen kanvasta seçilemiyor#

  1. Bileşen props.className’i kök DOM elemanına basıyor mu? Her dal (erken return’ler dahil) basmalı. defineSection / defineElement bunu otomatik yapar (Kök className sözleşmesi).
  2. render bir bileşen elemanı döndürüyorsa o bileşen className prop’unu kendi kökünde kullanıyor mu?
  3. inline: true bileşende puck.dragRef köke bağlı mı?

Stil sekmesinde verilen stil görünmüyor#

  1. Aynı nedenle: className köke ulaşmıyorsa stil sınıfları da ulaşmaz.
  2. Doğru katmanı mı düzenliyorsunuz? Kırılımlar masaüstü önceliklidir: md 768 px ve altında uygulanır (Stil editörü).
  3. Temanın Tailwind derlemesinde Studio sınıflarını safelist’e eklediyseniz kaldırın; mobil-öncelikli kurallar TecofRender’ın kurallarıyla çakışır.
  4. Marka skalası (primary-*) yayında renksiz görünüyorsa temanın --color-primary-* değişkenlerini tanımladığını doğrulayın (Tema marka paleti).

Bileşen editörde var, yayında yok#

  1. Editör ve renderer aynı StudioConfig nesnesini mi kullanıyor? Kayıtlı type yayındaki config’te yoksa düğüm sessizce atlanır.
  2. Tip adını değiştirdiyseniz migrations.renameComponents ekleyin (Migration).
  3. Düğüm Katmanlar’da gizlenmiş (_hidden) olabilir; gizli düğümler yayında render edilmez.

Slot yerleşimi yayında bozuk#

  1. .tecof-slot-* yerleşim sınıfları temanın global CSS’inde var mı? Yayın sayfası paket CSS’ini yüklemez (Yayın render’ı).
  2. Repeat slotlarda yayın yerleşimi <Slot layout>’tan değil orientation’dan gelir (Slotlar).

Repeat şablonu yayında boş#

  1. repeatSource prop’u gerçekten bir dizi (ya da API/CMS kaynağı) taşıyor mu? Satır yoksa şablon bilerek hiç render edilmez.
  2. CMS kaynağı kullanılıyorsa ağaçta TecofProvider var mı?
  3. Token yolu satır nesnesindeki alanla eşleşiyor mu ({{ item.name }} ↔ row.name)?

Tema renkleri ya da fontlar eksik#

TecofRender tema değişkenlerini ve fontları kendisi basar. Sayfayı kendiniz render ediyorsanız generateCSSVariables, themeGoogleFontsHref ve themeFontFaceCss çıktısını <head>’e ekleyin (Canlı tema).

API, CORS ya da yükleme hatası#

  • API adresinin sonundaki / istemci tarafından temizlenir.
  • Backend x-secret-key ve Authorization başlıklarına izin veriyor mu?
  • Yükleme isteğinde Content-Type’ı elle vermeyin; çok parçalı sınırı tarayıcı ekler.
  • Yazma uçları (kaydet, yükle, ortak bileşen) JWT ister: accessToken verildi mi, süresi doldu mu?
  • Çok temalı mağazada themeId verilmezse istekler aktif temaya gider.

iframe mesajları çalışmıyor#

  1. hostOrigin ile üst pencerenin origin’i birebir aynı mı (şema, alan adı, port)?
  2. Mesaj iframe.contentWindow’a gönderiliyor mu?
  3. Gelen mesajda event.origin ve puck: tipi doğrulanıyor mu? Ayrıntı: iframe ve postMessage.

AI asistanınız API uyduruyor#

Asistanı doküman MCP sunucusuna bağlayın: search_docs → read_doc_page ile bu belgeleri, read_type_definition ile paketin gerçek TypeScript bildirimlerini okur. Çelişkide dışa aktarılan tipler son doğruluk kaynağıdır.

Üretim kontrol listesi#

  • @tecof/theme-editor/styles.css editör layout’unda içe aktarıldı.
  • Editör ve renderer aynı StudioConfig’i kullanıyor.
  • Her bileşen className’i kök DOM elemanına basıyor.
  • .tecof-slot-* yerleşim sınıfları temanın global CSS’inde.
  • Studio stil sınıfları temanın Tailwind safelist’ine eklenmedi.
  • Gömülü editörde hostOrigin verildi; editör rotası yalnız panelden token ile açılıyor.
  • Tip adı değişen bileşenler için migrations tanımlandı.
  • Karanlık mod açıksa <head>’de darkModeHeadScript() var.
  • @tecof/theme-editor sürümü package.json’da sabit ve güncel.