Workbox v2 से v3 पर माइग्रेट करना

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

अगर sw-precache/sw-toolbox के लेगसी कॉम्बिनेशन का इस्तेमाल किया जा रहा है और आपको पहली बार वर्कबॉक्स पर अपग्रेड करना है, तो यहां डेटा को दूसरी जगह भेजने से जुड़ी गाइड दी गई है. इससे आपको मदद मिलेगी.

v3 बैकग्राउंड

वर्कबॉक्स की v3 रिलीज़, मौजूदा कोडबेस की एक महत्वपूर्ण रीफ़ैक्टरिंग है. इसके मुख्य लक्ष्य हैं:

• वर्कबॉक्स का साइज़ छोटा करें. डाउनलोड और एक्ज़ीक्यूट किए गए सर्विस वर्कर रनटाइम कोड की संख्या कम कर दी गई है. सभी को मोनोलिथिक बंडल में ऑप्ट-इन करने के बजाय, रनटाइम के दौरान सिर्फ़ उन खास सुविधाओं का कोड इंपोर्ट किया जाएगा जिनका इस्तेमाल किया जा रहा है.
• वर्कबॉक्स में सीडीएन है. हम Workbox की रनटाइम लाइब्रेरी को ऐक्सेस करने के लिए, कैननिकल विकल्प के तौर पर Google Cloud Storage पर आधारित सीडीएन होस्टिंग को पूरी तरह से इस्तेमाल करने की सुविधा देते हैं. इससे Workbox के साथ काम करना और इस्तेमाल करना आसान हो जाता है.
• बेहतर डीबगिंग और लॉग. डीबग और लॉग करने का अनुभव काफ़ी बेहतर हो गया है. डीबग लॉग डिफ़ॉल्ट रूप से चालू हो जाते हैं. ऐसा तब होता है, जब वर्कबॉक्स को localhost ऑरिजिन से इस्तेमाल किया जाता है. साथ ही, प्रोडक्शन बिल्ड से सभी लॉगिंग और दावे हटा दिए जाते हैं.
• बेहतर webpack प्लगिन. workbox-webpack-plugin, वेबपैक बनाने की प्रोसेस के साथ बेहतर तरीके से इंटिग्रेट करता है. इससे, बिल्ड पाइपलाइन में सभी एसेट प्री-कैश होने पर, इस्तेमाल के उदाहरण के लिए शून्य भी कॉन्फ़िगर किया जा सकता है.

इन लक्ष्यों को पूरा करने और पिछले इंटरफ़ेस के कुछ पहलुओं को साफ़ करने के लिए, जो अजीब महसूस हुए थे या जिनके कारण एंटीपैटर्न थे. इसके लिए, v3 रिलीज़ में कई नुकसान पहुंचा सकने वाले बदलाव शामिल करना ज़रूरी था.

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

बिल्ड कॉन्फ़िगरेशन

ये बदलाव, हमारे उन सभी बिल्ड टूल (workbox-build, workbox-cli, workbox-webpack-plugin) के काम करने के तरीके पर असर डालते हैं जिनमें कॉन्फ़िगरेशन के विकल्पों का एक ही सेट शामिल है.

• 'fastest' हैंडलर का नाम पहले मान्य था और runtimeCaching को कॉन्फ़िगर करते समय, इसे 'staleWhileRevalidate' के लिए उपनाम के तौर पर माना जाता था. अब यह मान्य नहीं है और डेवलपर को सीधे 'staleWhileRevalidate' का इस्तेमाल करना चाहिए.
• runtimeCaching.options प्रॉपर्टी के कई नाम अपडेट किए गए हैं. साथ ही, अन्य पैरामीटर की पुष्टि की जा रही है. इसकी वजह से, अमान्य कॉन्फ़िगरेशन का इस्तेमाल करने पर बिल्ड फ़ेल हो जाएगा. फ़िलहाल, उपलब्ध विकल्पों की सूची के लिए, runtimeCaching का दस्तावेज़ देखें.

वर्कबॉक्स-बैकग्राउंड-सिंक

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

workbox-broadcast-cache-update

• अब चैनल के नाम को दिखाने वाली एक ज़रूरी स्ट्रिंग मौजूद है. प्लगिन या स्टैंडअलोन क्लास बनाते समय, इसे पहले पैरामीटर के तौर पर पास किया जाना चाहिए.

