5 Kasım 2026 · 8 dk okuma

Polaris 2.0'a Geçişten Sonra Gömülü Shopify Uygulamasını Polaris Web Bileşenlerine Taşıma

Polaris 2.0 kararlı hâle geldi ve Polaris React kullanımdan kaldırıldı. Gömülü Shopify uygulamasını Polaris web bileşenlerine taşımak için tam rehber.

Polaris 2.0'a Geçişten Sonra Gömülü Shopify Uygulamasını Polaris Web Bileşenlerine Taşıma

Polaris 2.0, 22 Ekim 2026'de Shopify CDN'de kararlı sürüme ulaştı ve @shopify/polaris React paketi artık resmi olarak kullanımdan kaldırıldı ve arşivlendi. Gömülü uygulamanız hâlen @shopify/polaris paketinden <Page> ve <DataTable> bileşenlerini kullanıyorsa, artık hiçbir güncelleme, güvenlik yaması veya yeni bileşen almayan bir kütüphaneyi çalıştırıyorsunuz demektir. Taşıma yolu açık tanımlanmıştır: npm bağımlılığını kaldırın, bir CDN script etiketi ekleyin, React JSX bileşen ağaçlarını s-* özel öğeleriyle değiştirin ve olayları callback özelikleri yerine DOM üzerinden bağlayın.

Temel çıkarımlar

  • polaris.js ve polaris-1.js her ikisi de Polaris 1.x üzerinde sonsuza kadar kalacak ve hiçbir zaman 2.x sunmayacaktır. polaris-2.js ile açıkça değiştirmeniz gerekir.
  • Tüm 2025-10 ve daha sonraki API sürümleri varsayılan olarak Polaris web bileşenlerini kullanır. 2025-07 veya daha eski sürümlerdeki uzantılar 1 Ekim 2026'dan sonra güncellemelerden engellenmiştir.
  • React 18, kontrollü s-* form alanlarını yönetemez. Kontrollü girdileri taşımadan önce React 19'a yükseltmeniz gerekir.
  • Polaris React ve Polaris web bileşenleri taşıma sırasında aynı uygulamada birlikte çalışabilir, bu nedenle dilim halinde yayın yapabilirsiniz.
  • Built for Shopify uygulamaları 1 Mayıs 2027'ye kadar yeni admin görsel stiline uygun hâle gelmelidir.

CDN modeli neden var

Eski @shopify/polaris npm paketi React'i, reconciler'ı ve tasarım belirteçlerini her uygulama derlemesine paketledi. Bu yaklaşım React tek ilgili renderer olduğunda çalışıyordu, ancak Shopify artık Uygulama Giriş Sayfası, ödeme uzantıları, POS uzantıları ve müşteri hesap sayfaları genelinde UI sunuyor; bunların hepsi farklı sandbox kısıtlamalarına sahiptir.

Remote-dom, Shopify'ın platformlar arası UI'ları için kullanılan kütüphanesi, gerçek DOM düğümlerini yalıtılmış bir sandbox'tan ana bilgisayara yansıtır, böylece herhangi bir DOM-render framework çalışır. Polaris web bileşenleri, bunun üstüne oturan framework-agnostik özel öğelerdir. Shopify, beş yüksek trafikli Checkout Blocks uzantısını React'ten Preact'e Polaris web bileşenleriyle taşıyarak içeride bu yaklaşımı kanıtladı ve bundle boyutlarını yüzde 40 ile 85 arasında azalttı. En büyük tek uzantı yüzde 84,4 oranında küçüldü. 2026-01 remote-dom CLI, uzantı başına 64 KB gzip'lik bir hard sınır uygular, bu da daha önceki 100 ila 112 KB gzip'lik bundlelere düşüşüdür.

Uygulama Giriş Sayfası gömülü uygulaması için hikaye daha basittir: Polaris, cdn.shopify.com/shopifycloud/polaris-2.js adresinden tek bir script etiketi olarak yüklenilir, özel öğeleri tarayıcıda kaydeder ve bileşenler yeniden dağıtım yapmadan her uyumlu minör CDN sürümüyle güncellenir.

