מעבר מתיבת עבודה מגרסה 2 לגרסה 3

המדריך הזה מתמקד בשינויים שבוצעו ב-Workbox v3, ומוצגות בו דוגמאות לשינויים שצריך לבצע כשמשדרגים מהגדרה של Workbox v2.

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

רקע גרסה 3

מהדורת v3 של Workbox מייצגת ארגון מחדש משמעותי של ה-codebase הקיים. היעדים העיקריים הם:

• הקטן את גודל תיבת העבודה. כמות קוד זמן הריצה של Service Worker שמורידים ומתבצעת הופחתה. במקום לצרף את כולם לחבילה מונוליתית, המערכת תייבא בזמן הריצה רק את הקוד של התכונות הספציפיות שבהן אתם משתמשים.
• לתיבת העבודה יש CDN. אנחנו מספקים אירוח CDN שמבוסס על תמיכה מלאה ב-Google Cloud Storage כאפשרות הקנונית לגישה לספריות זמן ריצה של Workbox, כדי שיהיה קל יותר להתחיל לעבוד עם Workbox.
• ניפוי באגים ויומנים משופרים. חוויית ניפוי הבאגים והרישום ביומן השתפרה משמעותית. יומני ניפוי באגים מופעלים כברירת מחדל בכל פעם שנעשה שימוש ב-Workbox ממקור localhost, וכל הרישום ביומן והטענות נכונות נמחקים מגרסאות ה-build של הייצור.
• פלאגין משופר של Webpack. workbox-webpack-plugin משתלב בצורה הדוקה יותר עם תהליך ה-build של חבילת Webpack, וכך מאפשר תרחיש לדוגמה של אפס הגדרה כשרוצים לשמור מראש את כל הנכסים בצינור עיבוד הנתונים של ה-build.

כדי להשיג את המטרות האלה ולנקות היבטים מסוימים בממשק הקודם שנראו מוזר או הובילו לתבניות נגדיות, נדרשו שינויים חריגים בגרסה 3.

שינויי תוכנה שעלולים לגרום לכשלים

הגדרת התצורה

השינויים הבאים משפיעים על ההתנהגות של כל כלי ה-build שלנו (workbox-build, workbox-cli, workbox-webpack-plugin), שיש להם קבוצה משותפת של אפשרויות הגדרה.

• שם ה-handler של 'fastest' היה תקין בעבר וטופל ככינוי של 'staleWhileRevalidate' במהלך הגדרת runtimeCaching. האימות כבר לא תקף, ומפתחים צריכים לעבור להשתמש ישירות ב-'staleWhileRevalidate'.
• עודכנו כמה שמות של מאפייני runtimeCaching.options ונעשה בהם שימוש באימות פרמטרים נוסף, שיגרום ל-build להיכשל אם ייעשה שימוש בהגדרה לא חוקית. במסמכי התיעוד של runtimeCaching תוכלו למצוא רשימה של האפשרויות הנתמכות כרגע.

תיבת עבודה-רקע-סנכרון

• פרמטר ההגדרה maxRetentionTime מפורש עכשיו כמספר דקות, ולא כמספר אלפיות שנייה.
• עכשיו יש מחרוזת נדרשת שמייצגת את שם התור, וצריך להעביר אותה כפרמטר הראשון כשיוצרים את הפלאגין או את המחלקה העצמאית. (הוא הועבר בעבר כמאפיין של האפשרויות.) תוכלו להיעזר במסמכי התיעוד כדי למצוא את פלטפורמת ה-API המעודכנת.

workbox-broadcast-cache-update

• עכשיו יש מחרוזת נדרשת שמייצגת את שם הערוץ, וצריך להעביר אותה כפרמטר הראשון כשיוצרים את הפלאגין או את המחלקה העצמאית.

לדוגמה, בגרסה 2 תצטרכו לאתחל את המחלקה של הפלאגין באופן הבא:

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

השימוש המקביל בגרסה 3 הוא:

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

תוכלו להיעזר במסמכי התיעוד כדי למצוא את פלטפורמת ה-API המעודכנת.

פיתוח ארגז עבודה

