העברה מ-sw-precache או מ-sw-toolbox

מפתחים שהשתמשו בעבר ב-sw-precache ו/או ב-sw-toolbox יכולים לשדרג בקלות לספריות של משפחת Workbox. שדרוג ל-Workbox יעניק חוויית קובץ שירות (service worker) מודרנית וניתנת להרחבה, עם ניפוי באגים משופר וארכיטקטורת מפתחים משופרת.

שינויים בהגדרות הקיימות

אם משתמשים ב-sw-precache שהוגדרו באחת מהאפשרויות הבאות, צריך לקחת בחשבון את השינויים הבאים במהלך ההעברה אל Workbox.

אפשרויות ששינו את השם

שם הפרמטר dynamicUrlToDependencies השתנה ל-templatedURLs.

שם הפרמטר staticFileGlobs השתנה ל-globPatterns.

הפרמטר config‏ runtimeCaching מקבל קבוצה מעודכנת של אפשרויות, בהתאם לשמות שבהם נעשה שימוש במודולים הבסיסיים של Workbox. כדי להמחיש מה השם ששונה, זו ההגדרה של sw-precache:

runtimeCaching: [{
  urlPattern: /api/,
  handler: 'fastest',
  options: {
    cache: {
      name: 'my-api-cache',
      maxEntries: 5,
      maxAgeSeconds: 60,
    },
  },
}],

מקביל לתצורה הבאה של 'תיבת עבודה':

runtimeCaching: [{
  urlPattern: /api/,
  // 'fastest' is now 'StaleWhileRevalidate'
  handler: 'StaleWhileRevalidate',
  options: {
    // options.cache.name is now options.cacheName
    cacheName: 'my-api-cache',
    // options.cache is now options.expiration
    expiration: {
      maxEntries: 5,
      maxAgeSeconds: 60,
    },
  },
}],

אפשרויות שהוצאו משימוש

אין יותר תמיכה במסלולים עם תווים כלליים לחיפוש בסגנון אקספרס. אם השתמשת בנתיבים כלליים לחיפוש בסגנון Express בתצורה runtimeCaching או ישירות ב-sw-toolbox, עליך לעבור למסלול מקביל של ביטויים רגולריים במהלך השימוש ב-Workbox.

מיגרציות של sw-precache

מ-CLI של sw-precache ל-workbox-cli

מפתחים שמשתמשים בממשק שורת הפקודה sw-precache, בין אם מריצים את הפקודה באופן ידני או כחלק מתהליך build מבוסס npm scripts, ימצאו את הדרך הקלה ביותר לבצע את ההעברה באמצעות המודול workbox-cli. התקנת workbox-cli תעניק לכם גישה לקובץ בינארי בשם workbox.

אמנם ה-CLI של sw-precache נתמך בהגדרה באמצעות דגלי שורת פקודה או קובץ תצורה, אבל ה-CLI של workbox מחייב לספק את כל אפשרויות התצורה בקובץ תצורה, באמצעות CommonJS module.exports.

ב-CLI של workbox יש תמיכה בכמה מצבים שונים. (אפשר להקיש על workbox --help כדי לראות את כולן). עם זאת, המצב שהכי קרוב לפונקציונליות של sw-precache הוא generateSW. לכן, קריאה ל-

$ sw-precache --config='sw-precache-config.js'

אפשר לבטא כ-

$ workbox generateSW workbox-config.js

ממודול הצומת sw-precache למודול הצומת workbox-build

מפתחים שמשתמשים ב-node API ל-sw-precache, כחלק מתהליך עבודה של gulp/Grunt או רק בסקריפט build מותאם אישית של node, יכולים לעבור למערך node של workbox-build.

הפונקציה generateSW() של המודול workbox-build תואמת ביותר לפונקציה write() של המודול sw-precache. אחד ההבדלים העיקריים הוא ש-generateSW() תמיד מחזירה Promise, ואילו הפונקציה write() הישנה תומכת גם בקריאה חוזרת (callback) וגם בממשק מבוסס-Promise.

השימוש ב-gulp לאורך התקופה של

const swPrecache = require('sw-precache');
gulp.task('generate-service-worker', function () {
  return swPrecache.write('service-worker.js', {
    // Config options.
  });
});

