Workbox v4 से v5 पर माइग्रेट करें

इस गाइड में, Workbox v5 में किए गए ताज़ा बदलावों के बारे में बताया गया है. साथ ही, इसमें वर्कबॉक्स v4 से अपग्रेड करते समय किए जाने वाले बदलावों के उदाहरण भी दिए गए हैं.

नुकसान पहुंचा सकने वाले बदलाव

प्लग इन क्लास के नाम बदले गए

कई Workbox v4 पैकेज में Plugin नाम की क्लास शामिल हैं. v5 में, उन क्लास के नाम बदलकर पैटर्न पैकेज आइडेंटिफ़ायर + Plugin को फ़ॉलो करने के लिए कर दिया गया है:

  • BackgroundSyncPlugin
  • BroadcastUpdatePlugin
  • CacheableResponsePlugin
  • ExpirationPlugin
  • RangeRequestsPlugin

नाम बदलने की यह प्रक्रिया लागू होती है, चाहे आप मॉड्यूल इंपोर्ट के ज़रिए क्लास का इस्तेमाल कर रहे हों या workbox.* नेमस्पेस के ज़रिए.

डिफ़ॉल्ट प्रीकैश मेनिफ़ेस्ट रीप्लेसमेंट पॉइंट

इससे पहले, "इंजेक्ट मेनिफ़ेस्ट" मोड में किसी बिल्ड टूल का इस्तेमाल करते समय, आपकी सोर्स सर्विस वर्कर फ़ाइल की precacheAndRoute([]) की मौजूदगी की जांच की जाती थी. इसमें, उस खाली ऐरे [] का इस्तेमाल प्लेसहोल्डर के तौर पर, उस पॉइंट के लिए किया जाता था जहां से प्रीकैश मेनिफ़ेस्ट इंजेक्ट किया गया था.

Workbox v5 में, रिप्लेसमेंट लॉजिक बदल गया है. अब self.__WB_MANIFEST को डिफ़ॉल्ट रूप से इंजेक्शन पॉइंट के तौर पर इस्तेमाल किया जाता है.

// v4:
precacheAndRoute([]);

// v5:
precacheAndRoute(self.__WB_MANIFEST);

जैसा कि इस चर्चा में बताया गया है, हमारा मानना है कि यह बदलाव आसान अनुभव देता है. साथ ही, कस्टम सर्विस वर्कर कोड में इंजेक्ट किए गए मेनिफ़ेस्ट का इस्तेमाल करने के तरीके पर ज़्यादा कंट्रोल देता है. अगर ज़रूरत हो, तो injectionPoint कॉन्फ़िगरेशन के विकल्प के ज़रिए इस रिप्लेसमेंट स्ट्रिंग को बदला जा सकता है.

नेविगेशन रूट के लिए इस्तेमाल किए जा रहे दो विकल्पों blacklist और whitelist का नाम बदलकर, denylist और allowlist कर दिया गया है.

workbox-routing ने पहले एक तरीके registerNavigationRoute() का इस्तेमाल किया था. इस तरीके ने बेहतर तरीके से दो काम किए:

  1. पता लगाया गया कि दिए गए fetch इवेंट में, 'navigate' में से mode शामिल है या नहीं.
  2. अगर हां, तो उस अनुरोध का जवाब, पहले से कैश मेमोरी में सेव किए गए, हार्डकोड किए गए यूआरएल के कॉन्टेंट का इस्तेमाल करके दिया गया था. भले ही, यूआरएल को किसी भी यूआरएल पर नेविगेट किया जा रहा हो.

ऐप्लिकेशन शेल आर्किटेक्चर को लागू करते समय, यह एक सामान्य पैटर्न है.