• כברירת מחדל, התאמת דפוסים של glob תבוצע כעת עם האפשרויות follow: true (שיופיעו אחרי הקישורים) ו-strict: true (שהיא פחות סובלת משגיאות "חריגות"). אפשר להשבית את כל אחת מהן ולחזור להתנהגות הקודמת על ידי הגדרה של globFollow: false ו/או globStrict: false בהגדרות ה-build.
• כל הפונקציות בפונקציה 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}`));

• מפתחים שכתבו פונקציות ManifestTransform מותאמות אישית בגרסה 2 צריכים להחזיר את מערך המניפסט באובייקט (כלומר, במקום return manifestArray; יש להשתמש ב-return {manifest: manifestArray};).m פעולה זו מאפשרת לפלאגין לכלול מאפיין warnings אופציונלי, שאמור להיות מערך של מחרוזות המכילות פרטי אזהרה לא חמורים.

אם כותבים ManifestTransform בהתאמה אישית בגרסה 2, צריך לקודד באופן הבא:

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

הוא גרסה 3 שהיא שוות-ערך ל:

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(), וההבטחה הוחזרה עכשיו כוללת מידע נוסף לגבי כתובות ה-URL שנשמרו מראש.

קוד כמו בדוגמה הבאה בגרסה 2:

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

ניתנים לכתיבה מחדש בגרסה 3, באופן הבא:

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

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

• הפונקציה generateFileManifest() הוסרה. מומלץ למפתחים לקרוא ל-getManifest() במקום זאת, ולהשתמש בתגובה שלו כדי לכתוב נתונים בדיסק בפורמט המתאים.

תיבת עבודה-מטמון-expiration

• ממשק ה-API של הפלאגין נשאר ללא שינוי, וזהו המצב שרוב המפתחים ישתמשו בו בסופו של דבר. עם זאת, יש שינויים משמעותיים ב-API שמשפיעים על מפתחים שמשתמשים בו כמחלקה עצמאית. תוכלו להיעזר במסמכי התיעוד כדי למצוא את פלטפורמת ה-API המעודכנת.

workbox-cli

מפתחים יכולים להריץ את ה-CLI עם הדגל --help לקבלת כל הפרמטרים הנתמכים.

• התמיכה בכינוי workbox-cli עבור הסקריפט הבינארי הוסרה. מעכשיו אפשר לגשת לקובץ הבינארי רק בתור workbox.
• השמות של פקודות V2 generate:sw ו-inject:manifest השתנו ל-generateSW ו-injectManifest בגרסה 3.
• בגרסה 2, ההנחה היא שקובץ התצורה המוגדר כברירת מחדל (בשימוש כשלא צוין במפורש) workbox-cli-config.js בספרייה הנוכחית. בגרסה 3, המחיר הוא workbox-config.js.

יחד, המשמעות היא שבגרסה 2:

$ workbox inject:manifest

יפעיל את תהליך ה-build 'החדרת מניפסט' באמצעות הגדרה שנקראה מ-workbox-cli-config.js ובגרסה 3:

$ workbox injectManifest

תבצע את אותה פעולה, אבל תקרא את התצורה מ-workbox-config.js.

הכנה מראש של ארגז עבודה

• השיטה precache() ביצעה בעבר גם שינויים במטמון וגם הגדרת ניתוב כדי להציג רשומות שנשמרו במטמון. עכשיו precache() משנה רק את הרשומות במטמון, ונחשפה שיטה חדשה, addRoute(), לרישום נתיב להצגת התגובות האלה שנשמרו במטמון. מפתחים שרוצים את הפונקציונליות הקודמת של 'שניים באחד' יכולים לעבור להתקשר אל precacheAndRoute().
• כמה אפשרויות שבעבר הוגדרו באמצעות הבנאי WorkboxSW מועברות עכשיו כפרמטר options ב-workbox.precaching.precacheAndRoute([...], options). ברירות המחדל של האפשרויות האלה, כאשר הן לא מוגדרות, מפורטות במסמכי העזר.
• כברירת מחדל, תתבצע בדיקה אוטומטית של התאמה לכתובות URL ללא סיומת קובץ כלשהי מול רשומת מטמון שמכילה את התוסף .html. למשל, אם נשלחת בקשה אל /path/to/index (שלא נשמרה במטמון מראש) וקיימת רשומה שנשמרה מראש במטמון של /path/to/index.html, ייעשה שימוש ברשומה ששמורה מראש במטמון. מפתחים יכולים להשבית את ההתנהגות החדשה הזו על ידי הגדרת {cleanUrls: false} בעת העברת אפשרויות אל workbox.precaching.precacheAndRoute().
• workbox-broadcast-update לא תוגדר יותר באופן אוטומטי להודיע על עדכונים במטמון של נכסים שנשמרו מראש.

הקוד הבא בגרסה 2:

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

הוא גרסה 3 שהיא שוות-ערך ל:

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

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

ניתוב ארגזי עבודה

• מפתחים שהשתמשו בעבר ב-workbox-routing דרך מרחב השמות workbox.router.* של אובייקט WorkboxSW צריכים לעבור למרחב השמות החדש, workbox.routing.*.
• המסלולים מוערכים עכשיו לפי הסדר הראשון שבו הם זוכים. זה הסדר ההפוך להערכה של Route שנעשה בו שימוש בגרסה 2, שבה תינתן עדיפות לRoute שנרשם לאחרונה.
• המחלקה ExpressRoute והתמיכה בתווים כלליים לחיפוש "בסגנון Express" הוסרה. פעולה זו מקטינה באופן משמעותי את הגודל של workbox-routing. מחרוזות המשמשות כפרמטר הראשון לפרמטר workbox.routing.registerRoute() יטופלו כהתאמות מדויקות. התאמות של תווים כלליים לחיפוש או התאמות חלקיות צריכות להתבצע על ידי RegExp – שימוש בכל RegExp שתואם לחלק מכתובת ה-URL של הבקשה או לכולן יכול להפעיל נתיב.
• שיטת המסייע addFetchListener() של המחלקה Router הוסרה. המפתחים יכולים להוסיף handler משלהם ל-fetch באופן מפורש, או להשתמש בממשק שסופק על ידי workbox.routing, וכתוצאה מכך ליצור בשבילם handler של fetch באופן לא מפורש.
• השיטות registerRoutes() ו-unregisterRoutes() הוסרו. הגרסאות של השיטות האלה שפועלות דרך Route אחד לא השתנו. מפתחים שצריכים לרשום או לבטל את הרישום של מספר מסלולים בבת אחת צריכים לבצע סדרה של קריאות אל registerRoute() או אל unregisterRoute() במקום זאת.

הקוד הבא בגרסה 2:

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

הוא גרסה 3 שהיא שוות-ערך ל:

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

זה עלול להוביל לרשומות שפג תוקפן במטמון ברירת המחדל, וזה לא צפוי. ב-v3, נדרש שם של קובץ שמור:

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

• השם של שיטת מחזור החיים cacheWillMatch השתנה ל-cachedResponseWillBeUsed. שינוי זה לא אמור להיות גלוי למפתחים, אלא אם הם כתבו יישומי פלאגין משלהם שהגיבו לcacheWillMatch.
• התחביר לציון יישומי פלאגין במהלך הגדרת אסטרטגיה השתנה. כל פלאגין צריך להיות רשום במפורש במאפיין plugins של הגדרת האסטרטגיה.

הקוד הבא בגרסה 2:

const workboxSW = new self.WorkboxSW();

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

הוא גרסה 3 שהיא שוות-ערך ל:

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 constructor כבר לא נתמכת בגרסה 3. מפתחים שצריכים להשתמש בפונקציונליות דומה כדי לבדוק את קובץ השירות (service worker) ללא הפעלה של רכיבי handler של אחזור, יכולים להשתמש באפשרות עקיפה לרשת, שזמינה בכלים למפתחים ב-Chrome.

פלאגין לתיבת עבודה-Webpack

הפלאגין נכתב מחדש באופן משמעותי, ובמקרים רבים ניתן להשתמש בו במצב 'אפס תצורה'. תוכלו להיעזר במסמכי התיעוד כדי למצוא את פלטפורמת ה-API המעודכנת.

• ה-API חושף עכשיו שתי מחלקות, GenerateSW ו-InjectManifest. כתוצאה מכך, ההחלפה בין המצבים תהיה מפורשת, לעומת ההתנהגות ב-v2 שבה ההתנהגות השתנתה על סמך הנוכחות של swSrc.
• כברירת מחדל, הנכסים בצינור עיבוד הנתונים של הידור של חבילות האינטרנט יישמרו מראש במטמון, וכבר לא צריך להגדיר את globPatterns. הסיבה היחידה להמשיך להשתמש ב-globPatterns היא אם צריך לשמור מראש נכסים דיגיטליים שלא כלולים ב-build של חבילת האינטרנט. באופן כללי, כשעוברים לפלאגין v3, צריך להסיר את כל ההגדרות הקודמות שמבוססות על glob, ולהוסיף אותן מחדש רק אם יש צורך בכך.

קבלת עזרה

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