אפשר לשנות ל-

const workboxBuild = require('workbox-build');
gulp.task('generate-service-worker', function () {
  return workboxBuild.generateSW({
    // Config options.
  });
});

מ-sw-precache-webpack-plugin אל הפלאגין webpack של Workbox

מפתחים שמשתמשים ב-sw-precache-webpack-plugin כחלק מתהליך ה-build של webpack יכולים לעבור למחלקה GenerateSW בתוך המודול workbox-webpack-plugin.

workbox-webpack-plugin משתלב ישירות בתהליך ה-build של webpack ו "יודע" על כל הנכסים שנוצרו על ידי הידור נתון. המשמעות היא שבתרחישים לדוגמה רבים, אפשר להסתמך על התנהגות ברירת המחדל של workbox-webpack-plugin בלי הגדרות נוספות, ולקבל שירות עבודה מקביל לזה ש-sw-precache-webpack-plugin מספק.

const SWPrecacheWebpackPlugin = require('sw-precache-webpack-plugin');
const webpackConfig = {
  // ...
  plugins: [
    new SWPrecacheWebpackPlugin({
      dontCacheBustUrlsMatching: /\.\w{8}\./,
      filename: 'service-worker.js',
    }),
  ],
};

אפשר לשנות ל-

const {GenerateSW} = require('workbox-webpack-plugin');
const webpackConfig = {
  // ...
  plugins: [
    new GenerateSW({
      // Config options, if needed.
    }),
  ],
};

sw-toolbox migrations

מעבר מ-sw-toolbox שנוצר באופן ידני ל-workbox-sw

אם השתמשתם ב-sw-toolbox ישירות (במקום להשתמש בו באופן משתמע באמצעות האפשרות runtimeCaching של sw-precache), תצטרכו לבצע כמה התאמות ידניות במהלך ההעברה ל-Workbox כדי לקבל את אותה התנהגות. כדי לקבל הקשר נוסף, כדאי לקרוא את המסמכים של המודולים workbox-routing ו-workbox-strategies.

ריכזנו כאן כמה קטעי קוד שיעזרו לכם במעבר. קוד הsw-toolbox הזה:

importScripts('path/to/sw-toolbox.js');

// Set up a route that matches HTTP 'GET' requests.
toolbox.router.get(
  // Match any URL that contains 'ytimg.com', regardless of
  // where in the URL that match occurs.
  /\.ytimg\.com\//,

  // Apply a cache-first strategy to anything that matches.
  toolbox.cacheFirst,

  {
    // Configure a custom cache name and expiration policy.
    cache: {
      name: 'youtube-thumbnails',
      maxEntries: 10,
      maxAgeSeconds: 30,
    },
  }
);

// Set a default network-first strategy to use when
// there is no explicit matching route:
toolbox.router.default = toolbox.networkFirst;

מקביל לקוד הבא:

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

workbox.routing.registerRoute(
  // Match any URL that contains 'ytimg.com'.
  // Unlike in sw-toolbox, in Workbox, a RegExp that matches
  // a cross-origin URL needs to include the initial 'https://'
  // as part of the match.
  new RegExp('^https://.*.ytimg.com'),

  // Apply a cache-first strategy to anything that matches.
  new workbox.strategies.CacheFirst({
    // Configuration options are passed in to the strategy.
    cacheName: 'youtube-thumbnails',
    plugins: [
      new workbox.expiration.ExpirationPlugin({
        maxEntries: 10,
        maxAgeSeconds: 30,
      }),
      // In Workbox, you must explicitly opt-in to caching
      // responses with a status of 0 when using the
      // cache-first strategy.
      new workbox.cacheableResponse.CacheableResponsePlugin({
        statuses: [0, 200],
      }),
    ],
  })
);

// Set a default network-first strategy to use when
// there is no explicit matching route:
workbox.routing.setDefaultHandler(new workbox.strategies.NetworkFirst());

קבלת עזרה

אנחנו מצפים שרוב ההעברות אל Workbox יהיו פשוטות. אם נתקלת בבעיות שלא מפורטות במדריך הזה, אפשר לפתוח פנייה בנושא ב-GitHub.