Bu kılavuz, Workbox v3'te yapılan değişiklikleri bozmaya odaklanarak, Workbox v2 kurulumundan yükseltme yaparken yapmanız gereken değişikliklerin örneklerine odaklanmaktadır.
Şu anda eski sw-precache
/sw-toolbox
kombinasyonunu kullanıyorsanız ve Workbox'a ilk kez geçiş yapmak istiyorsanız aşağıdaki farklı taşıma rehberinden yararlanabilirsiniz.
v3 Arka Planı
Workbox'ın v3 sürümü, mevcut kod tabanında önemli ölçüde yeniden düzenleme yapıldığını gösteriyor. Ana hedefler şunlardır:
- Çalışma Kutusu'nun boyutunu en aza indirin. İndirilen ve yürütülen Service Worker çalışma zamanı kodu miktarı azaltıldı. Herkesi monolitik pakete dahil etmek yerine yalnızca kullandığınız belirli özelliklerin kodu çalışma zamanında içe aktarılır.
- Workbox'ta CDN var. Workbox çalışma zamanı kitaplıklarına erişmek için standart seçenek olarak tam olarak desteklenen, Google Cloud Storage tabanlı bir CDN barındırma hizmeti sunuyoruz. Böylece, Workbox'ı kurup çalıştırmanız daha kolay.
- Daha İyi Hata Ayıklama ve Günlükler. Hata ayıklama ve günlük kaydı deneyimi büyük ölçüde iyileştirildi. Workbox bir
localhost
kaynağından kullanıldığında ve tüm günlük kaydı ve onaylar üretim derlemelerinden kaldırıldığında hata ayıklama günlükleri varsayılan olarak etkinleştirilir. - İyileştirilmiş web paketi eklentisi.
workbox-webpack-plugin
, web paketi derleme süreciyle daha yakından entegre olduğundan derleme ardışık düzenindeki tüm öğeleri önceden önbelleğe almak istediğinizde sıfır yapılandırmalı bir kullanım alanı sağlar.
Bu hedeflere ulaşmak ve önceki arayüzün tuhaf görünen ya da karşıt kalıplara yol açan bazı yönlerini temizlemek için v3 sürümünde bazı bozucu değişiklikler yapılması gerekiyordu.
Zarar Veren Değişiklikler
Derleme Yapılandırması
Aşağıdaki değişiklikler, ortak bir yapılandırma seçeneği grubunu paylaşan tüm derleme araçlarımızın (workbox-build
, workbox-cli
, workbox-webpack-plugin
) davranışını etkiler.
'fastest'
işleyici adı daha önce geçerliydi veruntimeCaching
yapılandırılırken'staleWhileRevalidate'
için takma ad olarak kabul ediliyordu. Artık geçerli olmadığından geliştiriciler doğrudan'staleWhileRevalidate'
kullanımına geçmelidir.- Birkaç
runtimeCaching.options
özellik adı güncellendi ve geçersiz yapılandırma kullanılması durumunda derlemenin başarısız olmasına neden olacak ek parametre doğrulama işlemi uygulanıyor. Şu anda desteklenen seçeneklerin listesi içinruntimeCaching
dokümanlarına bakın.
çalışma kutusu-arka plan-senkronizasyon
maxRetentionTime
yapılandırma parametresi artık milisaniye sayısı yerine dakika sayısı olarak yorumlanıyor.- Artık, Eklenti veya bağımsız sınıf oluştururken ilk parametre olarak aktarılması gereken, sıra adını temsil eden gerekli bir dize mevcuttur. (Daha önce seçeneklerin özelliği olarak aktarılıyordu.) Güncellenen API yüzeyi için belgelere bakın.
workbox-broadcast-cache-update
- Artık, Eklenti veya bağımsız sınıf oluştururken ilk parametre olarak iletilmesi gereken, kanal adını temsil eden bir gerekli dize mevcuttur.
Örneğin, v2'de Eklenti sınıfını aşağıdaki gibi başlatırsınız:
new workbox.broadcastCacheUpdate.BroadcastCacheUpdatePlugin({
channelName: 'cache-updates',
headersToCheck: ['etag'],
});
v3'te eşdeğer kullanım:
new workbox.broadcastUpdate.Plugin('cache-updates', {headersToCheck: ['etag']});
Güncellenen API yüzeyi için belgelere bakın.
çalışma kutusu oluşturma
- Varsayılan olarak,
glob
kalıp eşleştirme artık seçeneklerlefollow: true
(sembolik bağlantıları izler) vestrict: true
("olağan dışı" hatalara karşı daha az toleranslıdır) ile gerçekleştirilecektir. Derleme yapılandırmanızdaglobFollow: false
ve/veyaglobStrict: false
ayarlarını yaparak her birini devre dışı bırakabilir ve önceki davranışa dönebilirsiniz. workbox-build
içindeki işlevlerin tümü, döndürdükleri yanıtlarda ek bir özellik (warnings
) döndürür. v2'de önemli hata olarak ele alınan bazı senaryolara artık izin veriliyor ancak bir dize dizisi olanwarnings
aracılığıyla raporlanıyor.
v2'de generateSW
şöyle diyebilirsiniz:
const workboxBuild = require('workbox-build');
workboxBuild.generateSW({...})
.then(({count, size}) => console.log(`Precached ${count} files, totaling ${size} bytes.`))
.catch((error) => console.error(`Something went wrong: ${error}`));
Aynı kodu v3'te de kullanabilirsiniz, ancak warnings
olup olmadığını kontrol etmek ve bunları günlüğe kaydetmek iyi bir fikirdir:
const workboxBuild = require('workbox-build');
workboxBuild.generateSW({...})
.then(({count, size, warnings}) => {
for (const warning of warnings) {
console.warn(warning);
}
console.log(`Precached ${count} files, totalling ${size} bytes.`);
})
.catch((error) => console.error(`Something went wrong: ${error}`));
- v2'de kendi özel
ManifestTransform
işlevlerini yazan geliştiricilerin, manifest dizisini bir nesnede döndürmesi gerekir (yanireturn manifestArray;
yerinereturn {manifest: manifestArray};
).mBu, eklentinizin önemli olmayan uyarı bilgileri içeren bir dize dizisi olması gereken isteğe bağlıwarnings
özelliğini eklemesine olanak tanır.
v2'de özel bir ManifestTransform
yazacaksanız şunun gibi bir kod yazın:
const cdnTransform = manifestEntries => {
return manifestEntries.map(entry => {
const cdnOrigin = 'https://example.com';
if (entry.url.startsWith('/assets/')) {
entry.url = cdnOrigin + entry.url;
}
return entry;
});
};
aşağıdaki gibi v3 eşdeğerine sahiptir:
const cdnTransform = manifestEntries => {
const manifest = manifestEntries.map(entry => {
const cdnOrigin = 'https://example.com';
if (entry.url.startsWith('/assets/')) {
entry.url = cdnOrigin + entry.url;
}
return entry;
});
return {manifest, warnings: []};
};
getFileManifestEntries()
işlevigetManifest()
olarak yeniden adlandırıldı ve döndürülen sözü artık, önceden önbelleğe alınan URL'ler hakkında ek bilgiler içeriyor.
v2'de aşağıdaki gibi bir kod:
const manifestEntries = await workboxBuild.getFileManifestEntries({...});
v3'te şu şekilde yeniden yazılabilir:
const {manifestEntries, count, size, warnings} = await workboxBuild.getManifest({...});
// Use manifestEntries like before.
// Optionally, log the new info returned in count, size, warnings.
generateFileManifest()
işlevi kaldırıldı. Geliştiricilerin bunun yerinegetManifest()
yöntemini çağırmaları ve ilgili yanıtı diske uygun biçimde yazmak için yanıt kullanmaları önerilir.
çalışma kutusu-önbelleği-geçerlilik-geçerlilik-geçerlilik
- Eklenti API'sı aynı kaldı. Çoğu geliştirici bu modu kullanacak. Ancak API'yi bağımsız bir sınıf olarak kullanan geliştiricileri etkileyen önemli API değişiklikleri vardır. Güncellenen API yüzeyi için belgelere bakın.
workbox-cli
Geliştiriciler, desteklenen parametrelerin tamamı için KSA'yı --help
işaretiyle çalıştırabilir.
- İkili komut dosyası için
workbox-cli
takma adı desteği kaldırıldı. İkili dosyaya artık yalnızcaworkbox
olarak erişilebilir. generate:sw
veinject:manifest
v2 komutları, v3'tegenerateSW
veinjectManifest
olarak yeniden adlandırıldı.- v2'de, varsayılan yapılandırma dosyasının (açıkça belirtilmediğinde kullanılır) geçerli dizinde
workbox-cli-config.js
olduğu varsayıldı. v3'te özelliğin değeriworkbox-config.js
.
Bu durum, birlikte ele alındığında v2'de şu anlama gelir:
$ workbox inject:manifest
workbox-cli-config.js
ve v3'ten okunan bir yapılandırma kullanarak "manifest ekleme" derleme işlemini çalıştırır:
$ workbox injectManifest
aynısını yapar ancak yapılandırmayı workbox-config.js
öğesinden okur.
çalışma kutusu önbelleğine alma
precache()
yöntemi daha önce hem önbellek değişikliklerini gerçekleştiriyor hem de önbelleğe alınan girişleri sunmak için yönlendirmeyi ayarladı.precache()
artık yalnızca önbellek girişlerini değiştiriyor. Yeni yöntem olanaddRoute()
, önbelleğe alınan bu yanıtları sunmak için bir rota kaydetmek üzere kullanıma sunuldu. Önceki ikisi bir arada işlevi isteyen geliştiricilerprecacheAndRoute()
uygulamasını çağırmaya geçebilirler.- Daha önce
WorkboxSW
oluşturucu aracılığıyla yapılandırılan çeşitli seçenekler artıkworkbox.precaching.precacheAndRoute([...], options)
içindeoptions
parametresi olarak aktarılıyor. Bu seçenekler için varsayılanlar, yapılandırılmadığında referans dokümanlarında listelenmiştir. - Varsayılan olarak, dosya uzantısı olmayan URL'lerin
.html
uzantısı içeren bir önbellek girişiyle eşleşip eşleşmediği otomatik olarak kontrol edilir. Örneğin,/path/to/index
için istekte bulunulduğunda (önbelleğe alınmayan)/path/to/index.html
için önceden önbelleğe alınmış bir giriş varsa bu ön önbelleğe alınmış giriş kullanılır. Geliştiriciler, seçenekleriworkbox.precaching.precacheAndRoute()
uygulamasına aktarırken{cleanUrls: false}
ayarlayarak bu yeni davranışı devre dışı bırakabilirler. workbox-broadcast-update
artık önceden önbelleğe alınmış öğeler için önbellek güncellemelerini duyuracak şekilde otomatik olarak yapılandırılmayacak.
v2'de şu kod:
const workboxSW = new self.WorkboxSW({
directoryIndex: 'index.html',
ignoreUrlParametersMatching: [/^utm_/],
precacheChannelName: 'precache-updates',
});
workboxSW.precache([...]);
aşağıdaki gibi v3 eşdeğerine sahiptir:
workbox.precaching.addPlugins([
new workbox.broadcastUpdate.Plugin('precache-updates')
]);
workbox.precaching.precacheAndRoute([...], {
cleanUrls: false,
directoryIndex: 'index.html',
ignoreUrlParametersMatching: [/^utm_/],
});
çalışma kutusu yönlendirme
- Daha önce WorkboxSW nesnesinin
workbox.router.*
ad alanı üzerindenworkbox-routing
kullanan geliştiricilerin yeni ad alanına (workbox.routing.*
) geçmesi gerekir. - Rotalar artık ilk kaydedilenler sırasına göre değerlendiriliyor. Bu, v2'de kullanılan
Route
değerlendirmesinin karşıt sırasıdır. Burada son kaydedilenRoute
'e öncelik verilir. ExpressRoute
sınıfı ve "Ekspres stil" joker karakterleri desteği kaldırılmıştır. Bu,workbox-routing
öğesinin boyutunu önemli ölçüde küçültür.workbox.routing.registerRoute()
için ilk parametre olarak kullanılan dizeler artık tam eşleşme olarak değerlendirilecek. Joker karakter veya kısmi eşleşmelerRegExp
tarafından işlenmelidir. İstek URL'sinin bir kısmı veya tamamıyla eşleşen herhangi birRegExp
kullanılması bir rotayı tetikleyebilir.Router
sınıfınınaddFetchListener()
yardımcı yöntemi kaldırıldı. Geliştiriciler kendifetch
işleyicilerini açık bir şekilde ekleyebilir veyaworkbox.routing
tarafından sağlanan arayüzü kullanarak dolaylı yoldan birfetch
işleyici oluşturabilirler.registerRoutes()
veunregisterRoutes()
yöntemleri kaldırıldı. Bu yöntemlerin, tek birRoute
üzerinde çalışan sürümleri değiştirilmedi. Aynı anda birden fazla rotayı kaydetmesi veya kaydını iptal etmesi gereken geliştiriciler, bunun yerineregisterRoute()
veyaunregisterRoute()
için bir dizi çağrı yapmalıdır.
v2'de şu kod:
const workboxSW = new self.WorkboxSW();
workboxSW.router.registerRoute(
'/path/with/.*/wildcard/',
workboxSW.strategies.staleWhileRevalidate()
);
workboxSW.router.registerRoute(
new RegExp('^https://example.com/'),
workboxSW.strategies.networkFirst()
);
aşağıdaki gibi v3 eşdeğerine sahiptir:
workbox.routing.registerRoute(
new RegExp('^https://example.com/'),
workbox.strategies.networkFirst()
);
workbox.routing.registerRoute(
new RegExp('^/path/with/.*/wildcard'),
workbox.strategies.staleWhileRevalidate()
);
çalışma kutusu-stratejileri (eski adıyla çalışma kutusu çalışma zamanı önbelleğe alma)
workbox-runtime-caching
modülü artık resmi olarakworkbox-strategies
adıyla biliniyor venpm
ürününde yeni adıyla yayınlanmıştır.- Önbellek adı da sağlamadan bir stratejide önbellek geçerlilik sonu kullanımı artık geçerli değildir. v2'de bu mümkündü:
workboxSW.strategies.staleWhileRevalidate({
cacheExpiration: {maxEntries: 50},
});
Bu durum, varsayılan önbellekteki girişlerin süresinin dolmasına yol açar. Bu beklenmedik bir durumdur. v3'te bir önbellek adı gerekir:
workboxSW.strategies.staleWhileRevalidate({
cacheName: 'my-cache',
plugins: [new workbox.expiration.Plugin({maxEntries: 50})],
});
cacheWillMatch
yaşam döngüsü yöntemi,cachedResponseWillBeUsed
olarak yeniden adlandırıldı.cacheWillMatch
yönergesine tepki veren kendi eklentilerini yazmadıkları sürece bu değişiklik, geliştiriciler için görünür bir değişiklik olmamalıdır.- Bir strateji yapılandırırken eklentileri belirtmek için kullanılan söz dizimi değişti. Her bir eklentinin, strateji yapılandırmasının
plugins
özelliğinde açıkça listelenmesi gerekir.
v2'de şu kod:
const workboxSW = new self.WorkboxSW();
const networkFirstStrategy = workboxSW.strategies.networkFirst({
cacheName: 'my-cache',
networkTimeoutSeconds: 5,
cacheExpiration: {
maxEntries: 50,
},
cacheableResponse: {
statuses: [0, 200],
},
});
aşağıdaki gibi v3 eşdeğerine sahiptir:
const networkFirstStrategy = workbox.strategies.networkFirst({
cacheName: 'my-cache',
networkTimeoutSeconds: 5,
plugins: [
new workbox.expiration.Plugin({maxEntries: 50}),
new workbox.cacheableResponse.Plugin({statuses: [0, 200]}),
],
});
"Eklenti Kullanma" kılavuzundan daha fazla bilgi edinebilirsiniz.
çalışma kutusu-sw
workbox-sw
, temel bir yapılandırma gerektiren ve çalışma zamanında gerekli olan diğer modülleri çekmekten sorumlu olan, hafif bir "yükleyici" arayüzü olacak şekilde yeniden yazılmıştır. Geliştiriciler,WorkboxSW
sınıfının yeni bir örneğini oluşturmak yerine, genel ad alanında otomatik olarak sunulan mevcut bir örnekle etkileşime geçer.
v2'de öncekiler:
importScripts('<path to workbox-sw>/importScripts/workbox-sw.prod.v2.1.3.js');
const workbox = new WorkboxSW({
skipWaiting: true,
clientsClaim: true,
// etc.
});
workbox.router.registerRoute(...);
v3'te workbox-sw.js
komut dosyasını içe aktarmanız yeterlidir. Global ad alanında workbox
olarak, kullanıma hazır bir örnek otomatik olarak sunulur:
importScripts('<path to workbox-sw>/3.0.0/workbox-sw.js');
// workbox is implicitly created and ready for use.
workbox.routing.registerRoute(...);
skipWaiting
veclientsClaim
artıkWorkboxSW
oluşturucuya iletilen seçenekler değil. Bunun yerine,workbox.clientsClaim()
veworkbox.skipWaiting()
yöntemleri olarak değiştirildi.- Daha önce v2 oluşturucuda desteklenen
handleFetch
seçeneği artık v3'te desteklenmemektedir. Herhangi bir getirme işleyici kullanılmadan hizmet çalışanlarını test etmek için benzer işlevlere ihtiyaç duyan geliştiriciler, Chrome'un Geliştirici Araçları'nda bulunan "Ağ için atla" seçeneğini kullanabilir.
çalışma-kutusu-web-paketi-eklentisi
Eklenti önemli ölçüde yeniden yazılmıştır ve birçok durumda "sıfır yapılandırma" modunda kullanılabilir. Güncellenen API yüzeyi için belgelere bakın.
- API artık
GenerateSW
veInjectManifest
olmak üzere iki sınıfı kullanıma sunar. Bu, davranışınswSrc
varlığına göre değiştiği v2 davranışına kıyasla açık modlar arasında geçiş yapılmasını sağlar. - Varsayılan olarak, web paketi derleme ardışık düzenindeki öğeler önbelleğe alınır ve artık
globPatterns
öğesinin yapılandırılması gerekmez.globPatterns
ürününü kullanmaya devam etmenizin tek nedeni, web paketi derlemenize dahil olmayan öğeleri önbelleğe almanız gerekmesidir. Genel olarak, v3 eklentisine geçiş yaparkenglob
tabanlı tüm yapılandırmalarınızı kaldırarak başlamanız ve yalnızca özellikle ihtiyacınız varsa yeniden eklemeniz gerekir.
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.