Bu kılavuzda, Workbox v4'ten yükseltme yaparken yapmanız gereken değişikliklere dair örneklerle birlikte Workbox v5'te kullanımdan kaldırılan özellikler ele alınmaktadır.
Zarar Veren Değişiklikler
Eklenti sınıfları yeniden adlandırıldı
Bazı Workbox v4 paketleri Plugin adlı sınıflar içeriyordu. 5. sürümde bu sınıflar, paket tanımlayıcısı + Plugin kalıbına 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ızdan bağımsız olarak geçerlidir.
Varsayılan Ön Önbellek Manifest Değiştirme Noktası
Daha önce, "manifest ekleme" modunda bir derleme aracından biri kullanıldığında kaynak hizmet çalışanı dosyanızda precacheAndRoute([]) olup olmadığı kontrol edilirdi. Bu boş dizi [], önbelleğe alma manifestinin yerleştirildiği nokta için yer tutucu olarak kullanılırdı.
Workbox v5'te değiştirme mantığı değişti ve artık self.__WB_MANIFEST ekleme noktası olarak varsayılan olarak kullanılıyor.
// v4:
precacheAndRoute([]);
// v5:
precacheAndRoute(self.__WB_MANIFEST);
Bu tartışmada da belirtildiği gibi, bu değişikliğin daha basit bir deneyim sağlarken geliştiricilere yerleştirilen manifestin özel hizmet çalışanı kodunda nasıl kullanıldığı konusunda daha fazla kontrol sağladığını düşünüyoruz. Gerekirse bu yeni dizeyi injectionPoint yapılandırma seçeneğinden değiştirebilirsiniz.
Navigasyon rotası değişiklikleri
Daha önce navigasyon rotaları için desteklenen iki seçenek (blacklist ve whitelist) denylist ve allowlist olarak yeniden adlandırıldı.
workbox-routing daha önce, arka planda iki şey yapan registerNavigationRoute() yöntemini destekliyordu:
- Belirli bir
fetchetkinliğininmode/'navigate'olup olmadığı algılandı. - Bu durumda, gidilen URL ne olursa olsun, önceden önbelleğe alınmış ve kodu gömülü bir URL'nin içeriğini kullanarak bu isteği yanıtlayabilirsiniz.
Bu, uygulama kabuğu mimarisini uygularken kullanılan yaygın bir kalıptır.
Önbellekten okuyarak yanıt oluşturma işlemi olan ikinci adım, workbox-routing'ün sorumlulukları kapsamında değildir. Bunun yerine, yeni bir yöntem olan createHandlerBoundToURL() aracılığıyla workbox-precaching kapsamında olması gereken işlev olarak görüyoruz. Bu yeni yöntem, aynı mantığı gerçekleştirmek için workbox-routing sınıfındaki mevcut NavigationRoute sınıfıyla birlikte çalışabilir.
Derleme aracının "SW oluştur" kodlarından birindeki navigateFallback seçeneğini 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 veya navigateFallbackAllowlist olarak değiştirin.
"Inject manifest" (manifest ekle) kullanıyorsanız modunda çalışırken ya da Service Worker'ı kendiniz yazarsanız ve Workbox v4 hizmet çalışanı doğrudan registerNavigationRoute() ürününü çağırırsa, 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 konuda sizin adınıza ilgileneceği için artık getCacheKeyForURL()'ü aramanıza gerek yok.
workbox-strategies'den makeRequest() kaldırıldı
makeRequest() çağrısı, çoğunlukla workbox-strategy sınıflarından birinde handle() çağrısıyla eşdeğerdir. İki yöntem arasındaki farklar çok az olduğu için her ikisini de bir arada tutmak mantıklı değildi. makeRequest() çağrısı yapan geliştiriciler, başka bir değişiklik yapmadan handle() kullanmaya geçebilir:
// v4:
const strategy = new StaleWhileRevalidate({...});
const response = await strategy.makeRequest({event, request});
// v5:
const strategy = new StaleWhileRevalidate({...});
const response = await strategy.handle({event, request});
handle(), v5'te request'u zorunlu bir parametre olarak değerlendirir ve event.request'yi kullanmaya geri dönmez. handle() öğesini çağırırken geçerli bir istek ilettiğinizden emin olun.
workbox-broadcast-update Her Zaman postMessage() Kullanır
4. sürümde workbox-broadcast-update kitaplığı, desteklendiğinde varsayılan olarak mesaj göndermek için Broadcast Channel API'yi kullanır ve yalnızca Broadcast Channel desteklenmediğinde postMessage()'i kullanır.
Gelen mesajların iki olası kaynağını dinlemek zorunda kalmanın, istemci tarafı kod yazmayı fazla karmaşık hale getirdiğini fark ettik. Ayrıca bazı tarayıcılarda, istemci sayfalarına gönderilen hizmet işleyiciden gelen postMessage() çağrıları, bir message etkinlik dinleyicisi ayarlanana kadar otomatik olarak arabelleğe alınır. Yayın Kanalı API'sinde arabelleğe alma işlemi yoktur ve istemci sayfası iletileri almaya hazır olmadan önce gönderilen yayınlanan mesajlar atlanır.
Bu nedenlerden dolayı, workbox-broadcast-update hizmetini v5'te her zaman postMessage() kullanacak şekilde değiştirdik. Mesajlar, geçerli hizmet çalışanının kapsamındaki tüm istemci sayfalarına tek tek gönderilir.
Bu yeni davranışa uyum sağlamak için, BroadcastChannel örnek oluşturan istemci sayfalarındaki tüm kodları kaldırabilir ve bunun yerine navigator.serviceWorker adlı cihazda 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ği için workbox-window kullanıcılarının herhangi bir değişiklik yapması gerekmez.
Derleme Araçları Node.js v8 veya Üst Sürümünü Gerektirir
workbox-webpack-plugin, workbox-build veya workbox-cli için v8'den önceki Node.js sürümleri artık desteklenmiyor. 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 Daha Yüksek
workbox-webpack-plugin kullanıyorsanız en az webpack v4'ü kullanacak şekilde webpack kurulumunuzu güncelleyin.
Geliştirme Aracı Seçeneği Revizyonu
Bazı workbox-build, workbox-cli ve workbox-webpack-plugin yapılandırma parametreleri artık desteklenmiyor. Örneğin, generateSW sizin için her zaman yerel bir Workbox çalışma zamanı paketi oluşturur. Bu nedenle, importWorkboxFrom seçeneği artık bir anlam ifade etmez.
Desteklenen seçeneklerin listesi için ilgili aracın belgelerine bakın.
Çalışma kutusu derlemesinden generateSWString'in kaldırılması
generateSWString modu workbox-build uygulamasından kaldırıldı. Öncelikli olarak workbox-webpack-plugin tarafından dahili olarak kullanıldığı için bu durumun 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ılırken teknik olarak mümkün olsa da v5'e geçerken beklediğimiz en büyük değişiklik, Workbox'ın modüllerini içe aktararak kendi paket halinde hizmet çalışanınızı oluşturduğunuz modeldir. Bu yaklaşım, hizmet işleyicinizin en üstünde importScripts('/path/to/workbox-sw.js') çağrısı yapmanın ve workbox.* ad alanı aracılığıyla Workbox'u kullanmanın alternatifidir.
"SW oluşturma" bölümünde derleme araçlarından birini (workbox-webpack-plugin, workbox-build, workbox-cli) kullanıyorsanız bu değişiklik sizin için otomatik olarak gerçekleşecektir. Bu araçların tümü, hizmet çalışanı mantığınızı uygulamak için gereken asıl kodun yanı sıra Workbox çalışma zamanının yerel ve özel bir paketini oluşturur. Bu senaryoda, artık workbox-sw veya Workbox'un CDN kopyasına bağımlılık yoktur. inlineWorkboxRuntime yapılandırmanızın değerine bağlı olarak, Workbox çalışma zamanı, hizmet çalışanınızla birlikte dağıtılması gereken (varsayılan false değerine ayarlandığında) veya hizmet çalışanı mantığıyla birlikte satır içi olarak dağıtılması gereken (true olarak ayarlandığında) ayrı bir dosyaya bölünür.
"inject manifest" içindeki derleme araçlarını kullanıyorsanız veya Workbox'ın derleme araçlarını kullanmıyorsanız mevcut İş Kutusu ile Paketleyicileri (webpack/Toplayıcı) Kullanma (webpack/Rollup) kılavuzundan kendi Workbox çalışma zamanı paketinizi oluşturma hakkında daha fazla bilgi edinebilirsiniz.
v5 ile ilgili dokümanlar ve örnekler, modülün içe aktarma söz diziminin söz konusu olduğu varsayılmıştır, ancak workbox.* ad alanı Workbox v5'te desteklenmeye devam edecektir.
Önbelleğe Alınmış Yanıtları Okuma
Bazı geliştiricilerin, önceden önbelleğe alınmış yanıtları örtülü olarak precacheAndRoute() yöntemi aracılığıyla kullanmak yerine, doğrudan önbellekten okuması gerekir. v4'te yaygın olarak kullanılan bir kalıp, önce önceden önbelleğe alınmış bir kaynağın mevcut sürümüne özel önbellek anahtarını alıp ardından bu anahtarı önbelleğin önbellek adıyla birlikte caches.match() hizmetine ileterek Response elde etmektir.
Bu işlemi basitleştirmek için v5'teki workbox-precaching, matchPrecache() adlı yeni ve eşdeğer bir yöntemi desteklemektedir:
// 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 Benimseme
v5'te, Workbox çalışma zamanı kitaplıkları TypeScript'te yazılır. TypeScript'i kullanmayan geliştiriciler için, aktarılan JavaScript modüllerini ve paketlerini yayınlamaya devam edeceğiz. Ancak TypeScript kullanıyorsanız doğrudan Workbox projesinden alınan doğru, her zaman güncel tür bilgilerinden yararlanabilirsiniz.
Örnek Taşıma
Bu taahhüt, satır içi yorumlarla birlikte oldukça karmaşık bir taşıma işlemini göstermektedir. Çalışma zamanını CDN'den yüklemek yerine nihai hizmet çalışanına özel bir Workbox çalışma zamanı eklemek için Rollup'u kullanır.
Her önemli değişikliği kapsamasa da bir hizmet çalışanı dosyasını 4. sürümden 5. sürüme yükseltme (TypeScript'e geçiş de dahil) işleminin önceki ve sonraki halini burada görebilirsiniz.
Yardım Alma
Taşıma işlemlerinin çoğunun sorunsuz geçeceğini tahmin ediyoruz. Bu kılavuzda ele alınmayan sorunlarla karşılaşırsanız GitHub'da bir sorun açarak bize bildirin.