दूसरे चरण में, कैश मेमोरी से डेटा देखकर जवाब जनरेट करना, workbox-routing की ज़िम्मेदारियों के दायरे में नहीं आता. इसके बजाय, हम इसे एक नए तरीके createHandlerBoundToURL() के ज़रिए, ऐसी सुविधा के रूप में देखते हैं जिसे workbox-precaching का हिस्सा होना चाहिए. इस नए तरीके से उसी लॉजिक को पूरा करने के लिए, workbox-routing में मौजूदा NavigationRoute क्लास के साथ काम किया जा सकता है.

अगर बिल्ड टूल के "SW जनरेट करें" मोड में navigateFallback विकल्प का इस्तेमाल किया जा रहा है, तो स्विचओवर अपने-आप हो जाएगा. अगर आपने पहले navigateFallbackBlacklist या navigateFallbackWhitelist विकल्पों में से किसी एक को कॉन्फ़िगर किया था, तो उन्हें क्रम से navigateFallbackDenylist या navigateFallbackAllowlist में बदलें.

अगर "मेनिफ़ेस्ट इंजेक्ट" मोड का इस्तेमाल किया जा रहा है या खुद ही सर्विस वर्कर लिखा जा रहा है और आपका Workbox v4 सर्विस वर्कर सीधे तौर पर registerNavigationRoute() को कॉल करता है, तो आपको उसी तरह का व्यवहार पाने के लिए, अपने कोड में बदलाव करना होगा.

// 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);

अब आपको getCacheKeyForURL() को कॉल करने की ज़रूरत नहीं है, क्योंकि createHandlerBoundToURL() आपकी मदद करेगा.

वर्कबॉक्स रणनीति से createRequest() को हटाना

makeRequest() को कॉल करने का मतलब है, workbox-strategy में से किसी एक क्लास में handle() को कॉल करना. दोनों तरीकों में इतना अंतर था कि दोनों को एक साथ रखने का कोई मतलब नहीं बनता. जिन डेवलपर ने makeRequest() को कॉल किया है वे बिना कोई बदलाव किए, handle() का इस्तेमाल कर सकते हैं:

// v4:
const strategy = new StaleWhileRevalidate({...});
const response = await strategy.makeRequest({event, request});

// v5:
const strategy = new StaleWhileRevalidate({...});
const response = await strategy.handle({event, request});

वर्शन 5 में, handle(), request को ज़रूरी पैरामीटर मानता है और event.request का इस्तेमाल नहीं करेगा. handle() को कॉल करते समय पक्का करें कि आपने मान्य अनुरोध भेजा हो.

Workbox-broadcast-update हमेशा postMessage() का इस्तेमाल करता है

वर्शन 4 में, workbox-broadcast-update लाइब्रेरी डिफ़ॉल्ट रूप से ब्रॉडकास्ट चैनल एपीआई का इस्तेमाल करेगी, ताकि इसके साथ काम करने पर मैसेज भेजे जा सकें. साथ ही, postMessage() सिर्फ़ तब इस्तेमाल किया जाएगा, जब ब्रॉडकास्ट चैनल काम नहीं करेगा.

हमने महसूस किया कि इनकमिंग मैसेज के दो संभावित सोर्स को सुनना और क्लाइंट-साइड कोड लिखना बहुत मुश्किल हो गया. इसके अलावा, कुछ ब्राउज़र पर, क्लाइंट पेजों को भेजे गए सर्विस वर्कर से किए गए postMessage() कॉल अपने-आप बफ़र हो जाते हैं. ऐसा तब तक होता है, जब तक message इवेंट लिसनर सेट अप नहीं हो जाता. ब्रॉडकास्ट चैनल एपीआई में कोई बफ़रिंग नहीं होती. साथ ही, अगर ब्रॉडकास्ट किए गए मैसेज क्लाइंट पेज पर आने से पहले भेजे जाते हैं, तो उन्हें छोड़ दिया जाता है.

इन्हीं वजहों से, हमने workbox-broadcast-update को बदलकर, हमेशा v5 में postMessage() कर दिया है. मैसेज, मौजूदा सर्विस वर्कर के दायरे में आने वाले सभी क्लाइंट पेजों पर एक-एक करके भेजे जाते हैं.

