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

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

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

רקע גרסה 3

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

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

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

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

הגדרת build

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

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

workbox-background-sync

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

workbox-broadcast-cache-update

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

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

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

השימוש המקביל ב-v3 הוא:

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

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

workbox-build

• כברירת מחדל, המערכת תבצע התאמת תבניות של 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};).mThis מאפשר לפלאגין לכלול מאפיין 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({...});

ניתן לשכתב ב-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

• ה-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.

הכנה במטמון לתיבת העבודה

• ה-method precache() ביצעה בעבר גם את השינויים במטמון וגם הגדירה ניתוב להצגת רשומות שנשמרו במטמון. עכשיו, precache() רק משנה את רשומות המטמון, ושיטה חדשה, addRoute(), נחשפה לרישום נתיב להצגת התגובות שנשמרו במטמון. מפתחים שרוצים את הפונקציונליות הקודמת של שניים באחד יכולים לעבור לקריאה ל-precacheAndRoute().
• מספר אפשרויות שבעבר הוגדרו באמצעות ה-constructor של 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- מכלing)

• המודול 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})],
});

• השם של ה-method של מחזור החיים 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]}),
  ],
});

מידע נוסף זמין בקטע שימוש ביישומי פלאגין. מותאמת אישית.

תיבת עבודה

• מתחת למכסה המנוע, 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 כבר לא אפשרויות שמועברות ל-constructor של WorkboxSW. במקום זאת, הם הוחלפו ב-methods workbox.clientsClaim() ו-workbox.skipWaiting().
• האפשרות handleFetch שנתמכה בעבר ב-constructor של גרסה 2 לא נתמכת יותר ב-v3. מפתחים שצריכים פונקציונליות דומה כדי לבדוק את קובץ השירות (service worker) מבלי להפעיל רכיבי handler של אחזור יכולים להשתמש ב"מעקף לרשת" שזמינה ב'כלים למפתחים' ב-Chrome.

workbox-webpack-plugin

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

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

קבלת עזרה

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