उदाहरण के लिए, v2 में प्लगिन क्लास को इस तरह शुरू किया जाएगा:

new workbox.broadcastCacheUpdate.BroadcastCacheUpdatePlugin({
  channelName: 'cache-updates',
  headersToCheck: ['etag'],
});

v3 में इसके बराबर इस्तेमाल हैं:

new workbox.broadcastUpdate.Plugin('cache-updates', {headersToCheck: ['etag']});

एपीआई के अपडेट किए गए प्लैटफ़ॉर्म के बारे में जानने के लिए, दस्तावेज़ देखें.

वर्कबॉक्स-बिल्ड

• डिफ़ॉल्ट रूप से, glob पैटर्न मिलान को अब विकल्प follow: true (जो सिमलिंक का अनुसरण करेगा) और strict: true (जो "असामान्य" गड़बड़ियों को कम सहन करता है) से किया जाएगा. आपके पास दोनों में से किसी को भी बंद करने और बिल्ड कॉन्फ़िगरेशन में globFollow: false और/या globStrict: false को सेट करके, पिछले व्यवहार पर वापस जाने का विकल्प होता है.
• workbox-build के सभी फ़ंक्शन, उनके मिलने वाले जवाबों में warnings अतिरिक्त प्रॉपर्टी दिखाते हैं. कुछ स्थितियों को अब v2 में गंभीर गड़बड़ियों के रूप में माना जाता है. हालांकि, इन्हें warnings के ज़रिए रिपोर्ट किया गया है, जो स्ट्रिंग का एक कलेक्शन है.

वर्शन 2 में, आप generateSW को इस तरह कॉल कर सकते हैं:

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

हालांकि, उसी कोड का इस्तेमाल v3 में किया जा सकता है. हालांकि, किसी warnings का पता लगाना और उसे लॉग करना बेहतर रहेगा:

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 में अपना कस्टम ManifestTransform फ़ंक्शन लिखा है उन्हें किसी ऑब्जेक्ट (जैसे कि return manifestArray; के बजाय, आपको return {manifest: manifestArray}; का इस्तेमाल करना चाहिए) में मेनिफ़ेस्ट अरे दिखाना होगा. m इससे आपका प्लगिन एक वैकल्पिक warnings प्रॉपर्टी शामिल करता है. यह उन स्ट्रिंग का कलेक्शन होना चाहिए जिनमें नुकसान पहुंचाने वाली चेतावनी की जानकारी मौजूद नहीं है.

अगर v2 में पसंद के मुताबिक ManifestTransform लिखा जा रहा था, तो इस तरह कोड करें:

const cdnTransform = manifestEntries => {
  return manifestEntries.map(entry => {
    const cdnOrigin = 'https://example.com';
    if (entry.url.startsWith('/assets/')) {
      entry.url = cdnOrigin + entry.url;
    }
    return entry;
  });
};

इसके v3 के बराबर है:

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() फ़ंक्शन का नाम बदलकर getManifest() कर दिया गया है. साथ ही, प्रॉमिस में, पहले से कैश मेमोरी में सेव किए गए यूआरएल के बारे में अन्य जानकारी भी शामिल है.

वर्शन 2 में नीचे दिए गए कोड की तरह:

const manifestEntries = await workboxBuild.getFileManifestEntries({...});

v3 में इस तरह से दोबारा लिखा जा सकता है:

const {manifestEntries, count, size, warnings} = await workboxBuild.getManifest({...});

// Use manifestEntries like before.
// Optionally, log the new info returned in count, size, warnings.

• generateFileManifest() फ़ंक्शन हटा दिया गया है. डेवलपर को इसके बजाय getManifest() को कॉल करने और डिस्क पर डेटा को सही फ़ॉर्मैट में लिखने के लिए, इसके जवाब का इस्तेमाल करने का सुझाव दिया जाता है.

वर्कबॉक्स-कैश-खत्म

• प्लगिन एपीआई में कोई बदलाव नहीं किया गया है. ज़्यादातर डेवलपर इस मोड का इस्तेमाल करेंगे. हालांकि, एपीआई में हुए अहम बदलावों का असर उन डेवलपर पर पड़ा है जो इसे स्टैंडअलोन क्लास के तौर पर इस्तेमाल करते हैं. एपीआई के अपडेट किए गए प्लैटफ़ॉर्म के बारे में जानने के लिए, दस्तावेज़ देखें.

