Cloudflare Workers’ta bir Node.js paketinin çalışması, yalnız ihtiyaç duyduğu API’nin bulunmasına bağlı değil. Paket; ES modülünü nasıl çözdüğünüzü, require() davranışını, JSON içe aktarma kurallarını ve aynı yerleşik modülün tek örnek olarak önbelleğe alınıp alınmadığını da varsayar. Cloudflare’ın 9 Eylül 2026’da duyurduğu yeni modül kayıt defteri tam olarak bu görünmeyen katmanı Node.js’e yaklaştırıyor.
Gelişme iki ayrı değişiklik içeriyor ve bunları karıştırmamak önemli. Workers’ın sunucusuz kullanımda anlamlı kararlı Node.js API’leri artık varsayılan olarak açık. Buna karşılık yeni kayıt defteri otomatik açılmıyor; new_module_registry uyumluluk bayrağını açıkça eklemek gerekiyor. Cloudflare henüz bir varsayılan açılış tarihi de vermedi. Dolayısıyla doğru yaklaşım, canlı uygulamanın ayarını körlemesine değiştirmek değil, aynı kodu yeni kayıt defteriyle test edip davranış farklarını ölçmek.
Modül kayıt defteri neden önemlidir?
Bir JavaScript uygulamasında import satırını gördüğümüzde çoğu zaman yalnız dosya yolunu düşünürüz. Çalışma zamanı ise modül tanımlayıcısını ayrıştırır, hedefi bulur, ESM veya CommonJS olduğunu belirler, derler ve daha sonra aynı hedef çağrıldığında doğru örneği döndürür. Node.js paketleri bu ayrıntılara dayanabildiği için API uyumluluğu tek başına yeterli olmaz.
Cloudflare, workerd içindeki kayıt defterini daha hızlı, standartlara daha uygun ve Node.js davranışına daha yakın olacak biçimde yeniden yazdığını söylüyor. Yeni düzen import.meta.url, import.meta.main ve import.meta.resolve() desteği getiriyor; sorgu dizeleri ile parçaları gerçek URL kurallarıyla çözüyor. node: önekiyle erişilen yerleşik modüller hangi yoldan çağrılırsa çağrılsın aynı örneğe bağlanıyor. JSON içe aktarma nitelikleri doğrulanıyor ve bir ES modülünde require() kullanımı Node.js kurallarını izliyor.
Bu ayrıntılar, özellikle npm paketini yerelde Node.js ile test edip Workers’a taşıyan ekipler için değerli. Daha az uyumluluk yaması, daha az “lokalde çalışıyor, edge’de bozuluyor” sürprizi demek. Ancak bir uyumluluk bayrağı davranış değişikliği yaratabilir; otomatik kazanç gibi ele alınmamalı.
64 MiB sınırı neyi değiştiriyor?
Cloudflare aynı duyuruda tüm planlarda Workers uygulamalarının 64 MiB’a kadar çıkabildiğini ve sıkıştırılmış paket boyutu sınırının kaldırıldığını belirtiyor. Bu sayı, her projeyi büyütmek için hedef değil. Daha büyük bir paket; yükleme, inceleme ve bağımlılık riskini de büyütebilir. Fakat kapsamlı Node.js kütüphaneleri, WebAssembly modülleri veya çok sayıda üretim bağımlılığı kullanan uygulamalar için daha önceki paketleme baskısını azaltabilir.
Burada iki metriği ayrı izleyin: dağıtıma gönderilen toplam boyut ile ilk istekte gerçekten derlenen modüller. Yeni kayıt defteri modülleri ilk içe aktarıldıklarında tembel biçimde derleyebiliyor. Bu, büyük modül ağlarında başlangıç davranışını iyileştirebilir; yine de ölçülmeden performans vaadi sayılmaz. Cloudflare’ın DNS önbellek optimizasyonunu incelerken olduğu gibi, mimari açıklamayı kendi gecikme ve hata verinizle sınamak gerekir.
Yeni kayıt defterini güvenli biçimde nasıl test edersiniz?
1. Üretim kopyasıyla başlayın
Aynı kaynak kodunu ayrı bir ön izleme Worker’ına dağıtın. Ortam değişkenleri ve harici hizmetler üretimden ayrılmış olsun. compatibility_flags listesine yalnız bu ortamda new_module_registry ekleyin. Eski ve yeni kayıt defterini aynı gün, aynı test girdileriyle karşılaştırın.
2. Modül davranışını doğrudan sınayın
- ESM ve CommonJS giriş noktalarının ikisini de çağırın.
- Dinamik
import(),require(esm)ve JSON içe aktarmalarını ayrı test edin. import.meta.resolve()sonucunun beklediğiniz URL’ye çıktığını doğrulayın.- Sorgu dizesi veya parça kullanan modül yollarınız varsa önbellek davranışını ölçün.
- WebAssembly kullanıyorsanız kaynak aşaması içe aktarmasını gerçek dosyanızla deneyin.
3. Hata sınıflarını da karşılaştırın
Yalnız başarılı isteklere bakmayın. Bilerek eksik bir modül, yanlış JSON niteliği ve desteklenmeyen yol çalıştırın. Hata türü, mesajı ve iz kaydı gözlem sisteminizde doğru gruplanıyor mu kontrol edin. Alarm kuralı belirli bir eski hata metnine bağlıysa, gerçek sorun çözülse bile izleme sessiz kalabilir.
4. Geri dönüş yolunu yazılı tutun
Bayrağı kaldırarak eski davranışa dönebileceğinizi dağıtım prosedürüne ekleyin. Canlıya çıkmadan önce bu geri dönüşü ön izleme ortamında bir kez uygulayın. npm trusted publishing akışında olduğu gibi, dağıtım güvenliği yalnız yeni ayarı açmak değil, geri dönüşün de kanıtlanmasıdır.
5. Bağımlılık envanterini kaydedin
Test ettiğiniz paket kilidi, Wrangler sürümü ve uyumluluk tarihini sonuçla birlikte saklayın. Bir hafta sonra gelen küçük bağımlılık güncellemesi aynı modül yolunu farklı biçimde paketleyebilir. Başarılı ön izleme sonucunu yalnız kaynak commit’iyle değil, kilit dosyası ve dağıtım yapılandırmasıyla eşleştirin. Böylece sorun çıktığında kayıt defterinin mi, paketleyicinin mi yoksa yeni bir bağımlılığın mı davranışı değiştirdiğini ayırabilirsiniz.
Türkiye’deki küçük ekip için karar ölçütü
Bir ajans veya SaaS ekibi için en iyi aday, Node.js uyumluluk yaması taşıyan ama iş etkisi sınırlı bir Worker’dır. Önce bu uygulamada deneyin; hata oranı, p95 gecikme, soğuk başlangıç ve paket boyutunu kaydedin. En az bir iş günü normal trafik benzeri test koşturun. Sırf 64 MiB’a izin veriliyor diye bağımlılık temizliğini bırakmayın; kullanılmayan paketleri kaldırmak hâlâ güvenlik ve bakım avantajı sağlar.
Özetle yeni kayıt defteri, Workers’ı Node.js paket ekosistemine daha yakınlaştıran önemli bir temel değişiklik. Fakat bugün için açıkça seçilen bir uyumluluk bayrağıdır. Doğru geçiş planı; ön izleme, davranış testi, gözlem ve geri dönüş kanıtından oluşur.
