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

इस गाइड में, Workbox v3 में हुए बदलावों के बारे में जानकारी दी गई है. साथ ही, इसमें बताया गया है कि Workspace v2 को सेटअप करने के दौरान आपको क्या-क्या बदलाव करने होंगे.

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

v3 बैकग्राउंड

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

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

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

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

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

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

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

workbox-background-sync

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

workbox-broadcast-cache-update

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

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

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

वर्शन 3 का एक जैसा इस्तेमाल:

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

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

workbox-build

• डिफ़ॉल्ट रूप से, glob पैटर्न को मैच करने की प्रोसेस, अब विकल्प follow: true (जो सिमलिंक के बाद होगी) और strict: true (जो "असामान्य" गड़बड़ियों को कम सहन कर सकती है) की मदद से की जाएगी. इन दोनों में से किसी को भी बंद किया जा सकता है और बिल्ड कॉन्फ़िगरेशन में globFollow: false और/या globStrict: false को सेट करके, पिछली कार्रवाई पर वापस जाया जा सकता है.
• workbox-build के सभी फ़ंक्शन, रिस्पॉन्स में मिलने वाले रिस्पॉन्स में warnings अतिरिक्त प्रॉपर्टी दिखाते हैं. कुछ ऐसी स्थितियों को अब अनुमति दी गई है जिन्हें वर्शन 2 में गंभीर गड़बड़ियों के तौर पर देखा गया था. हालांकि, इनकी रिपोर्ट 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}`));

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

v2 में इस तरह के कोड:

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-cache-expiration

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

workbox-cli

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

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

अगर एक साथ देखा जाए, तो इसका मतलब है कि v2 में:

$ 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.* पर स्विच करना होगा.
• अब रूट का आकलन, पहले-रजिस्टर किए गए उपयोगकर्ताओं के क्रम में किया जाता है. यह वर्शन 2 में इस्तेमाल किए गए Route आकलन का गलत क्रम है. इसमें आखिरी बार रजिस्टर किए गए Route को प्राथमिकता दी जाएगी.
• ExpressRoute क्लास और "Express-style" की सुविधा वाइल्डकार्ड हटा दिए गए हैं. इससे workbox-routing का साइज़ काफ़ी कम हो जाता है. workbox.routing.registerRoute() के लिए पहले पैरामीटर के तौर पर इस्तेमाल की गई स्ट्रिंग को अब एग्ज़ैक्ट मैच माना जाएगा. वाइल्डकार्ड या आंशिक मिलान को RegExp मैनेज करता है—ऐसा किसी भी 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 के डेवलपर टूल में उपलब्ध है.

workbox-webpack-plugin

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

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

सहायता पाना

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