workbox-cli

डेवलपर काम करने वाले पैरामीटर के पूरे सेट के लिए, --help फ़्लैग के साथ सीएलआई चला सकते हैं.

• बाइनरी स्क्रिप्ट के लिए, workbox-cli उपनाम का इस्तेमाल नहीं किया जा सकता. बाइनरी को अब सिर्फ़ workbox के तौर पर ऐक्सेस किया जा सकता है.
• v3 में मौजूद v2 कमांड generate:sw और inject:manifest के नाम को बदलकर, generateSW और injectManifest कर दिया गया है.
• v2 में, डिफ़ॉल्ट कॉन्फ़िगरेशन फ़ाइल (उस समय इस्तेमाल की जाती है जब किसी फ़ाइल को खास तौर पर उपलब्ध नहीं कराया गया था) को मौजूदा डायरेक्ट्री में workbox-cli-config.js माना जाता है. वर्शन 3 में, यह workbox-config.js है.

अगर साथ में ले लिया जाए, तो इसका मतलब है कि वर्शन 2 में:

$ workbox inject:manifest

workbox-cli-config.js और v3 से पढ़े गए कॉन्फ़िगरेशन का इस्तेमाल करके, "इंजेक्ट मेनिफ़ेस्ट" बिल्ड प्रोसेस चलाएगा:

$ workbox injectManifest

यही काम करेगा, लेकिन workbox-config.js से कॉन्फ़िगरेशन पढ़ें.

वर्कबॉक्स-प्रीकैशिंग

• precache() तरीके ने पहले, दोनों कैश मेमोरी में बदलाव किए थे और कैश मेमोरी में सेव की गई एंट्री दिखाने के लिए रूटिंग सेट अप की थी. अब precache() सिर्फ़ कैश एंट्री में बदलाव करता है. साथ ही, कैश मेमोरी में सेव किए गए इन रिस्पॉन्स को दिखाने के लिए, रूट रजिस्टर करने के लिए एक नया तरीका addRoute() दिखाया गया है. जिन डेवलपर को पिछली टू-इन-वन सुविधा का इस्तेमाल करना है वे precacheAndRoute() पर कॉल कर सकते हैं.
• WorkboxSW कंस्ट्रक्टर की मदद से कॉन्फ़िगर किए जाने वाले कई विकल्प, अब workbox.precaching.precacheAndRoute([...], options) में options पैरामीटर के तौर पर पास किए जाते हैं. जब उन विकल्पों को कॉन्फ़िगर नहीं किया जाता है, तो उनकी डिफ़ॉल्ट सेटिंग पहचान फ़ाइलों में मौजूद होती है.
• डिफ़ॉल्ट रूप से, जिन यूआरएल में कोई फ़ाइल एक्सटेंशन नहीं होता है उनकी जांच अपने-आप ऐसी कैश एंट्री से की जाएगी जिसमें .html एक्सटेंशन मौजूद हो. उदाहरण के लिए, अगर /path/to/index के लिए अनुरोध किया गया है (जो प्रीकैश नहीं किया गया है) और /path/to/index.html के लिए पहले से कैश मेमोरी में सेव की गई एंट्री है, तो पहले से कैश मेमोरी में सेव की गई एंट्री का इस्तेमाल किया जाएगा. डेवलपर इस नई सुविधा को बंद कर सकते हैं. इसके लिए, उन्हें workbox.precaching.precacheAndRoute() में विकल्प पास करते समय, {cleanUrls: false} को सेट करना होगा.
• workbox-broadcast-update, अब पहले से कैश मेमोरी में सेव की गई एसेट के कैश अपडेट की सूचना देने के लिए, अपने-आप कॉन्फ़िगर नहीं होगा.

v2 में नीचे दिया गया कोड:

const workboxSW = new self.WorkboxSW({
  directoryIndex: 'index.html',
  ignoreUrlParametersMatching: [/^utm_/],
  precacheChannelName: 'precache-updates',
});
workboxSW.precache([...]);

इसके v3 के बराबर है:

workbox.precaching.addPlugins([
    new workbox.broadcastUpdate.Plugin('precache-updates')
]);