CDN sürümleme modeli (bunu önce anlayın)

Shopify, 31 Ağustos 2026'da Polaris CDN için semantic versioning'i açıkladı. Tek bir dosyaya dokunmadan önce kurallar önemlidir.

CDN URL'siNe sunarNe zaman kullanılır
polaris.js (eski)Polaris 1.x, 1.1'de sabitlenmişHiçbir zaman yeni iş için. Hiçbir zaman 2.x'e geçmez.
polaris-1.jsEn son kararlı 1.xKasıtlı olarak 1.x'te kalıyor
polaris-2.jsEn son kararlı 2.xÖnerilen üretim hedefi
polaris-2.0.jsTam olarak 2.0.0'a sabitlenmişTam sürümü kontrol etmek istediğinizde
polaris-2.0-rc.js2.0 release candidateRC'ye karşı test etme; üretim için değil

@shopify/polaris-types npm paketi CDN ana sürümünü yansıtır. polaris-2.js yüklüyorsunuz ancak tsconfig'iniz @shopify/polaris-types@^1 çöküyorsa, TypeScript yanlış bileşen API'sine karşı derlenir ve özellik yeniden adlandırmalarını sessizce kaçırırsınız. Başka herhangi bir adımdan önce @shopify/polaris-types@^2.0.0 yükleyin.

İki ayrı taşıma yolu

"Polaris web bileşenlerine taşıma" ifadesi aslında farklı çalışma gerektiren iki farklı durumu kapsar:

Yol A: Zaten Polaris web bileşenleri (Polaris 1.x) üzerinde, Polaris 2.0'ı benimseyin

Uygulamanız s-* etiketlerini render ediyor ancak polaris.js veya polaris-1.js yüklüyor. Benimseme iki dosyalık bir değişikliktir: CDN script etiketini polaris-2.js ile güncelleyin ve @shopify/polaris-types'i ^2.0.0 olarak arttırın. Sonra test edin. Görsel değişiklikler gerçekler, özellikle s-frame, s-nav-menu ve s-button, mağazanız yeni admin tasarımını aldığında yeniden tasarlanan yöneticinin yeni renk ve boşluk belirteçlerini alır.

Yol B: Hâlen Polaris React (@shopify/polaris) üzerinde, web bileşenlerine taşıyın

Bu daha büyük bir projedir. Bu gönderinin geri kalanı birincil olarak Yol B hakkındadır.

Adım 0: Bir satır kod yazmadan önce denetleyin

Herhangi bir koda dokunmadan önce etki alanını harita yapın:

  • Polaris React importu olan her dosyayı bulmak için grep -r "@shopify/polaris" src/ --include='*.tsx' --include='*.ts' -l çalıştırın.
  • node_modules içinde @shopify/polaris bileşenlerini dahili olarak yeniden dışa aktaran paketleri tanımlayın. Bunlar sessiz engelleyicilerdir çünkü kendi JSX'leri otomatik olarak taşınmaz.
  • .Polaris-* sınıf adlarını geçersiz kılan CSS olup olmadığını kontrol edin. Web bileşenleri içindeki Shadow DOM bu geçersiz kılmaları ulaşılamaz hâle getirir, bu nedenle bunlar sessizce çalışmayı durdurur.
  • Mevcut React sürümünüzü kaydedin. React 18'deyseniz, kontrollü form alanlarını taşımadan önce React 19'a yükseltmeniz gerekir. React 18, kontrollü Polaris web bileşenlerinin güvendiği özel öğe özelliğini ve olay davranışını eksik kılar.

Adım 1: İkili render kurulumu

Polaris React ve Polaris web bileşenleri taşıma sırasında aynı uygulamada render edebilir. Bu kasıtlı ve desteklenir. Büyük patlama yazılımına gerek yoktur.

Bileşenlere dokunmadan önce CDN script etiketini ve türlerini şimdi ekleyin:

<!-- app/root.tsx veya üst düzey layoutunuz -->
<script src="https://cdn.shopify.com/shopifycloud/polaris-2.0-rc.js"></script>

Yükleme sırasına dikkat edin: Polaris betiği App Bridge'den sonra gelmelidir. App Bridge shopify globalini kaydetmeden önce enjekte ederseniz, bazı App Bridge bileşen entegrasyonları sessizce başarısız olur.

React Router şablon uygulamaları için polarisUrl iki yerde ayarlanmalıdır:

// app/shopify.server.ts
const shopify = shopifyApp({
  // ...
  polarisUrl: "https://cdn.shopify.com/shopifycloud/polaris-2.0-rc.js",
});
// app/routes/app.tsx
<AppProvider
  isEmbeddedApp
  polarisUrl="https://cdn.shopify.com/shopifycloud/polaris-2.0-rc.js"
>
  <Outlet />
</AppProvider>

Bu iki konumu uyuşturmazlık, CDN betiğinin iki kez yüklenmesine veya hiç yüklenmemesine neden olur, bu yaygın bir arıza modudur. Ağ sekmesini kontrol edin ve devam etmeden önce Polaris CDN'ye tam olarak bir istek olduğunu doğrulayın.

Adım 2: Rota dilimleri halinde taşıyın