इस नई कार्रवाई में बदलाव करने के लिए, BroadcastChannel इंस्टेंस बनाने वाले क्लाइंट पेजों पर मौजूद किसी भी कोड को हटाया जा सकता है. इसके बजाय, navigator.serviceWorker पर message इवेंट लिसनर सेट अप करें:

// 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 ...
  }
});

workbox-window उपयोगकर्ताओं को कोई बदलाव करने की ज़रूरत नहीं है, क्योंकि postMessage() कॉल को सुनने के लिए इसका इंटरनल लॉजिक अपडेट किया गया है.

बिल्ड टूल के लिए Node.js v8 या इससे ऊपर के वर्शन की ज़रूरत होती है

workbox-webpack-plugin, workbox-build या workbox-cli के लिए, v8 से पहले के Node.js वर्शन अब काम नहीं करते. अगर आपके पास 8 से पहले का Node.js वर्शन है, तो अपने रनटाइम को काम करने वाले वर्शन में अपडेट करें.

वर्कबॉक्स-वेबपैक-प्लगिन को webpack v4 या इससे ऊपर के वर्शन की ज़रूरत होती है

अगर workbox-webpack-plugin का इस्तेमाल किया जा रहा है, तो कम से कम webpack v4 का इस्तेमाल करने के लिए, अपने वेबपैक सेटअप को अपडेट करें.

बिल्ड टूल के विकल्प में बदलाव करें

कई workbox-build, workbox-cli, और workbox-webpack-plugin कॉन्फ़िगरेशन पैरामीटर अब काम नहीं करते. उदाहरण के लिए, generateSW आपके लिए हमेशा एक लोकल Workbox रनटाइम बंडल बनाएगा, इसलिए importWorkboxFrom विकल्प का अब कोई मतलब नहीं बनता.

इस्तेमाल किए जा सकने वाले विकल्पों की सूची के लिए, उससे जुड़े टूल के दस्तावेज़ देखें.

वर्कबॉक्स-बिल्ड से generateSWString को हटाना

generateSWString मोड को workbox-build से हटा दिया गया है. हमें उम्मीद है कि इससे कम असर पड़ेगा, क्योंकि इसे मुख्य रूप से workbox-webpack-plugin ने अंदरूनी तौर पर इस्तेमाल किया है.

वैकल्पिक बदलाव

मॉड्यूल इंपोर्ट का इस्तेमाल करना

हालांकि यह बदलाव a) वैकल्पिक है और b) Workbox v4 का इस्तेमाल करते समय तकनीकी रूप से संभव था, लेकिन v5 में बदलने के दौरान हमारे हिसाब से सबसे बड़ा बदलाव ऐसा मॉडल है जिसमें वर्कबॉक्स के मॉड्यूल इंपोर्ट करके अपना खुद का बंडल किया गया सर्विस वर्कर बनाया जाता है. यह तरीका, आपके सर्विस वर्कर में सबसे ऊपर importScripts('/path/to/workbox-sw.js') को कॉल करने और workbox.* नेमस्पेस के ज़रिए Workbox का इस्तेमाल करने का विकल्प है.

अगर "SW जनरेट करें" मोड में किसी बिल्ड टूल (workbox-webpack-plugin, workbox-build, workbox-cli) का इस्तेमाल किया जा रहा है, तो यह बदलाव अपने-आप होगा. वे सभी टूल, आपके सर्विस वर्कर लॉजिक को लागू करने के लिए ज़रूरी असल कोड के साथ-साथ Workbox रनटाइम का एक लोकल, कस्टम बंडल आउटपुट करेंगे. इस स्थिति में, अब workbox-sw या Workbox की CDN कॉपी पर कोई डिपेंडेंसी नहीं होगी. आपके inlineWorkboxRuntime कॉन्फ़िगरेशन की वैल्यू के आधार पर, वर्कबॉक्स रनटाइम को या तो अलग फ़ाइल में बांटा जाएगा, जिसे आपके सर्विस वर्कर के साथ डिप्लॉय किया जाना चाहिए (जब डिफ़ॉल्ट तौर पर false पर सेट किया जाता है) या इसे सर्विस वर्कर लॉजिक (true पर सेट होने पर) के साथ इनलाइन शामिल किया जाना चाहिए.