workbox.precaching.precacheAndRoute([...], {
  cleanUrls: false,
  directoryIndex: 'index.html',
  ignoreUrlParametersMatching: [/^utm_/],
});

वर्कबॉक्स-रूटिंग

• जिन डेवलपर ने पहले WorkboxSW ऑब्जेक्ट के workbox.router.* नेमस्पेस के ज़रिए workbox-routing का इस्तेमाल किया है उन्हें नए नेमस्पेस, workbox.routing.* पर स्विच करना होगा.
• अब रूट का आकलन, पहले रजिस्टर करने वाले लोगों के क्रम में किया जाता है. यह Route के आकलन का विपरीत क्रम है, जिसका इस्तेमाल v2 में किया गया था. इसमें, आखिरी बार रजिस्टर किए गए Route को प्राथमिकता दी जाएगी.
• ExpressRoute क्लास और "एक्सप्रेस-स्टाइल" वाइल्डकार्ड की सुविधा हटा दी गई है. इससे workbox-routing का साइज़ काफ़ी कम हो गया. workbox.routing.registerRoute() के लिए पहले पैरामीटर के तौर पर इस्तेमाल की गई स्ट्रिंग को अब एग्ज़ैक्ट मैच माना जाएगा. वाइल्डकार्ड या आंशिक मिलानों को RegExps की मदद से हैंडल किया जाना चाहिए—ऐसे किसी भी RegExp का इस्तेमाल करके जो अनुरोध के किसी हिस्से या पूरे अनुरोध यूआरएल से मेल खाता है, कोई रूट ट्रिगर कर सकता है.
• Router क्लास का addFetchListener() हेल्पर तरीका हटा दिया गया है. डेवलपर साफ़ तौर पर अपना fetch हैंडलर जोड़ सकते हैं या workbox.routing के इंटरफ़ेस का इस्तेमाल कर सकते हैं. यह इंटरफ़ेस, साफ़ तौर पर उनके लिए fetch हैंडलर बना देगा.
• registerRoutes() और unregisterRoutes() तरीके हटा दिए गए थे. एक Route पर काम करने वाले उन तरीकों के वर्शन को नहीं बदला गया है. जिन डेवलपर को एक साथ कई रास्तों को रजिस्टर या रजिस्ट्रेशन रद्द करना है उन्हें इसके बजाय registerRoute() या unregisterRoute() पर कॉल की एक सीरीज़ बनानी चाहिए.

v2 में नीचे दिया गया कोड:

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

इसके v3 के बराबर है:

workbox.routing.registerRoute(
  new RegExp('^https://example.com/'),
  workbox.strategies.networkFirst()
);

workbox.routing.registerRoute(
  new RegExp('^/path/with/.*/wildcard'),
  workbox.strategies.staleWhileRevalidate()
);

वर्कबॉक्स-स्ट्रेटजी (पहले इन्हें वर्कबॉक्स-रनटाइम-कैशिंग के तौर पर जाना जाता था)

• workbox-runtime-caching मॉड्यूल को अब आधिकारिक तौर पर workbox-strategies के नाम से जाना जाता है. इसे नए नाम से npm पर पब्लिश किया गया है.
• रणनीति में कैश मेमोरी का नाम डाले बिना भी, कैश मेमोरी की समयसीमा खत्म होने की तारीख का इस्तेमाल करना अब मान्य नहीं है. वर्शन 2 में यह संभव था:

workboxSW.strategies.staleWhileRevalidate({
  cacheExpiration: {maxEntries: 50},
});

इससे डिफ़ॉल्ट कैश में एंट्री की समयसीमा खत्म हो जाएगी, जो कि अनचाहे तरीके से होती है. वर्शन 3 में कैश मेमोरी का नाम ज़रूरी है:

workboxSW.strategies.staleWhileRevalidate({
  cacheName: 'my-cache',
  plugins: [new workbox.expiration.Plugin({maxEntries: 50})],
});

• cacheWillMatch लाइफ़साइकल तरीके का नाम बदलकर cachedResponseWillBeUsed कर दिया गया है. यह बदलाव डेवलपर को तब तक नहीं दिखेगा, जब तक कि उन्होंने खुद के ऐसे प्लगिन न लिखे हों जिनका जवाबcacheWillMatch के मुताबिक हो.
• रणनीति को कॉन्फ़िगर करते समय, प्लगिन तय करने के लिए सिंटैक्स बदल गया है. रणनीति के कॉन्फ़िगरेशन की plugins प्रॉपर्टी में, हर प्लगिन की सूची साफ़ तौर पर शामिल होनी चाहिए.

