htmx 4.0: Neler Bozuluyor ve Sürüm Sizi Bozmamak İçin Ne Yapıyor?

htmx 4.0.0, ekibin sekiz aylık çalışma olarak tanımladığı sürecin ardından 28 Ağustos'ta yayınlandı. Öne çıkan değişiklikler gerçekten önemli: attribute kalıtımı artık isteğe bağlı (opt-in), event isimleri yeni bir şemaya geçti, history artık sayfaları localStorage içinde önbelleğe almıyor ve iç yapı XMLHttpRequest'ten fetch()'e taşındı. Yine de benim dikkatimi asıl çeken, sürümün ne kadar özenle aşamalandırıldığı oldu.

Neler değişti#

Duyuruya göre kullanıcı açısından htmx 4, htmx 2 ile neredeyse aynı. Üç büyük değişiklik var:

• Kalıtım artık açık. htmx 2'de üst elemandaki hx-confirm gibi bir attribute alt elemanlara da uygulanıyordu. htmx 4'te bunu bir sonekle açıkça belirtmeniz gerekiyor: hx-confirm:inherited="Are you sure?". Artık gerek kalmadığı için hx-disinherit kaldırıldı. Ekip, yükseltmedeki en büyük yükün bu olduğunu söylüyor.
• Event'ler htmx:phase:action düzenini izliyor. htmx:beforeRequest, htmx:before:request oluyor; htmx:afterSwap, htmx:after:swap oluyor. Hata event'lerinin çoğu tek bir htmx:error altında toplanıyor, HTTP hataları ise htmx:response:error tetikliyor. htmx:xhr:* ve htmx:validation:* event'leri kaldırıldı.
• History sayfayı yeniden çekiyor. Geri gidildiğinde htmx sayfayı yeniden fetch ediyor ve <body> içine swap ediyor. Eski localStorage snapshot'ı, üçüncü parti script'lerin yaptığı DOM değişikliklerini de saklayabiliyordu; oysa geri yüklemeden sonra bu script'lerin mantığı ortada olmuyordu. Önbelleklemeyi hâlâ istiyorsanız hx-history-cache extension'ı sessionStorage üzerinden geri yükleme yapıyor.

Yenilikler tarafında ise yerleşik morph swap'lar (idiomorph tabanlı innerMorph ve outerMorph) ve tek bir yanıttan birden fazla elemanı hedefleyen <hx-partial> etiketi var. Bu etiket, out-of-band swap'lara göre daha anlaşılır bir alternatif olarak sunuluyor.

Sessizce bozulan değişiklikler#

What's New in htmx 4 rehberi, duyurudakinden daha fazla breaking change listeliyor. Bunlarda gözle görülür bir şey kırılmıyor; uygulama sadece farklı davranmaya başlıyor:

• htmx 4, 204 ve 304 dışındaki tüm HTTP yanıtlarını swap ediyor. Sunucunuz 422 veya 500 ile bir HTML hata sayfası dönüyorsa, bu sayfa artık hedef elemanın içine düşüyor. htmx 2, 4xx ve 5xx yanıtlarını swap etmiyordu.
• Varsayılan timeout artık 60 saniye. htmx 2'de hiç timeout yoktu.
• hx-delete artık kapsayan formun input'larını dahil etmiyor. Rehberin önerdiği çözüm hx-include="closest form".
• Out-of-band elemanlar artık ana içerikten önce değil, sonra swap ediliyor.
• hx-disable, hx-ignore oluyor; hx-disable ise artık eskiden hx-disabled-elt'nin yaptığı işi yapıyor. Rehber, hx-disable yeniden adlandırmasını yükseltmeden önce ve hx-disabled-elt'yi yeniden adlandırmadan önce yapmanızı söylüyor.

Duyuru sayfasındaki örnek upgrade checker çıktısı en sinsi durumu gösteriyor. Üst elemanda CSRF token taşıyan bir hx-headers attribute'u, :inherited olmadan artık alt elemanlara ulaşmıyor ve sunucu isteği reddediyor. Log'larınızda bu büyük ihtimalle bir htmx sorunu gibi değil, bir CSRF ya da yetkilendirme sorunu gibi görünecek.

