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ı:
BackgroundSyncPlugin
BroadcastUpdatePlugin
CacheableResponsePlugin
ExpirationPlugin
RangeRequestsPlugin
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
fetch
etkinliğ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.