Workbox v5'ten v6'ya geçiş

Bu kılavuzda, Workbox 6 sürümünde yapılan önemli değişiklikler ele alınmakta ve Workbox 5'ten yükseltme yaparken yapmanız gereken değişiklikler örneklerle açıklanmaktadır.

Zarar Veren Değişiklikler

workbox-core

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-önbelleğe alma

  • 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 durum genellikle nadir görülür.
  • 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 kurucusu artık parametresi olarak dize yerine belirli özelliklere sahip bir nesne alıyor. Bu nesne aşağıdaki özellikleri destekler: cacheName (v5'teki kurucuya iletilen dizeyle aynı amaca hizmet eder), plugins (v5'teki addPlugins() yönteminin yerini alır) ve fallbackToNetwork (v5'teki createHandler() ve "createHandlerBoundToURL()"ye iletilen benzer seçeneğin yerini alır).
  • PrecacheController'nin install() ve activate() yöntemleri artık tam olarak bir parametre alır. Bu parametre, sırasıyla ilgili bir InstallEvent veya ActivateEvent olarak ayarlanmalıdır.
  • addRoute() yöntemi PrecacheController'dan kaldırıldı. Bunun yerine, yeni PrecacheRoute sınıfı, daha sonra kaydedebileceğiniz bir rota oluşturmak için kullanılabilir.
  • precacheAndRoute() yöntemi PrecacheController'dan 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, isteklerini 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 kaydedilen 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.

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ı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. Bu sayede üçüncü taraf geliştiriciler, Workbox'u ihtiyaçlarını tam olarak karşılayacak şekilde genişletebilir.

Yeni strateji taban 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ını sağlayan mekanizmadır ancak geliştiricilere gösterilmez.

Özel stratejilerin fetch() veya cacheMatch()'i çağırabilmesi ve strateji örneğine eklenen tüm eklentilerin otomatik olarak çağrılabilmesi için yeni "işleyici" sınıfı StrategyHandler bu yöntemleri gösterir.

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 bir istek hem requestWillFetch hem de cachedResponseWillBeUsed geri çağırma işlevini tetiklerse bu iki geri çağırma işlevinin birbiriyle iletişim kurması veya aynı istek tarafından tetiklendiklerini bilmesi mümkün değildir.

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 işlevi, bir rota işleyiciye veya başka bir özel mantığa döndürülmeden önce bu yanıtı 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, TypeScript kullanan ve işleyicileri uygulamak veya çağırmak için kendi kodlarını yazan geliştiriciler için daha iyi bir deneyim sunacaktı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 sayede bazı iyileştirmeler elde edebilirsiniz:

  • Workbox tarafından oluşturulan bir hizmet çalışanının skipWaiting()'yi tetiklemek için kontrol ettiği standart mesaj gövdesi {type: 'SKIP_WAITING'} ile postMessage()'ü ç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ı. Bu sayede, ayrımı önemseyen geliştiriciler bu özelliği tespit etmeye devam edebilir. Bu bilgiyi bilmesi gerekmeyen geliştiriciler ise özelliği yoksayabilir.

Daha temiz "Kullanıcılar için 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:

// 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şlevinde 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:

// 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 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-önbelleğe alma

Çalışma kutusu stratejileri kullanır

workbox-precaching, workbox-strategies'u temel olarak 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ü tek seferde 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.

PrecacheFallbackPlugin, çevrimdışı yedekleme için daha kolay bir yöntem sunar.

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 örnek verilmiştir. Diğer bir deyişle, özel bir çevrimdışı HTML sayfası gösterilmektedir:

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',
      }),
    ],
  })
);

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.