Yayın mekaniği örnek alınmaya değer#

• latest 2.x'te kalıyor. 4.0 serisi, 2027'nin başlarındaki bir tarihe kadar npm'de next olarak etiketleniyor; çünkü ekip, htmx'i versiyonsuz CDN URL'lerinden yükleyenleri zorla yükseltmek istemiyor.
• Sürümle birlikte bir kontrol aracı geliyor. npx [email protected] upgrade-check -- ./templates eksik :inherited soneklerini, yeniden adlandırılmış ve kaldırılmış attribute'ları, eski event isimlerini ve kaldırılmış API çağrılarını dosya ve satır numarasıyla raporluyor.
• En riskli davranış değişiklikleri geri alma ayarlarıyla geliyor. htmx.config.implicitInheritance = true, htmx.config.noSwap = [204, 304, '4xx', '5xx'] ve htmx.config.defaultTimeout = 0; bunlara ek olarak htmx 2 varsayılanlarını ve event isimlerini geri getiren bir htmx-2-compat extension'ı var. fetch() geçişinin geri alınamayacağı açıkça belirtilmiş. Rehberde out-of-band sıralama değişikliği için bir ayar listelenmiyor.
• htmx 2 süresiz olarak destekleniyor, dolayısıyla bir son tarih baskısı yok.
• LLM'ler için bir upgrade skill'i var: rehberlik ve debugging skill'lerinin yanında htmx-upgrade-from-htmx2.

Hepsini bir araya koyunca bir ekip, breaking change'lerin tam listesini bilen bir araçla, davranışları tek tek taşıyabiliyor. Kendi paketlerimde, örneğin NuGet'teki Meridian'da, ileride breaking bir sürüm çıkarmayı düşündüğümde ilk kopyalayacağım iki fikir bu kontrol aracı ve davranış bazlı ayarlar olur. Changelog insanlara neyin değiştiğini söyler. Kontrol aracı ise bunun kodlarında nereye dokunduğunu gösterir.

Pazartesi neyi kontrol ederdim#

Bir ekip htmx 2 kullanıyorsa listem şu:

1. Versiyonsuz htmx script URL'lerini bulun ve tam bir sürüme sabitleyin. latest şimdilik güvenli, ama yalnızca 2027'nin başlarına kadar.
2. Kontrol aracını bir branch üzerinde çalıştırın. Varsayılan tarama .html, .php, .js, .ts, Jinja, ERB ve Handlebars dosyalarını kapsıyor. Razor view'ları veya diğer template türleri için --ext gerekiyor, örneğin --ext .cshtml.
3. 4xx veya 5xx durumunda HTML dönen her endpoint'i listeleyin ve ne olması gerektiğine karar verin: bunu swap edilecek içerik olarak tasarlayın, hx-status:422="swap:innerHTML target:#errors" ile status bazında yönlendirin ya da noSwap ile eski davranışı koruyun.
4. JavaScript kodunuzda eski event isimlerini grep'leyin. Kontrol aracı hx-on attribute'larına ve yapabildiği ölçüde script'lere bakıyor, ama özel event bağlantıları için elle bir tur geçmek gerekiyor.
5. Export ve raporlar gibi, yeni 60 saniyelik varsayılan timeout'tan uzun sürebilecek yavaş istekleri tespit edin.

Benim yorumum#

htmx 4 makul bir major sürüm, ama asıl ders yayın mühendisliğinde. latest'i eski seride tutmak, bir kontrol aracı sunmak ve en riskli davranış değişikliklerine kendi geri alma ayarlarını vermek, tek bir riskli migrasyonu birkaç küçük adıma bölüyor. Üstelik htmx 2 süresiz desteklendiği için çoğu ekip için doğru ilk adım yükseltme değil. İlk adım sürümü sabitlemek ve kontrol aracını çalıştırmak, ardından yükseltmeyi planlamak.