Shopify'ın resmi rehberliği, uygulamayı aynı anda tümü yerine çalışan dilimler halinde taşımaktır. Taşıma sırasında bir web bileşeni yaprağı Polaris React sayfasında render edebilir. Kaçınılması gereken şey, layout chrome'u (Frame, TopBar veya Navigation'a eşdeğer) içindeki sayfalardan bağımsız olarak taşımaktır, çünkü iki sistem arasındaki tutarsız boşluk belirteçleri hata ayıklanması zor olan görsel boşluklar oluşturur.

Çoğu uygulama için pratik bir sıra:

  1. İlk etkileşimsiz görüntü bileşenleri: <Badge>, <Banner>, <Icon>, <Text>. Bunların olay bağlantısı yoktur ve düşük risklidir.
  2. İşlem bileşenleri: <Button>, <Link>. Olaylar React onClick özelliklerinden yerel DOM olay dinleyicilerine değişir.
  3. Layout bileşenleri: s-page, s-section, s-layout. Boşluğun tutarlı olması için bir rout'un tüm layoutunu tek bir committe taşıyın.
  4. Kontrollü form alanları en son: s-text-field, s-select, s-checkbox. Bunlar React 19 ve olay yeniden bağlantılandırması gerektirir.
  5. App shell en son: Frame, AppProvider, Navigation. Diğer tüm Polaris React tüketicileri gittikten sonra bunları kaldırın.

Olay bağlantısı değişikliği

Bu taşıma sırasında hataların tek en büyük kaynağıdır. Polaris React React sentetik callback özelliklerini kullandı:

// Önce: Polaris React
<TextField value={val} onChange={(newVal) => setVal(newVal)} />

Polaris web bileşenleri durumu standart DOM olayları aracılığıyla iletişim kurar:

// Sonra: React 19 JSX ağacında Polaris web bileşeni
<s-text-field
  value={val}
  onInput={(e: Event) => setVal((e.currentTarget as HTMLInputElement).value)}
/>

e.currentTarget.value'ye, e.target.value'ye değil dikkat edin. Polaris web bileşenleri öğe referansının kendisine yaslanır, balon hedef değil. Bunu yanlış yapmak ilk değeri doğru okuyan ancak kullanıcı girdisinde hiçbir zaman güncellenmeyen alanlar üretir.

Bileşen eşleştirmesi: ne değişir ve ne eksiktir

Polaris ReactPolaris Web BileşeniNotlar
<Page><s-page>Başlık çubuğu App Bridge üzerinden admin chrome'a aktarıldı
<Card>s-card yok<s-section> veya compositions kütüphanesinden kart desenini kullanın
<DataTable><s-data-table>Mevcut; IndexTable'ın henüz doğrudan eşdeğeri yok
<Autocomplete>Henüz eşdeğer yokPolaris React'te kalın; her iki kütüphane birlikte çalışabilir
<Banner><s-banner>Mevcut
<Badge><s-badge>Mevcut
<Frame>KaldırıldıAdmin chrome'u App Bridge tarafından sahiplenildi
<Navigation><s-app-nav> (App Bridge)İframe dışında admin chrome'da yaşıyor
<AppProvider>Son Polaris React tüketiciden sonra kaldırınWeb bileşen eşdeğeri gerek yoktur

IndexTable'ı en sık yakalayan boşluk. Polaris React'te var ve yazı anında doğrudan s-* eşdeğeri yok. Önerilen geçici çözüm, başka her şeyi taşırken bu belirli ekranları Polaris React'te bırakmaktır. Shopify bu karma durumu açıkça destekler.

textAlign de s-paragraph ve s-heading adresinden web bileşenleri yeniden tasarımı sırasında kaldırıldı, bu da ortalı metin layoutlarını kırıyor. Sarmalayıcı öğesinde bunun yerine CSS ızgarası veya flexbox kullanın.

Adım 3: Shell'i kaldırın ve test edin

Her rota web bileşenleri üzerindeyken, AppProvider, Frame ve tüm Polaris React stil sayfalarını kaldırın. Sonra:

  • TypeScript katı modu çalıştırın ve sıfır kalan @shopify/polaris import yolunu doğrulayın.
  • Klavye gezintisini doğrulayın: s-* bileşenleri ARIA rollerini doğal olarak uygular, ancak modaller ve form akışlarında sekme sırasını kontrol edin.
  • Birden fazla viewport boyutunda test edin. s-page, eski Page'den dar genişliklerde farklı davranır.
  • Tarayıcı DevTools Shadow DOM müfettişini kullanarak stillerin bileşen içinden geldiğini ve artık hiçbir etkisi olmayan kendi geçersiz kılmalarınızdan değil, geldiğini doğrulayın.

Shopify ayrıca, React'ten Preact'e dönüşümün mekanik bölümlerini ve UI uzantıları için bileşen eşleştirmesini yönetilen bir AI Araç Takımı sağlar, resmi doçlar aracılığıyla Shopify Dev MCP sunucusu tarafından işaret edilir.

Adım 4: Polaris 2.0'ı benimseyin

Uygulamanız tamamen Polaris web bileşenleri üzerindeyken (Yol A veya Yol B'nin sonu), Polaris 2.0'a geçiş bir script etiketi güncellemesidir:

<!-- polaris-2.0-rc.js veya polaris-1.js adresinden şu adrese geçin: -->
<script src="https://cdn.shopify.com/shopifycloud/polaris-2.js"></script>

Ve package.json'da:

npm install @shopify/polaris-types@^2.0.0

React Router şablon uygulamaları için, @shopify/shopify-app-react-router'ı ^4.0.0 olarak arttırın, bu varsayılan olarak polaris-2.js yükler ve @shopify/polaris-types@^2.0.0'ı eş bağımlılıklarında ayarlar.

Yeni admin tasarımı özellik ön izlemesi etkinleştirilmiş bir geliştirme mağazasına karşı test edin. Bileşenler yeni vizyal stilini (yeni renk, tipografi, boşluk ve simgeler) yeniden tasarımı alan mağazalarda render eder ve henüz yeniden tasarımı almamış mağazalarda Polaris 1.1 görünümüne geri döner. Admin dışında bir yere render ederseniz, bileşenler varsayılan olarak yeni görsel stiline dönüştürülür.

UI uzantıları ile Uygulama Giriş Sayfası hakkında bir not

Bu gönderi Uygulama Giriş Sayfası gömülü uygulamalarına odaklanır. UI uzantıları (ödeme, müşteri hesabı, POS) ayrı bir taşıma yoluna sahiptir: React yerine Preact ile remote-dom'a taşıyorlar ve bundle bütçesi 64 KB gzip'te sıkıdır. Uzantılar CDN paketini kendileri yüklemeden Shopify admin tasarımını otomatik olarak alırlar. Uygulama Giriş Sayfası sayfaları ve UI uzantılarınız varsa, bunları ayrı taşıma projeleri ve ayrı zaman çizelgeleriyle ele alın. Zaman çizelgesi baskısı uzantılar üzerinde daha ağırırır: API sürümleri 2025-07 veya daha eski sürümlerdeki uzantılara sahip uygulamalar 1 Ekim 2026 itibariyle CLI güncellemelerinden zaten engellenmiştir.

Doğrulama denetim listesi

  • [ ] Ağ sekmesi tam olarak bir Polaris CDN isteğini gösteriyor, App Bridge'den sonra yükleniyor
  • [ ] @shopify/polaris-types sürümü CDN ana sürümüyle eşleşiyor (polaris-2.js için ^2.0.0)
  • [ ] polarisUrl, React Router uygulamaları için hem AppProvider hem de shopifyApp() içinde ayarlanıyor
  • [ ] Herhangi bir kontrollü s-* form alanı ağaca girmeden önce React 19 çalışıyor
  • [ ] Üretim rotalarında @shopify/polaris importu kalmıyor (grep ile doğrulayın)
  • [ ] .Polaris-* CSS geçersiz kılması kalmıyor (Shadow DOM üzerinden ulaşılamaz)
  • [ ] TypeScript katı modu s-* öğe referanslarında sıfır kapalı any ile geçiyor
  • [ ] Tüm modal ve form akışlarında klavye gezintisi test edildi
  • [ ] Yeni admin tasarımı özellik ön izlemesi etkinleştirilmiş geliştirme mağazası son onay için kullanıldı

Ekibinde Shopify geliştiricisi olmayan markalar bu işi Shopify mühendislik stüdyom Lintel'e getirebilir: özel Shopify uygulama geliştirme.

shopifypolarisweb-componentsembedded-appsapp-bridge

Sıkça sorulan sorular

Gömülü uygulamam hâlen çalışıyorsa Polaris web bileşenlerine taşımalı mıyım?

Polaris React kullanımdan kaldırıldı ve artık güncellemeler, güvenlik yamaları veya yeni bileşenler almaz. Şu anda çalışmaya devam edecek ancak Built for Shopify uygulamaları 1 Mayıs 2027'ye kadar yeni vizyal stile uyum sağlamalıdır ve kullanımdan kaldırılan kütüphanede yeni bileşenler veya hata düzeltmeleri alamazsınız. Taşımaya şimdi başlamak, acil bir yazılım yeniden yazılımı gerektirmeden bunu yapmanız için zaman verir.

Polaris web bileşenlerini React dışındaki frameworklerle kullanabilir miyim?

Evet. Polaris web bileşenleri Web Bileşenleri standardının üzerine inşa edilir ve framework-agnostik özel öğelerdir. Bunları React 19, Preact, Vue, düz JavaScript veya hiçbir framework olmadan kullanabilirsiniz. Tek React-spesifik gereklilik, React state tarafından yönetilen kontrollü form alanlarına ihtiyacınız varsa React 19 veya daha yeni sürümüdür.

CDN üzerinde polaris.js, polaris-1.js ve polaris-2.js arasındaki fark nedir?

polaris.js, Polaris 1.x'i takip eden ve hiçbir zaman 2.x sunmayacak olan eski versiyonsuz URL'dir. polaris-1.js en son kararlı 1.x sürümünü sunar. polaris-2.js en son kararlı 2.x sürümünü sunar ve web bileşenlerine taşındıktan sonra önerilen üretim hedefidir. Yeni ana sürümü benimsemek için script etiketini açıkça değiştirmeniz gerekir.

Yedi yıllık Shopify, tek sayfada.

Roller, projeler, teknoloji yığını ve sertifikalar özgeçmişte.

Özgeçmiş PDF indir LinkedIn