Workbox v5'ten v6'ya geçiş

Bu kılavuzda, Workbox v6'da yapılan zarar veren değişikliklere odaklanılmakta ve Workbox v5'ten yükseltme yaparken yapmanız gereken değişikliklere dair örnekler verilmektedir.

Zarar Veren Değişiklikler

workbox-core

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

skipWaiting(), Workbox v7'de kaldırılacağı için bundan sonra self.skipWaiting() kullanın.

workbox-precaching

• HTTP yönlendirmesine karşılık gelen URL'ler için çapraz kaynak HTML belgeleri artık workbox-precaching ile gezinme isteğini karşılamak için kullanılamaz. Bu senaryo genellikle nadir görülür.
• fbclid URL sorgu parametresi, belirli bir istek için önceden önbelleğe alınmış bir yanıt aranırken artık workbox-precaching tarafından yoksayılıyor.
• PrecacheController oluşturucusu artık dize yerine parametre olarak belirli özelliklere sahip bir nesne alır. Bu nesne şu özellikleri destekler: cacheName (v5'te oluşturucuya iletilen dizeyle aynı amaca hizmet eder), plugins (v5'teki addPlugins() yönteminin yerini alır) ve fallbackToNetwork (v5'te createHandler() ve `createHandlerBoundToURL()'ye iletilen benzer seçeneğin yerini alır).
• PrecacheController sınıfının install() ve activate() yöntemleri artık tam olarak bir parametre alır. Bu parametre, sırasıyla ilgili InstallEvent veya ActivateEvent değerine ayarlanmalıdır.
• addRoute() yöntemi PrecacheController öğesinden kaldırıldı. Bunun yerine, yeni PrecacheRoute sınıfı kullanılarak kaydedebileceğiniz bir rota oluşturabilirsiniz.
• precacheAndRoute() yöntemi PrecacheController öğesinden 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ılabileceği için kaldırıldı.
• createMatchCalback() yöntemi PrecacheController öğesinden kaldırıldı. Bunun yerine yeni PrecacheRoute kullanılabilir.
• createHandler() yöntemi PrecacheController öğesinden 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ılmış. Bunun yerine geliştiriciler bir PrecacheController örneği oluşturmalı ve bunun strategy özelliğini kullanmalıdır.
• precacheAndRoute() ile kaydedilen rota artık arka planda workbox-routing'in Router sınıfını kullanan"gerçek" bir rotadır. registerRoute() ve precacheAndRoute() çağrılarını birbiriyle karıştırırsanız bu durum, rotalarınızın farklı bir değerlendirme sırasına sahip olmasına neden olabilir.

workbox-routing

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

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

Derleme Yapılandırması

workbox-build ve workbox-cli'da getManifest ve injectManifest modları için mode seçeneğinin desteklenmesi amaçlanmamıştı ve bu seçenek kaldırıldı. Bu durum, InjectManifest eklentisinde mode özelliğini destekleyen workbox-webpack-plugin için geçerli değildir.

Derleme Araçları için Node.js v10 veya Sonraki Bir Sürüm Gerekir

workbox-webpack-plugin, workbox-build veya workbox-cli için v10'dan önceki Node.js sürümleri artık desteklenmiyor. Node.js'nin v8'den önceki bir sürümünü kullanıyorsanız çalışma zamanınızı desteklenen bir sürüme güncelleyin.

Yeni İyileştirmeler

workbox-strategies

Workbox v6, üçüncü taraf geliştiricilerin kendi Workbox stratejilerini tanımlamaları için yeni bir yöntem sunar. Bu sayede üçü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 strateji sınıfları yeni Strategy temel sınıfını genişletmelidir. Yerleşik stratejilerin tümü bunu destekleyecek şekilde yeniden yazıldı.

Strategy temel sınıfı iki ana işlemden sorumludur:

• Tüm strateji işleyiciler için ortak olan eklenti yaşam döngüsü geri çağırma yöntemlerini çağırma (ör. başladıklarında, yanıt verdiklerinde ve sona erdiklerinde).
• Bir stratejinin işlediği her bir isteğin durumunu yönetebilen bir "işleyici" örneği oluşturma.

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

Daha önce, fetchWrapper ve cacheWrapper adlı dahili modüllerimiz vardı. Bunlar (adlarından da anlaşılacağı üzere) çeşitli getirme ve önbelleğe alma API'lerini yaşam döngülerine kancalarla sarmalar. Bu, şu anda eklentilerin çalışmasına olanak tanıyan mekanizmadır ancak geliştiricilere sunulmamıştır.

Yeni "işleyici" sınıfı StrategyHandler, bu yöntemleri kullanıma sunar. Böylece özel stratejiler fetch() veya cacheMatch() yöntemini çağırabilir ve strateji örneğine eklenen tüm eklentiler otomatik olarak çağrılır.

Bu sınıf, geliştiricilerin kendi stratejilerine özgü özel yaşam döngüsü geri çağırma yöntemlerini eklemelerini de mümkün kılar ve bu yöntemler mevcut eklenti arayüzüyle "sorunsuz çalışır".

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

Workbox v5'te eklentiler durum bilgisizdir. Yani /index.html isteği hem requestWillFetch hem de cachedResponseWillBeUsed geri çağırmalarını tetiklerse bu iki geri çağırma birbiriyle iletişim kuramaz, hatta aynı istek tarafından tetiklendiklerini bile bilemez.

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

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

Geliştiricilerin eklenti yaşam döngüsü durumundan tam olarak yararlanabilmesi için yeni eklenti yaşam döngüsü geri çağırma yöntemleri 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: Stratejiler handle() yöntemi bir 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, diğer eklentiler tarafından yapılan değişikliklerden sonra nihai yanıt ayrıntılarını kaydetmek için kullanılabilir.
• handlerDidComplete: Bu stratejinin çağrılmasıyla etkinliğe eklenen tüm extend lifetime promises çözümlendikten sonra çağrılır. Bu geri çağırma, hesaplama için işleyicinin tamamlanmasını beklemesi gereken tüm verileri (ör. önbellek isabet durumu, önbellek gecikmesi, ağ gecikmesi) raporlamak için kullanılabilir.
• handlerDidError: İşleyici herhangi bir kaynaktan geçerli bir yanıt sağlayamadığında ç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ğırmaları kendilerinin çağırması gerekmez. Bu işlemlerin tamamı yeni bir Strategy temel sınıfı tarafından gerçekleştirilir.

İş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ğırmak için kendi kodlarını yazan geliştiriciler daha iyi bir deneyim yaşayacaktır.

workbox-window

Yeni messageSkipWaiting() yöntemi

"Bekleyen" hizmet çalışanına etkinleştirme talimatı verme sürecini basitleştirmek için workbox-window modülüne messageSkipWaiting() adlı yeni bir yöntem eklendi. Bu sayede bazı iyileştirmeler yapılmıştır:

• Workbox tarafından oluşturulan bir hizmet çalışanının skipWaiting() işlemini tetiklemek için kontrol ettiği standart e-posta mesajı {type: 'SKIP_WAITING'} ile postMessage() yöntemini çağırır.
• workbox-window ile kaydedilen hizmet çalışanı olmasa bile bu mesajı göndermek için doğru "bekleyen" hizmet çalışanını seçer.

"Harici" etkinliklerin kaldırılması ve isExternal mülkünün kullanılması

workbox-window içindeki tüm "harici" etkinlikler kaldırıldı ve bunların yerine isExternal özelliği true olarak ayarlanmış "normal" etkinlikler eklendi. Bu sayede, bu ayrımı önemseyen geliştiriciler bunu tespit edebilir, bilmesi gerekmeyen geliştiriciler ise özelliği yoksayabilir.

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

Yukarıdaki her iki değişiklik sayesinde "Kullanıcılara sayfa yeniden yükleme seçeneği sunma" tarifi basitleştirilebilir:

// v6:
<script type="module">
  import {Workbox} from 'https://storage.googleapis.com/workbox-cdn/releases/6.0.0-alpha.1/workbox-window.prod.mjs';

  if ('serviceWorker' in navigator) {
    const wb = new Workbox('/sw.js');

    const showSkipWaitingPrompt = () => {
      // This assumes a hypothetical createUIPrompt() method with
      // onAccept and onReject callbacks:
      const prompt = createUIPrompt({
        onAccept: () => {
          wb.addEventListener('controlling', () => {
            window.location.reload();
          });

          // This will postMessage() to the waiting service worker.
          wb.messageSkipWaiting();
        },

        onReject: () => {
          prompt.dismiss();
        },
      });
    };

    // Listening for externalwaiting is no longer needed.
    wb.addEventListener('waiting', showSkipWaitingPrompt);
    wb.register();
  }
</script>

workbox-routing

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

Bu, bazı yaygın standart kodları basitleştirir:

// In v5:
registerRoute(
  ({url}) =>
    url.origin === self.location.origin && url.pathname.endsWith('.png'),
  new StaleWhileRevalidate({cacheName: 'local-png'})
);

// In v6:
registerRoute(
  ({sameOrigin, url}) => sameOrigin && url.pathname.endsWith('.png'),
  new StaleWhileRevalidate({cacheName: 'local-png'})
);

workbox-expiration'da matchOptions

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

workbox-precaching

workbox-strategies kullanır

workbox-precaching, workbox-strategies temel alınarak yeniden yazıldı. Bu durum, zarar veren değişikliklere yol açmaz ve iki modülün ağa ve önbelleğe erişiminde uzun vadede daha iyi tutarlılık sağlar.

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

workbox-precaching, önbelleğe alma manifestindeki tüm girişleri aynı anda istemek ve önbelleğe almak yerine (kısıtlama yöntemini tarayıcıya bırakarak) tek seferde yalnızca bir giriş istenecek ve önbelleğe alınacak şekilde güncellendi.

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

PrecacheFallbackPlugin, çevrimdışı yedeklemeyi kolaylaştırır

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

Bu sayede, yanıtın kullanılamadığı durumlarda önceden önbelleğe alınmış bir URL'yi belirli bir strateji için"yedek" olarak belirtmek kolaylaşır. Eklenti, önceden önbelleğe alınmış URL için doğru önbellek anahtarını (gerekli tüm düzeltme parametreleri dahil) doğru şekilde oluşturur.

Aşağıda, NetworkOnly stratejisi bir gezinme isteği için yanıt oluşturamadığında önbelleğe alınmış bir /offline.html ile yanıt vermek için bu stratejinin nasıl kullanılacağına dair bir örnek verilmiştir. Diğer bir deyişle, özel bir çevrimdışı HTML sayfası gösterilir:

import {PrecacheFallbackPlugin, precacheAndRoute} from 'workbox-precaching';
import {registerRoute} from 'workbox-routing';
import {NetworkOnly} from 'workbox-strategies';

// Ensure that /offline.html is part of your precache manifest!
precacheAndRoute(self.__WB_MANIFEST);

registerRoute(
  ({request}) => request.mode === 'navigate',
  new NetworkOnly({
    plugins: [
      new PrecacheFallbackPlugin({
        fallbackURL: '/offline.html',
      }),
    ],
  })
);

Çalışma zamanı önbelleğe alma işleminde precacheFallback

Hizmet çalışanınızı kendiniz yazmak yerine hizmet çalışanı oluşturmak için generateSW kullanıyorsanız aynı işlemi gerçekleştirmek için runtimeCaching içindeki 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

Çoğu taşıma işleminin kolay olacağını tahmin ediyoruz. Bu kılavuzda ele alınmayan sorunlarla karşılaşırsanız lütfen GitHub'da sorun kaydı açarak bize bildirin.