Hydrogen 2026-10, 14 Ekim 2026'da genel olarak kullanıma sunuldu ve asıl haber şudur: artık bir framework değildir. Zaten kullandığınız herhangi bir JavaScript framework'ünün içine attığınız bir kütüphanedir. Bu tek mimarî değişim, başsız bir vitrinde "uygulama entegrasyonu" ne anlama geldiğini değiştirir ve cevap altı ay önce olduğundan çok daha makul hale gelmiştir.
Ana çıkarımlar
@shopify/hydrogen@2026.10.x, Storefront API ve Customer Account API sürüm 2026-10'a sabitlenir; en az Ekim 2027'ye kadar en son kararlı sürüm.- Hydrogen artık framework-agnostik bir kütüphanedir: React Router ve Next.js başlangıç şablonları kutudan çıkar ve Vue bağlamaları Temmuz 2026'da geliştirici ön izlemesine indi.
ShopifyScripts, eski komut dosyası etiketlerinin yerini alır; bunlar 1 Ekim 2026'dan beri yazılı kilitli ve 1 Mart 2027'de tamamen enjekte olmayı durdurur.- Evrensel Ticaret Protokolü (UCP) iş profili,
handleShopifyRoutestarafından otomatik olarak sunulur ve vitrininizi Shopify'ın ajanla çalışan katmanına hiçbir özel kod olmadan bağlar. - Tema uygulama uzantılarına dayanan uygulamalar, başsız bir vitrinde otomatik olarak hala render edilmez; özel vitrini entegrasyonunu açığa çıkaran uygulamalara ihtiyacınız var ya da onları kendiniz bağlarsınız.
@shopify/hydrogen@2026.10.0'da gerçekten neler değişti
Framework dönüşü
Bu sürümden önce, klasik Hydrogen, React Router'ın üstüne yerleştirilmiş tam yığın bir framework'tü. Hydrogen'ın yazılı sepet yardımcılarını ya da analitik ilkellerini istiyorsanız, tüm framework'ü benimsemeniz gerekiyordu. Bu kısıtlama ortadan kalkmıştır.
2026-10 paketi, yazılı Storefront API istemcisi, handleShopifyRoutes, sepet sunucu işleyicileri, tahmine dayalı arama, analitikler, onay, Shop Pay ve Müşteri Hesabı desteğini düz bir kütüphane olarak gönderir. İhtiyacınız olanı içeri aktarırsınız. React ve Vue bağlamaları ayrı giriş noktaları aracılığıyla dahil edilir (@shopify/hydrogen ve @shopify/hydrogen/vue). Next.js başlangıç şablonu Vercel tarafından React Router şablonunun yanı sıra korunur.
Mevcut bir Hydrogen (Remix/React Router) projeniz varsa, migrate-to-hydrogen-2026-10 adında paketlenmiş bir aracı becerisi paketle birlikte gönderilir ve bir kodlama aracını adım adım geçişten geçirir. hydrogen skills sync'i çalıştırarak projenize çekin.
Hareket etmeniz gereken önemli değişiklikler
2026-10 penceresindeki dört değişiklik, 2026-04'ten yükseltme yapıyorsanız kod güncellemesi gerektirir:
- Zorunlu Storefront API proxy'si.
proxyStandardRoutesseçeneği, Nisan 2026 sürümünde (v2026.4)createRequestHandler'dan kaldırılmıştır. Proxy artık her zaman açıktır. Yük bağlamınız birstorefrontörneği içermezse, istek işleyici uyarı günlüğü yerine atış yapar.createHydrogenContext()kullanırsanız, zaten uyumlursunuz.
- Sepet rotası karışık mutasyonları reddeder. Ekim 8 geliştirici ön izlemesi itibarıyla (şimdi 2026.10.0'a birleştirilmiş), sepet rotası satır değişikliklerini, indirim kodlarını, öznitelikleri ve not değişikliklerini tek bir çağrıda karışan JSON isteklerini reddeder. Her tür ayrı bir istek olmalıdır. Hydrogen'ın kendi sepet formları zaten bu deseni izler; elle yazılan sepet getirme çağrıları burada kırılır.
_shopify_yve_shopify_sçerezleri kaldırıldı.ShopifyScriptsartık bu eski JavaScript'e görünür çerezleri oluşturmaz ya da yenilemez. Onları doğrudan JavaScript'ten okuyan herhangi bir uygulama ya da analitik hedefi,ShopifyScripts'in şimdiwindow.Shopify.analyticsaracılığıyla ortaya koyan onay ve analitik API'lerine geçiş yapması gerekir.
product_viewedfiyat şekli değişti. Olay artık tam fiyat nesnesini{ amount, currencyCode }alır, miktar dizesi yerine. Daha öncevariant.price.amountgeçtiğiniz yerevariant.pricegeçirin. Analitik hedefler tutarsak doğrudan tutarı ayırırlarsa güncelleme gerekir.
// 2026-10 öncesi
Shopify.analytics.publish('product_viewed', {
price: variant.price.amount, // string
});
// 2026-10+
Shopify.analytics.publish('product_viewed', {
price: variant.price, // { amount, currencyCode }
});
Storefront API 2026-10: temel API'nin eklediği şey
Hydrogen 2026-10, Storefront API ve Customer Account API'nin her ikisinin de 2026-10 sürümlerini kullanır. Bu API sürümündeki iki ekleme, vitrini sorgusu yazarlarına doğrudan önemli:
@inContext,channelIdkazanır.@inContextyönergesi artık isteğe bağlı birchannelIdbağımsız değişkenini kabul eder; bütün sorgu genelinde satış kanalının bağlamını (kanal özgü ürün kullanılabilirliği ve fiyatlandırma dahil) uygular. Headless kanal aracılığıyla bağlı başsız vitrinler için, bu hangi kanalın fiyatlandırma kurallarının uygulanacağı konusunda açık olabileceğiniz anlamına gelir; kapalı varsayılanlar yerine.
- İşlevler teslim seçeneklerinden metaalan okuyabilir. Teslimat Özelleştirme İşlevleri artık giriş sorgusu içindeki
CartDeliveryOptionüzerindemetafield(namespace:, key:)öğesini çağırabilir. Daha önce, taşıyıcıya özgü verilere ihtiyaç duyan bir İşlev, onu seçenek başlığından ayırmak zorundaydı. Şimdi taşıyıcı hizmeti ya da teslimat seçeneği üreteci, yapılandırılmış verileri metaalan olarak ekleyebilir ve İşlev bunu doğrudan okur.
Başsız sayfada uygulama entegrasyonu sorunu: neler değişti ve değişmedi
Bu, çoğu başsız post'un üzerinden atladığı bölümdür, bu yüzden spesifik olacağım.
Shopify App Store aracılığıyla kurulu uygulamalar, vitrininiz açısından iki kampa ayrılır:
| Uygulama türü | Vitrini arayüzünü nasıl ekler | Hydrogen'da çalışır mı | Ne yapmanız gerekir |
|---|---|---|---|
| Yalnızca arka uç (siparişler, envanter, yerine getirme) | Vitrini yüzeyi yok | Evet, hiçbir şey değişmez | Hiçbir şey yapma |
| Tema uygulama uzantısı (uygulama blokları, uygulama gömme) | Online Store 2.0 tema yuvaları içine render edilir | Hayır, bloklar otomatik render edilmez | Uygulamanın özel vitrini API'sini kullan ya da kendi entegrasyonunu yap |
| Web pixel / analitik uygulaması | Web Pixels API aracılığıyla harekete geçer | Evet, pixeller vitrini türünden bağımsız olarak ateşlenir | Olay adlarının yeni fiyat şekliyle eşleştiğini doğrula |
| Komut dosyası etiketi (eski) | JavaScript'i vitrini <head>'e enjekte eder | Son tarih geçti: 1 Ekim 2026'da yazılı kilitli | Uygulama 1 Mart 2027 tarihine kadar gömme bloğa ya da web pixel'e taşınmalı |
| Storefront API erişimi olan uygulamalar | Vitrinin çağırdığı GraphQL uç noktalarını ortaya çıkarır | Evet, fakat kendin sorgulamalısın | GraphQL çağrılarını yaz; otomatik bağlantı yok |
Komut dosyası etiketi güneşi karşıdan başsız tüccarlar için bu tablodaki en yıkıcı çizgidir. Uygulamalar 1 Ekim 2026'dan beri herhangi bir API sürümünde vitrini komut dosyası etiketi oluşturamaz ya da güncelleyemez. Mevcut etiketler 1 Mart 2027'ye kadar yüklenmeye devam eder, ardından Shopify onları tamamen enjekte etmeyi durdurur. Tema uygulama uzantısı gömme bloğuna ya da web pixel'e taşınmayan uygulamalar, bu tarihte sessizce çalışmayı durdurur.
Başsız vitrin için, tema uygulama uzantıları, güneş ayetine bakılmaksızın irrelevant kalır. Önemli olan yüklenmiş uygulamalarınızın özel vitrini entegrasyonunu ortaya çıkarması ya da doğrudan sorgulayabileceğiniz genel Storefront API uç noktasını ortaya çıkarmasıdır.
ShopifyScripts uygulama bağlantısı hikayesini nasıl değiştirir
Bileşen (ya da bağlamalar olmayan çerçeveler için getShopifyScriptTags()), başsız vitrin üzerindeki Shopify tarafından yönetilen komut dosyaları için yeni montaj noktasıdır. 2026-10'da şunları işler:
- Vitrini analitikleri ve onayı (çerçeve hidrasyon öncesinde
window.Shopify.analyticsolarak analitik otobüsü satır içi) - Shopify Inbox:
inbox: trueekle ve<shopify-chat />al ve yapay zeka destekli sohbet penceresini al - Shop Pay ve müşteri hesabı web bileşenleri, 2026.10.0'da eklenen
account: truebayrağı aracılığıyla - UCP keşfi:
ShopifyScriptsartık<head>'e bir<link rel="ucp" href="/.well-known/ucp">etiketi render eder vehandleShopifyRoutesyönetilen iş profilini bu yolda sunar
Pratik çıkarım: standart sepet olayları sözleşmesini kullanan herhangi bir uygulama ya da ajan (window.Shopify.actions.updateCart, vb.) Hydrogen vitrininizde sıvı temada çalıştığı gibi çalışır; her iki yüzey de aynı standart eylemleri uygular. Burası gerçek eşitlik hikayesidir, tam uygulama uyumluluğu değil.
Başsız vitrinde UCP ve ajanla çalışan ticaret
handleShopifyRoutes 2026-10'da, çağrı yoluyla doğrulanan UCP MCP isteklerini /api/ucp/mcp'dan yapılandırılmış Shopify mağazasına proxy'ler ve UCP /buy/{items} bağlantılarını mevcut /cart/{items} el değişimiyle birlikte iletir. Bu, Evrensel Ticaret Protokolü üzerinde işletilen alışveriş ajanlarının kendi etki alanınız aracılığıyla başsız mağazanıza ulaşması anlamına gelir; myshopify.com'a atlama yerine. Hiçbir şey yapılandırmazsınız; handleShopifyRoutes'le birlikte gönderilir.
Geçiş denetim listesi: 2026-04 Hydrogen projesini yükseltme
2026-10'a geçmeden önce doğrulanması gereken sıralı şeyler listesi şu şekildedir:
createHydrogenContext()'in yük bağlamınızı oluşturduğunu onaylayın. Yaparsa, zorunlu proxy değişikliğinin sizin üzerinizde hiçbir etkisi yoktur.- Elle yazılan sepet getirme çağrılarını denetleyin. Satır, indirim, öznitelik ya da not işlemlerini karışan herhangi bir
fetch('/api/cart', { body: JSON.stringify({ ... }) })çağrısı bulun ve bölün. - Analitik yayın çağrılarında
variant.price.amountarayın.variant.priceile değiştirin. _shopify_yya da_shopify_sokumalarını arayın. Silin; bunun yerine analitik otobüsü ya da onay API'sini kullanın.cartDiscountCodesUpdatemutasyonunu kontrol edin. Ocak 2026 sürümü (v2026.1)discountCodesbağımsız değişkenini gerekli hale getirdi. Ön-2026-01'den sıçrıyorsanız, mutasyonlarınızın içerdiğini doğrulayın.npx @shopify/hydrogen@latest setupya dahydrogen skills syncçalıştırın ve kodlama aracınızımigrate-to-hydrogen-2026-10becerisi çalıştırmasını isteyin; rehberli geçişi istiyorsanız.- Kurulu uygulama listesini gözden geçirin. Vitrini arayüzünü enjekte eden her uygulamayı işaretleyin ve ya bir Storefront API uç noktasına sahip olduğunu ya da özel vitrini desteklediğini doğrulayın. Yalnızca komut dosyası etiketi uygulamalarının 1 Mart 2027'ye kadar süresi vardır.
Ortak uygulama türlerini Hydrogen vitrinine bağlama yaklaşımları
Burada, uygulamaya yapılan her istek ölçülebilir gecikme maliyeti olan 10.000+ SKU'ya sahip mağazalara dayalı olarak pratikte çalışan şeydir:
- Ürün incelemeleri. Çoğu inceleme uygulaması genel bir Storefront API metaalan ad alanı ya da bir REST uç noktasını ortaya çıkarır. Ürün rotası yükleyicide sunucu tarafında sorgu yapın ve verileri prop olarak geçin. Uygulamanın komut dosyası penceresi widget'ını yüklemeyin; artık yüklemez ve her zaman render bloğlayan bir sorumluyduk.
- Sadakat ve ödüller. Bunlar neredeyse her zaman arka uç uygulamalarıdır (siparişler, müşteriler). Değişmeden çalışırlar. Vitrini entegrasyonu, hesap rotanızdan API'sinden sorguladığınız bir puan görüntüsüdür.
- Canlı sohbet (Inbox olmayan). Satıcı komut dosyasını
ShopifyScripts'inextraScriptsaracılığıyla ya da kök düzeni içinde doğrudan yüklersiniz. Tema uygulama uzantısı yok. - Satış artırma / çapraz satış uygulamaları; checkout arayüz uzantılarını kullananlar. Checkout arayüz uzantıları, vitrinin türünden bağımsız olarak Shopify'ın barındırılan check-out penceresinde çalışır. Başsız gitmekten etkilenmez.
- Arama ve mal hizmetleri uygulamaları. Bunlar kendi API'sini ortaya çıkarır. Koleksiyon rotanızdaki Storefront API
productssorgusunu uygulamanın arama uç noktasıyla değiştirin. Swap tek yükleyici işlevindedir.
Başsız ön ucu sahip olmanın maliyeti ve bakımı yönü hakkında daha derin bir yürüyüş için, bu bloga zaten bağlı başsız maliyet dökümesine bakın.
Yükseltmenin çalıştığını doğrulama
2026.10 dağıttıktan sonra birkaç hızlı denetim:
# Paket sürümünü doğrula
npm ls @shopify/hydrogen
# UCP profilinin sunulup sunulmadığını kontrol et
curl -s https://your-storefront.com/.well-known/ucp | head -20
# HTML'de UCP bağlantı etiketini doğrula
curl -s https://your-storefront.com/ | grep 'rel="ucp"'
# Dev'de analitik otobüsünü izle
# Tarayıcı konsolunu aç, sonra:
window.Shopify.analytics # React hidrasyon öncesinde tanımlı olmalı
Shopify Events inceleyicide (geliştirme yapıları içinde ShopifyScripts yapılandırıldığında kullanılabilir), shopify:page:view'ün ilk yükte ve her istemci tarafı gezintisinde ateşlendiğini doğrulayın. Temmuz 2026 ön izleme döngüsündeki ShopifyScripts analitik çalışmasından önce, Hydrogen vitrini, analitik araçlandırmasına tek sayfa yükü gibi görünüyordu. 2026-10 ile, bir sıvı tema gibi sayfa sayfa rapor eder.
@inContext(channelId: "...") eklenmesi, kanal özgü fiyatlandırma kullanırsanız açıkça doğrulanmaya değer. Aynı ürünü bağımsız değişkenle ve olmadan sorgu yapın ve priceV2 değerleri dif yaparak kanal bağlamının uygulanıp uygulanmadığını doğrulayın.
Hydrogen 2026-10, en büyük benimseme engelini (framework kilitleme) kaldırırken, uygulamaların ve ajanların bağlı oldukları sözleşmeleri sıkılaştırdığı için anlamlı bir sürümdür. Uygulama entegrasyonu sorunu, kütüphanenin kendisi tarafından çözülemez; hangi yüzeyi her uygulamanın kullandığını anlamak ve o yüzeyde onunla buluşmak tarafından çözülür. 1 Mart 2027'de komut dosyası etiketi son tarihi yakın dönem baskı noktasıdır. Diğer her şey zamanlanabilecek bir geçiştir.
Bunu şirket içinde yapmak yerine yaptırmak isterseniz, yönettiğim stüdyo Lintel bu tür projeler için headless Shopify ve Hydrogen geliştirme sunuyor.
Sıkça sorulan sorular
Hydrogen 2026-10'a yükseltmek, React Router üzerinde inşa edilmiş mevcut bir Hydrogen vitrini kırar mı?
Otomatik olarak değil fakat yapmanız gereken kod düzeyi değişiklikleri var. Storefront API proxy'si şimdi zorunlu ve depo bağlamı eksikse atış yapar. Sepet rotası tek bir istekte karışık tür mutasyonlarını reddeder. Analytics olay şekilleri product_viewed için değişti. migrate-to-hydrogen-2026-10 becerisini hydrogen skills sync aracılığıyla çalıştırın; rehberli bir yol için.
Tema uygulama uzantıları kullanan Shopify uygulamaları, başsız vitrinde çalışır mı?
Hayır, tema uygulama uzantısı blokları, başsız vitrinde otomatik olarak render edilmez. Storefront API uç noktasını ortaya çıkaran ya da özel vitrini entegrasyonunu ortaya çıkaran uygulamalara ihtiyacınız var ya da entegrasyonu uygulamanın API'sini kullanarak kendiniz oluşturursunuz. Yerine getirme ya da envanter uygulamaları gibi arka uç uygulamaları etkilenmez.
Shopify komut dosyası etiketleri için son tarih nedir ve uygulamalar bunun yerine ne kullanmalı?
1 Ekim 2026'dan beri, uygulamalar herhangi bir API sürümünde vitrini komut dosyası etiketi oluşturamaz ya da güncelleyemez. Mevcut etiketler 1 Mart 2027'de enjekte olmayı durdurur. Uygulamalarınız vitrini arayüzü için komut dosyası etiketlerini kullanıyorsa, tema uygulama uzantısı gömme bloğuna ya da analitik izleme için web pixel'e geçiş yapmak için yaklaşık 4 aylık süreniz var.