Bu kılavuz, Workbox v5'te yapılan değişikliklerin zarar görmesine odaklanıyor ve Workbox v4'ten yükseltme yaparken yapmanız gereken değişikliklerin örneklerine yer veriyor.
Zarar Veren Değişiklikler
Eklenti Sınıfları Yeniden Adlandırıldı
Bazı Workbox v4 paketleri Plugin adlı sınıflar içeriyordu. v5'te bu sınıflar, kalıp paket tanımlayıcısı + Plugin'e uyacak şekilde yeniden adlandırıldı:
BackgroundSyncPluginBroadcastUpdatePluginCacheableResponsePluginExpirationPluginRangeRequestsPlugin
Bu yeniden adlandırma işlemi, sınıfları modül içe aktarma veya workbox.* ad alanları aracılığıyla kullanmanızda geçerlidir.
Varsayılan Ön Önbellek Manifest Değiştirme Noktası
Daha önce, "manifest ekleme" modunda derleme araçlarından birini kullanırken, kaynak hizmet çalışanı dosyanız precacheAndRoute([]) olup olmadığı kontrol ediliyor ve boş [] dizisi ön önbellek manifestinin eklendiği nokta için yer tutucu olarak kullanılıyordu.
Workbox v5'te değiştirme mantığı değişti ve artık varsayılan olarak self.__WB_MANIFEST ekleme noktası olarak kullanılmaktadır.
// v4:
precacheAndRoute([]);
// v5:
precacheAndRoute(self.__WB_MANIFEST);
Bu tartışmada açıklandığı gibi, bu değişikliğin daha basit bir deneyim sağladığına ve aynı zamanda geliştiricilere, yerleştirilen manifestin özel hizmet çalışanı kodunda nasıl kullanıldığı üzerinde daha fazla kontrol sağladığına inanıyoruz. Gerekirse bu değiştirme dizesini injectionPoint yapılandırma seçeneği aracılığıyla değiştirebilirsiniz.
Navigasyon rotası değişiklikleri
Navigasyon rotalarında daha önce desteklenen iki seçenek olan blacklist ve whitelist, denylist ve allowlist olarak yeniden adlandırıldı.
workbox-routing daha önce registerNavigationRoute() adlı bir yöntemi destekliyordu. Bu yöntem, arka planda iki işlem gerçekleştirdi:
- Belirli bir
fetchetkinliğininmode/'navigate'değerine sahip olup olmadığı tespit edildi. - Bu durumda söz konusu isteğe, gidilen URL'den bağımsız olarak önceden önbelleğe alınmış ve kodu gömülmüş bir URL'nin içeriğini kullanarak yanıt vermiştir.
Bu, App Shell mimarisini uygularken yaygın olarak kullanılan bir kalıptır.
Önbellekten okuyarak yanıt oluşturma olan ikinci adım, workbox-routing sorumluluklarının kapsamı dışında kalır. Bu işlevi, yeni bir yöntemle (createHandlerBoundToURL()) workbox-precaching ürününün bir parçası olması gereken bir işlev olarak görüyoruz. Bu yeni yöntem, aynı mantığı gerçekleştirmek için workbox-routing alanındaki mevcut NavigationRoute sınıfıyla birlikte çalışabilir.
navigateFallback seçeneğini derleme aracının "SW oluştur" modundan birinde kullanıyorsanız geçiş otomatik olarak gerçekleşir. Daha önce navigateFallbackBlacklist veya navigateFallbackWhitelist seçeneklerini yapılandırdıysanız bunları sırasıyla navigateFallbackDenylist ya da navigateFallbackAllowlist olarak değiştirin.
"Bildiri ekleme" modunu kullanıyorsanız veya hizmet çalışanına kendiniz yazıyorsanız ve Workbox v4 hizmet çalışanınız doğrudan registerNavigationRoute() çağrısı yapıyorsa eşdeğer davranışı elde etmek için kodunuzda değişiklik yapmanız gerekir.
// v4:
import {getCacheKeyForURL} from 'workbox-precaching';
import {registerNavigationRoute} from 'workbox-routing';
const appShellCacheKey = getCacheKeyForURL('/app-shell.html');
registerNavigationRoute(appShellCacheKey, {
whitelist: [...],
blacklist: [...],
});
// v5:
import {createHandlerBoundToURL} from 'workbox-precaching';
import {NavigationRoute, registerRoute} from 'workbox-routing';
const handler = createHandlerBoundToURL('/app-shell.html');
const navigationRoute = new NavigationRoute(handler, {
allowlist: [...],
denylist: [...],
});
registerRoute(navigationRoute);
createHandlerBoundToURL(), bu işlemi sizin için gerçekleştireceğinden artık getCacheKeyForURL() numaralı telefonu aramanız gerekmez.
Çalışma kutusu stratejilerinden makeRequest() işlevinin kaldırılması
makeRequest() çağrısı yapmak, çoğunlukla workbox-strategy sınıflarından birinde handle() çağrısı yapmakla eşdeğerdir. İki yöntem arasındaki farklar çok küçük olduğundan ikisini de kullanmaya devam etmek mantıklı değildi. makeRequest() numaralı telefonu arayan geliştiriciler herhangi bir değişiklik yapmadan handle() kullanımına geçebilirler:
// v4:
const strategy = new StaleWhileRevalidate({...});
const response = await strategy.makeRequest({event, request});
// v5:
const strategy = new StaleWhileRevalidate({...});
const response = await strategy.handle({event, request});
v5'te handle(), request değerini zorunlu bir parametre olarak ele alır ve event.request kullanımına geri dönmez. handle() numaralı telefonu aradığınızda geçerli bir istek ilettiğinizden emin olun.
workbox-broadcast-update Her Zaman postMessage() Kullanır
v4'te workbox-broadcast-update kitaplığı, desteklendiğinde mesaj göndermek için varsayılan olarak Broadcast Channel API'yi kullanmaya başlar ve postMessage() yalnızca Yayın Kanalı desteklenmediğinde kullanmaya başlar.
Gelen iletilerin iki olası kaynağını dinlemenin, istemci tarafında kod yazmayı aşırı karmaşık hale getirdiğini fark ettik. Ayrıca bazı tarayıcılarda, istemci sayfalarına gönderilen Service Worker'dan gelen postMessage() çağrıları bir message etkinlik işleyici ayarlanana kadar otomatik olarak arabelleğe alınır. Broadcast Channel API'de arabelleğe alma gerekmez ve yayınlanan mesajlar bir istemci sayfası bunları almaya hazır olmadan önce gönderilirse atlanır.
Bu nedenlerden dolayı, workbox-broadcast-update sürümünü v5'te her zaman postMessage() kullanılacak şekilde değiştirdik. İletiler, geçerli hizmet çalışanı kapsamındaki tüm istemci sayfalarına tek tek gönderilir.
Bu yeni davranışa uyum sağlamak için, BroadcastChannel örneği oluşturan müşteri sayfalarındaki tüm kodları kaldırabilir ve bunun yerine navigator.serviceWorker sitesinde bir message etkinlik işleyici oluşturabilirsiniz:
// v4:
const updatesChannel = new BroadcastChannel('api-updates');
updatesChannel.addEventListener('message', event => {
const {cacheName, updatedUrl} = event.data.payload;
// ... your code here ...
});
// v5:
// This listener should be added as early as possible in your page's lifespan
// to ensure that messages are properly buffered.
navigator.serviceWorker.addEventListener('message', event => {
// Optional: ensure the message came from workbox-broadcast-update
if (event.meta === 'workbox-broadcast-update') {
const {cacheName, updatedUrl} = event.data.payload;
// ... your code here ...
}
});
Dahili mantığı postMessage() çağrılarını dinleyecek şekilde güncellendiğinden workbox-window kullanıcılarının herhangi bir değişiklik yapmasına gerek yoktur.
Derleme Araçları Node.js v8 veya Üstü Gerektirir
Sürüm 8'den önceki Node.js sürümleri artık workbox-webpack-plugin, workbox-build veya workbox-cli için desteklenmemektedir. 8'den önceki bir Node.js sürümünü çalıştırıyorsanız çalışma zamanınızı desteklenen bir sürüme güncelleyin.
workbox-webpack-plugin Webpack v4 veya Üstü gerektirir
workbox-webpack-plugin kullanıyorsanız web paketi kurulumunuzu en azından webpack v4'ü kullanacak şekilde güncelleyin.
Derleme Aracı Seçeneği Revizyonu
Bazı workbox-build, workbox-cli ve workbox-webpack-plugin yapılandırma parametresi artık desteklenmiyor. Örneğin generateSW, sizin için her zaman yerel bir Workbox çalışma zamanı paketi oluşturacağından importWorkboxFrom seçeneği artık bir anlam ifade etmez.
Desteklenen seçeneklerin listesi için ilgili aracın dokümanlarına bakın.
createSWString'in çalışma kutusu derlemesinden kaldırılması
generateSWString modu, workbox-build adlı alandan kaldırıldı. Ağırlıklı olarak workbox-webpack-plugin tarafından şirket içinde kullanıldığı için bu uygulamanın etkisinin minimum düzeyde olmasını bekliyoruz.
İsteğe Bağlı Değişiklikler
Modül İçe Aktarmalarını Kullanma
Bu değişiklik a) isteğe bağlı ve b) Workbox v4'ü kullanırken teknik olarak mümkün olsa da, v5'e geçerken öngördüğümüz en büyük değişiklik Workbox modüllerini içe aktararak paket halinde kendi hizmet çalışanınızı oluşturduğunuz bir modeldir. Bu yaklaşım, hizmet çalışanınızın en üstünde importScripts('/path/to/workbox-sw.js') çağırmaya ve iş kutusunu workbox.* ad alanı üzerinden kullanmaya alternatiftir.
Derleme araçlarından (workbox-webpack-plugin, workbox-build, workbox-cli) birini "SW oluştur" modunda kullanıyorsanız bu değişiklik sizin için otomatik olarak gerçekleşir. Tüm bu araçlar, Service Worker mantığınızı uygulamak için gereken gerçek kodla birlikte, Workbox çalışma zamanı için yerel, özel bir paket oluşturur. Bu senaryoda artık workbox-sw ürününe veya Workbox'ın CDN kopyasına herhangi bir bağımlılık yoktur. inlineWorkboxRuntime yapılandırmanızın değerine bağlı olarak, Workbox çalışma zamanı ayrı bir dosyaya bölünür (varsayılan olarak false değerine ayarlandığında) ve hizmet çalışanınızla birlikte dağıtılması gereken ayrı bir dosyaya bölünür (false olarak ayarlandığında) veya Service Worker mantığıyla birlikte satır içi olarak eklenir (true olarak ayarlandığında).
Derleme araçlarını "manifest ekleme" modunda kullanıyorsanız veya Workbox'ın derleme araçlarını hiç kullanmıyorsanız kendi Workbox çalışma zamanı paketinizi oluşturma hakkında daha fazla bilgiyi mevcut Workbox ile Paketleyicileri (webpack/Toplayıcı) Kullanma kılavuzundan edinebilirsiniz.
v5 ile ilgili dokümanlar ve örnekler, modülün söz dizimini içe aktardığı varsayılarak yazılmıştır ancak workbox.* ad alanı, Workbox v5'te desteklenmeye devam edecektir.
Önceden Önbelleğe Alınan Yanıtları Okuma
Bazı geliştiricilerin, önceden önbelleğe alınmış yanıtları dolaylı yoldan precacheAndRoute() yöntemiyle kullanmak yerine, doğrudan önbellekten okuması gerekir. v4'te yaygın olarak kullanılan bir kalıp, önce önbelleğe alınmış bir kaynağın geçerli sürümüne özgü önbellek anahtarını almak, ardından Response almak için bu anahtarı ön önbelleğin önbellek adıyla birlikte caches.match() öğesine geçirmektir.
Bu süreci basitleştirmek için v5'teki workbox-precaching, yeni ve eşdeğer bir yöntemi (matchPrecache()) destekler:
// v4:
import {cacheNames} from 'workbox-core';
import {getCacheKeyForURL} from 'workbox-precaching';
const cachedResponse = await caches.match(
getCacheKeyForURL(`/somethingPrecached`),
{
cacheName: cacheNames.precache,
}
);
// v5:
import {matchPrecache} from 'workbox-precaching';
const cachedResponse = await matchPrecache(`/somethingPrecached`);
TypeScript Kullanımı
v5'te Workbox çalışma zamanı kitaplıkları TypeScript'te yazılmıştır. TypeScript'i kullanmaya başlamamış geliştiricileri desteklemek için aktarılan JavaScript modüllerini ve paketlerini yayınlamaya devam edeceğiz. Ancak TypeScript kullanıyorsanız doğru ve her zaman güncel tür bilgilerinden doğrudan Workbox projesinden yararlanmanız gerekecek.
Örnek Taşıma
Bu kaydetme, satır içi yorum içeren oldukça kapsamlı bir taşıma işlemidir. CDN'den çalışma zamanı yüklemek yerine son hizmet çalışanına özel bir Workbox çalışma zamanı eklemek için Toplayıcı'yı kullanır.
Zarar veren her değişikliği kapsamasa da TypeScript'e geçiş yapmayı da içeren bir Service Worker dosyasının v4'ten v5'e yükseltilmesinin öncesi ve sonraki adımları burada verilmiştir.
Yardım Alma
Çoğu taşıma işleminin basit olacağını tahmin ediyoruz. Bu kılavuzda ele alınmayan sorunlarla karşılaşırsanız GitHub'da sorun açarak bize bildirin.