v2 में नीचे दिया गया कोड:

const workboxSW = new self.WorkboxSW();

const networkFirstStrategy = workboxSW.strategies.networkFirst({
  cacheName: 'my-cache',
  networkTimeoutSeconds: 5,
  cacheExpiration: {
    maxEntries: 50,
  },
  cacheableResponse: {
    statuses: [0, 200],
  },
});

इसके v3 के बराबर है:

const networkFirstStrategy = workbox.strategies.networkFirst({
  cacheName: 'my-cache',
  networkTimeoutSeconds: 5,
  plugins: [
    new workbox.expiration.Plugin({maxEntries: 50}),
    new workbox.cacheableResponse.Plugin({statuses: [0, 200]}),
  ],
});

"प्लगिन का इस्तेमाल करना" गाइड में आपको ज़्यादा जानकारी मिल सकती है.

वर्कबॉक्स-sw

• इसके तहत, workbox-sw को एक लाइटवेट "लोडर" इंटरफ़ेस के तौर पर फिर से लिखा गया है, जो कुछ बुनियादी कॉन्फ़िगरेशन लेता है. साथ ही, यह रनटाइम के दौरान ज़रूरी अन्य मॉड्यूल को खींचने के लिए ज़िम्मेदार है. WorkboxSW क्लास का नया इंस्टेंस बनाने के बजाय, डेवलपर ऐसे मौजूदा इंस्टेंस के साथ इंटरैक्ट करेंगे जो ग्लोबल नेमस्पेस में अपने-आप सार्वजनिक होता है.

पहले वर्शन 2 में:

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(...);

वर्शन 3 में, आपको सिर्फ़ workbox-sw.js स्क्रिप्ट इंपोर्ट करनी होती है. इससे इस्तेमाल के लिए तैयार इंस्टेंस, ग्लोबल नेमस्पेस में अपने-आप workbox के तौर पर उपलब्ध हो जाएगा:

importScripts('<path to workbox-sw>/3.0.0/workbox-sw.js');

// workbox is implicitly created and ready for use.
workbox.routing.registerRoute(...);

• skipWaiting और clientsClaim, अब WorkboxSW कंस्ट्रक्टर को पास नहीं किए गए हैं. इसके बजाय, उन्हें workbox.clientsClaim() और workbox.skipWaiting() तरीकों में बदल दिया गया है.
• handleFetch विकल्प, जो पहले v2 कंस्ट्रक्टर में काम करता था, अब v3 में काम नहीं करता. जिन डेवलपर को किसी भी फ़ेच हैंडलर को शुरू किए बिना अपने सर्विस वर्कर की जांच करने के लिए, मिलती-जुलती सुविधा की ज़रूरत है वे Chrome के डेवलपर टूल में मौजूद "नेटवर्क के लिए बायपास" विकल्प का इस्तेमाल कर सकते हैं.

वर्कबॉक्स-वेबपैक-प्लगिन

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

• यह एपीआई अब दो क्लास, GenerateSW और InjectManifest दिखाता है. इससे, अलग-अलग मोड के बीच टॉगल करना साफ़ हो जाता है. साथ ही, v2 मोड के बीच टॉगल करना आसान हो जाता है, जहां swSrc की मौजूदगी के आधार पर व्यवहार बदल जाता है.
• डिफ़ॉल्ट रूप से, वेबपैक कंपाइलेशन पाइपलाइन में मौजूद एसेट प्री-कैश की जाएंगी. साथ ही, अब globPatterns को कॉन्फ़िगर करने की ज़रूरत नहीं है. globPatterns का इस्तेमाल जारी रखने की सिर्फ़ एक वजह यह है कि आपको उन एसेट को प्रीकैश करना है जो आपके वेबपैक बिल्ड में शामिल नहीं हैं. आम तौर पर, v3 प्लगिन पर माइग्रेट करते समय, आपको glob पर आधारित सभी पिछले कॉन्फ़िगरेशन हटाकर, शुरुआत करनी चाहिए. साथ ही, ज़रूरत पड़ने पर ही इसे दोबारा जोड़ना चाहिए.

सहायता पाना

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