अगर "इंजेक्ट मेनिफ़ेस्ट" मोड में बिल्ड टूल का इस्तेमाल किया जा रहा है या Workbox के बिल्ड टूल का इस्तेमाल नहीं किया जा रहा है, तो आपके पास मौजूदा Workbox के साथ बंडलर (वेबपैक/रोलअप) का इस्तेमाल करना गाइड में, अपना खुद का Workbox रनटाइम बंडल बनाने के बारे में ज़्यादा जानने का विकल्प है.

v5 के दस्तावेज़ और उदाहरण, मॉड्यूल इंपोर्ट सिंटैक्स के हिसाब से लिखे जाते हैं. हालांकि, Workbox v5 में workbox.* नेमस्पेस काम करता रहेगा.

पहले से कैश मेमोरी में सेव किए गए जवाब पढ़े जा रहे हैं

कुछ डेवलपर को सीधे कैश मेमोरी से, पहले से कैश मेमोरी में सेव किए गए रिस्पॉन्स पढ़ने की ज़रूरत होती है. उन्हें precacheAndRoute() तरीके से सीधे तौर पर इस्तेमाल करने के बजाय, उन्हें सीधे कैश मेमोरी से पढ़ना होता है. v4 में एक सामान्य पैटर्न यह है कि पहले कैश मेमोरी में सेव की गई कुंजी को, पहले से मौजूद किसी संसाधन के मौजूदा वर्शन के लिए इस्तेमाल किया जाए. इसके बाद, Response पाने के लिए उस कुंजी को प्रीकैश मेमोरी के नाम के साथ caches.match() को पास कर दिया जाए.

इस प्रोसेस को आसान बनाने के लिए, v5 में मौजूद workbox-precaching एक नई और मिलती जुलती विधि matchPrecache() के साथ काम करता है:

// 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`);

टाइपस्क्रिप्ट अडॉप्शन

v5 में, Workbox रनटाइम लाइब्रेरी को TypeScript में लिखा जाता है. हालांकि, हम टाइपस्क्रिप्ट का इस्तेमाल न करने वाले डेवलपर को शामिल करने के लिए ट्रांसपाइल किए गए JavaScript मॉड्यूल और बंडल को पब्लिश करना जारी रखेंगे. हालांकि, अगर आप TypeScript का इस्तेमाल करते हैं, तो आपको सीधे Workbox प्रोजेक्ट से मिलने वाली सटीक और हमेशा अप-टू-डेट जानकारी का फ़ायदा मिलेगा.

माइग्रेशन का उदाहरण

यह प्रतिबद्धता इस बात को दिखाती है कि माइग्रेशन की प्रोसेस काफ़ी अहम है और इसमें इनलाइन कमेंट्री शामिल है. यह सीडीएन से रनटाइम लोड करने के बजाय, फ़ाइनल सर्विस वर्कर में कस्टम वर्कबॉक्स रनटाइम को शामिल करने के लिए, रोलअप का इस्तेमाल करता है.

हालांकि, इसमें हर अहम बदलाव को शामिल नहीं किया गया है, लेकिन यहां एक सर्विस वर्कर फ़ाइल को v4 से v5 में अपग्रेड करने के पहले और बाद में बताया गया है. इसमें टाइपस्क्रिप्ट पर स्विच करना भी शामिल है.

मदद लेना

हमारा अनुमान है कि ज़्यादातर माइग्रेशन आसान होंगे. अगर आपको कोई ऐसी समस्या है जो इस गाइड में शामिल नहीं है, तो GitHub पर समस्या की जानकारी दें और हमें बताएं.