Workbox v5'ten v6'ya geçiş

Bu kılavuzda, Workbox 5'ten 6'ya geçiş yaparken yapmanız gereken değişikliklere örnekler verilerek Workbox 6'da yapılan önemli değişiklikler ele alınmaktadır.

Zarar Veren Değişiklikler

çalışma kutusu çekirdek

workbox-core içindeki skipWaiting() yöntemi artık bir install işleyicisi eklemeyecek ve yalnızca self.skipWaiting() çağrısına eşdeğer olacak.

skipWaiting(), Workbox v7'de kaldırılacağından bundan sonra bunun yerine self.skipWaiting() kullanın.

workbox-precaching

  • HTTP yönlendirmesine karşılık gelen URL'ler için çapraz kaynaklı HTML dokümanları artık workbox-precaching ile gezinme isteğini karşılamak için kullanılamaz. Bu senaryo genellikle nadirdir.
  • Belirli bir istek için önceden önbelleğe alınmış bir yanıt aranırken fbclid URL sorgu parametresi artık workbox-precaching tarafından yoksayılıyor.
  • PrecacheController oluşturucusu artık parametre olarak bir dize yerine belirli özelliklere sahip bir nesneyi alır. Bu nesne şu özellikleri destekler: cacheName (v5'te oluşturucuya iletilen dizeyle aynı amaca hizmet eder), plugins (v5'ten addPlugins() yöntemini değiştirerek) ve fallbackToNetwork (v5'te createHandler() öğesine ve "createHandlerBoundToURL()" öğesine iletilen benzer seçenek yerine).
  • PrecacheController öğesinin install() ve activate() yöntemleri artık tam olarak bir parametre alıyor. Bu parametre, sırasıyla karşılık gelen InstallEvent veya ActivateEvent değerine ayarlanmalıdır.
  • addRoute() yöntemi PrecacheController'dan kaldırıldı. Onun yerine, yeni PrecacheRoute sınıfını daha sonra kaydedebileceğiniz bir rota oluşturmak için kullanabilirsiniz.
  • precacheAndRoute() yöntemi PrecacheController yönteminden kaldırıldı. (workbox-precaching modülü tarafından dışa aktarılan statik bir yardımcı yöntem olarak hâlâ mevcuttur.) Bunun yerine PrecacheRoute kullanılabilir olduğu için kaldırıldı.
  • createMatchCalback() yöntemi PrecacheController'dan kaldırıldı. Bunun yerine yeni PrecacheRoute kullanılabilir.
  • createHandler() yöntemi PrecacheController'dan kaldırıldı. Bunun yerine, istekleri işlemek için PrecacheController nesnesinin strategy özelliği kullanılabilir.
  • createHandler() statik dışa aktarma işlemi workbox-precaching modülünden zaten kaldırıldı. Bunun yerine geliştiriciler bir PrecacheController örneği oluşturmalı ve strategy mülkünü kullanmalıdır.
  • precacheAndRoute() ile kayıtlı rota artık workbox-routing'un Router sınıfını kullanan"gerçek" bir rotadır. registerRoute() ve precacheAndRoute()'a yapılan aramaları birbirine karıştırırsanız bu durum rotalarınızın farklı bir değerlendirme sırasına sahip olmasına neden olabilir.

çalışma kutusu yönlendirmesi

setDefaultHandler() yöntemi artık geçerli olduğu HTTP yöntemine karşılık gelen isteğe bağlı ikinci bir parametre alıyor. Varsayılan olarak 'GET' değerini alır.

  • setDefaultHandler() kullanıyorsanız ve tüm isteğiniz GET ise herhangi bir değişiklik yapmanız gerekmez.
  • GET dışında bir isteğiniz varsa (POST, PUT vb.), setDefaultHandler() artık bu isteklerin eşleşmesine neden olmayacak.

Derleme Yapılandırması

workbox-build ve workbox-cli'teki getManifest ve injectManifest modları için mode seçeneği desteklenmek üzere tasarlanmamıştı ve kaldırıldı. Bu durum, InjectManifest eklentisinde mode'i destekleyen workbox-webpack-plugin için geçerli değildir.

Derleme Araçları Node.js 10 veya Üst Sürümünü Gerektirir

10 sürümünden önceki Node.js sürümleri artık workbox-webpack-plugin, workbox-build veya workbox-cli için desteklenmemektedir. Node.js'in 8'den önceki bir sürümünü çalıştırıyorsanız çalışma zamanınızı desteklenen bir sürüme güncelleyin.

Yeni İyileştirmeler

workbox-strategies

Workbox 6 sürümü, üçüncü taraf geliştiricilerin kendi Workbox stratejilerini tanımlamaları için yeni bir yöntem sunar. Böylece üçüncü taraf geliştiriciler, Workbox'ı ihtiyaçlarını tam olarak karşılayacak şekilde genişletebilir.

Yeni Strateji temel sınıfı

6. sürümde tüm Workbox stratejisi sınıfları yeni Strategy temel sınıfını genişletmelidir. Yerleşik stratejilerin tümü bunu desteklemek için yeniden yazıldı.

Strategy temel sınıfı iki temel şeyden sorumludur:

  • Tüm strateji işleyicileri için ortak olan eklenti yaşam döngüsü geri çağırma işlevlerini çağırma (ör. başlangıç, yanıt verme ve bitiş).
  • Bir stratejinin işlediği her istek için durumu yönetebilen bir "işleyici" örneği oluşturma.

Yeni "işleyici" sınıfı

Daha önce, adlarından da anlaşılacağı gibi çeşitli getirme ve önbelleğe alma API'lerini yaşam döngülerine kancalarla sarmalayan fetchWrapper ve cacheWrapper adlı dahili modüllerimiz vardı. Bu, şu anda eklentilerin çalışmasına izin veren mekanizmadır ancak geliştiricilere sunulmaz.

Yeni "işleyici" sınıfı (StrategyHandler), özel stratejilerin fetch() veya cacheMatch() yöntemini çağırabilmesi ve strateji örneğine eklenen eklentilerin otomatik olarak çağrılmasını sağlamak için bu yöntemleri kullanıma sunar.

Bu sınıf, geliştiricilerin kendi stratejilerine özel olabilecek özel yaşam döngüsü geri çağırma işlevleri eklemelerini de sağlar. Bu işlevler, mevcut eklenti arayüzüyle "kolayca çalışır".

Yeni eklenti yaşam döngüsü durumu

Workbox v5'te eklentiler durum bilgisizdir. Yani /index.html için yapılan bir istek hem requestWillFetch hem de cachedResponseWillBeUsed geri çağırmasını tetiklerse bu iki geri çağırmanın birbiriyle iletişim kurması mümkün olmaz, hatta bunların aynı istek tarafından tetiklendiğini bile bilmez.

6. sürümde, tüm eklenti geri çağırmalarına yeni bir state nesnesi de iletilir. Bu durum nesnesi, söz konusu eklenti nesnesine ve söz konusu strateji çağrısına (yani handle() çağrısına) özgüdür. Bu sayede geliştiriciler, bir geri çağırma işlevinin aynı eklentideki başka bir geri çağırma işlevinin yaptığına bağlı olarak koşullu olarak bir şey yapabileceği eklentiler yazabilir (ör. requestWillFetch ile fetchDidSucceed veya fetchDidFail çalıştırma arasındaki zaman farkını hesaplama).

Yeni eklenti yaşam döngüsü geri çağırma yöntemleri

Geliştiricilerin eklenti yaşam döngüsü durumundan tam olarak yararlanmasına olanak tanımak için yeni eklenti yaşam döngüsü geri çağırma işlevleri eklendi:

  • handlerWillStart: Herhangi bir işleyici mantığı çalışmaya başlamadan önce çağrılır. Bu geri çağırma, ilk işleyici durumunu ayarlamak için kullanılabilir (ör. başlangıç zamanını kaydetme).
  • handlerWillRespond: strategies handle() yöntemi yanıt döndürmeden önce çağrılır. Bu geri çağırma, yanıtı bir rota işleyiciye veya başka bir özel mantığa döndürmeden önce değiştirmek için kullanılabilir.
  • handlerDidRespond: Stratejinin handle() yöntemi bir yanıt döndürdükten sonra çağrılır. Bu geri çağırma, son yanıt ayrıntılarını (ör. diğer eklentiler tarafından yapılan değişikliklerden sonra) kaydetmek için kullanılabilir.
  • handlerDidComplete: Bu stratejinin çağrılmasından sonra etkinliğe eklenen tüm ömürlük kullanım süresi uzatma taahhütleri tamamlandıktan sonra çağrılır. Bu geri çağırma, hesaplama için işleyicinin tamamlanmasını beklemesi gereken tüm verileri (ör. önbellek isabeti durumu, önbellek gecikmesi, ağ gecikmesi) bildirmek için kullanılabilir.
  • handlerDidError: İşleyici herhangi bir kaynaktan geçerli bir yanıt sağlayamadıysa çağrılır. Bu geri çağırma, ağ hatasına alternatif olarak "yedek" içerik sağlamak için kullanılabilir.

Kendi özel stratejilerini uygulayan geliştiricilerin bu geri çağırma işlevlerini kendilerinin çağırması gerekmez. Bu işlevlerin tümü yeni bir Strategy temel sınıf tarafından yönetilir.

İşleyiciler için daha doğru TypeScript türleri

Çeşitli geri çağırma yöntemleri için TypeScript tanımları normalleştirildi. Bu sayede, TypeScript kullanan ve işleyicileri uygulamak veya çağrı yapmak için kendi kodlarını yazan geliştiriciler için daha iyi bir deneyim sağlanacaktır.

workbox-window

Yeni messageSkipWaiting() yöntemi

"Bekleme" durumundaki hizmet çalışanını etkinleştirme sürecini basitleştirmek için workbox-window modülüne messageSkipWaiting() adlı yeni bir yöntem eklendi. Bu güncellemeyle birlikte bazı iyileştirmeler yapılmıştır:

  • Workbox tarafından oluşturulan bir hizmet çalışanının, skipWaiting() tetiklemesini kontrol ettiği fiili standart mesaj gövdesiyle ({type: 'SKIP_WAITING'}) postMessage() öğesini çağırır.
  • workbox-window'ün kayıtlı olduğu hizmet çalışanı olmasa bile bu mesajı yayınlamak için doğru"beklemede" hizmet çalışanını seçer.

"external" etkinliklerinin isExternal mülkü lehine kaldırılması

workbox-window mülkündeki tüm "harici" etkinlikler, isExternal mülkü true olarak ayarlanmış "normal" etkinliklerin yerine kaldırıldı. Böylece, bu ayrımı önemseyen geliştiriciler bunu yine de tespit edebilir ve bilmesi gerekmeyen geliştiriciler mülkü göz ardı edebilir.

Daha temiz "Kullanıcılara sayfayı yeniden yükleme seçeneği sunma" tarifi

Yukarıdaki değişikliklerin her ikisi sayesinde "Kullanıcılar için sayfayı yeniden yükleme seçeneği sunma" tarifi basitleştirilebilir:

MULTI_LINE_CODE_PLACEHOLDER_0

çalışma kutusu yönlendirmesi

workbox-routing'te kullanılan matchCallback işlevine yeni bir boole parametresi (sameOrigin) iletilir. İstek aynı kaynaktan bir URL içinse true olarak, aksi takdirde yanlış olarak ayarlanır.

Bu sayede, bazı yaygın metinleri basitleştirebilirsiniz:

MULTI_LINE_CODE_PLACEHOLDER_1

workbox-expiration parametresinde matchOptions

Artık workbox-expiration içinde matchOptions değerini ayarlayabilirsiniz. Bu değer, temel cache.delete() çağrısına CacheQueryOptions olarak iletilir. (Çoğu geliştiricinin bunu yapması gerekmez.)

workbox-precaching

Çalışma kutusu stratejilerini kullanır

workbox-precaching, temel olarak workbox-strategies kullanacak şekilde yeniden yazıldı. Bu değişiklik, önemli değişikliklere neden olmayacak ve iki modülün ağa ve önbelleğe erişme şekli açısından uzun vadede daha iyi bir tutarlılık sağlayacaktır.

Ön önbelleğe alma işlemi artık girişleri toplu olarak değil, tek tek işler.

workbox-precaching, tümünü aynı anda istemek ve önbelleğe almak yerine önbelleğe alma manifestinde tek seferde yalnızca bir girişin istenip önbelleğe alınması için güncellendi (nasıl sınırlanacağını belirleme görevi tarayıcıya bırakılır).

Bu, önbelleğe alma sırasında net::ERR_INSUFFICIENT_RESOURCES hatalarının görülme olasılığını azaltır ve ayrıca önbelleğe alma ile web uygulaması tarafından yapılan eşzamanlı istekler arasındaki bant genişliği anlaşmazlığını azaltır.

PrecacheFallbackEklentileri daha kolay çevrimdışı yedek sağlar

workbox-precaching artık v6'da eklenen yeni handlerDidError yaşam döngüsü yöntemini uygulayan bir PrecacheFallbackPlugin içeriyor.

Bu sayede, aksi takdirde yanıt alınamayan belirli bir strateji için önceden önbelleğe alınmış bir URL'yi"yedek" olarak belirtmek kolaylaşır. Eklenti, gerekli tüm düzeltme parametreleri dahil olmak üzere önceden önbelleğe alınmış URL için doğru önbelleğe alma anahtarının doğru şekilde oluşturulmasını sağlar.

NetworkOnly stratejisi bir gezinme isteği için yanıt oluşturamadığında önceden önbelleğe alınmış bir /offline.html ile yanıt vermek için bu yöntemin kullanıldığı bir örneği burada bulabilirsiniz. Diğer bir deyişle, özel bir çevrimdışı HTML sayfası gösterilir:

MULTI_LINE_CODE_PLACEHOLDER_2

precacheFallback çalışma zamanında önbelleğe alma

Hizmet çalışanınızı manuel olarak yazmak yerine sizin için bir hizmet çalışanı oluşturmak üzere generateSW kullanıyorsanız aynı işlemi yapmak için runtimeCaching'deki yeni precacheFallback yapılandırma seçeneğini kullanabilirsiniz:

{
  // ... other generateSW config options...
  runtimeCaching: [{
    urlPattern: ({request}) => request.mode === 'navigate',
    handler: 'NetworkOnly',
    options: {
      precacheFallback: {
        // This URL needs to be included in your precache manifest.
        fallbackURL: '/offline.html',
      },
    },
  }],
}

Yardım Alma

Taşıma işlemlerinin çoğunun sorunsuz geçeceğini tahmin ediyoruz. Bu kılavuzda yer almayan sorunlarla karşılaşırsanız lütfen GitHub'da sorun kaydı açarak bize bildirin.