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

בתיבת העבודה יש שני יישומי פלאגין מסוג webpack: אחד שיוצר בשבילכם קובץ שירות (service worker) וקובץ אחד שיוצר רשימת נכסים לשמירה מראש שמוחדרת לקובץ של Service Worker.

הפלאגינים מוטמעים בשתי כיתות במודול workbox-webpack-plugin, שנקראות GenerateSW ו-InjectManifest. התשובות לשאלות הבאות יכולות לעזור לכם לבחור את הפלאגין וההגדרות המתאימים לשימוש.

באיזה פלאגין להשתמש

GenerateSW

הפלאגין GenerateSW ייצור בשבילכם קובץ Service Worker ויוסיף אותו לצינור עיבוד הנתונים של נכסי Webpack.

מתי כדאי להשתמש ב-GenerateSW

  • אתם רוצים לשמור קבצים במטמון מראש.
  • יש לך צרכים פשוטים לשמירה במטמון של סביבת זמן הריצה.

מתי לא כדאי להשתמש ב-GenerateSW

  • אתם רוצים להשתמש בתכונות אחרות של Service Worker (למשל Web Push).
  • אתם רוצים לייבא סקריפטים נוספים או להוסיף לוגיקה נוספת לאסטרטגיות שמירת מטמון בהתאמה אישית.

InjectManifest

הפלאגין InjectManifest ייצור רשימה של כתובות URL לאחסון במטמון מראש, ויוסיף את המניפסט של האחסון במטמון מראש לקובץ קיים של שירות העבודה. אחרת, הקובץ יישאר כפי שהוא.

מתי כדאי להשתמש ב-InjectManifest

  • אתם רוצים יותר שליטה על Service Worker.
  • רוצים לשמור קבצים מראש במטמון.
  • צריך להתאים אישית את הניתוב והאסטרטגיות.
  • אתם רוצים להשתמש ב-service worker עם תכונות אחרות בפלטפורמה (למשל Web Push).

מתי לא להשתמש במאפיין InjectManifest

  • אתם רוצים להוסיף שירות ל-worker לאתר שלכם בדרך הקלה ביותר.

הפלאגין GenerateSW

אפשר להוסיף את הפלאגין GenerateSW להגדרות של webpack באופן הבא:

// Inside of webpack.config.js:
const {GenerateSW} = require('workbox-webpack-plugin');

module.exports = {
  // Other webpack config...
  plugins: [
    // Other plugins...
    new GenerateSW({
      // These are some common options, and not all are required.
      // Consult the docs for more info.
      exclude: [/.../, '...'],
      maximumFileSizeToCacheInBytes: ...,
      navigateFallback: '...',
      runtimeCaching: [{
        // Routing via a matchCallback function:
        urlPattern: ({request, url}) => ...,
        handler: '...',
        options: {
          cacheName: '...',
          expiration: {
            maxEntries: ...,
          },
        },
      }, {
        // Routing via a RegExp:
        urlPattern: new RegExp('...'),
        handler: '...',
        options: {
          cacheName: '...',
          plugins: [..., ...],
        },
      }],
      skipWaiting: ...,
    }),
  ],
};

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

קבוצה מלאה של אפשרויות הגדרה מפורטת במסמכי העזרה.

פלאגין InjectManifest

אפשר להוסיף את הפלאגין InjectManifest להגדרות של webpack באופן הבא:

// Inside of webpack.config.js:
const {InjectManifest} = require('workbox-webpack-plugin');

module.exports = {
  // Other webpack config...
  plugins: [
    // Other plugins...
    new InjectManifest({
      // These are some common options, and not all are required.
      // Consult the docs for more info.
      exclude: [/.../, '...'],
      maximumFileSizeToCacheInBytes: ...,
      swSrc: '...',
    }),
  ],
};

הפעולה הזו תיצור מניפסט מראש במטמון שמבוסס על נכסי ה-webpack שנאספו על ידי ההגדרה שלכם, ותכניס אותו לקובץ השירות (service worker) הכלול בחבילה.

קבוצה מלאה של אפשרויות הגדרה מפורטת במסמכי העזרה.

מידע נוסף

הנחיות לשימוש בפלאגינים בהקשר של build גדול יותר של webpack מפורטות בקטע Progressive Web Application במסמכי התיעוד של webpack.

סוגים

GenerateSW

הכיתה הזו תומכת ביצירת קובץ חדש של שירות עבודה מוכן לשימוש, כחלק מתהליך הידור ה-Webpack.

משתמשים במופע של GenerateSW במערך plugins של קובץ ההגדרות של webpack.

// The following lists some common options; see the rest of the documentation
// for the full set of options and defaults.
new GenerateSW({
  exclude: [/.../, '...'],
  maximumFileSizeToCacheInBytes: ...,
  navigateFallback: '...',
  runtimeCaching: [{
    // Routing via a matchCallback function:
    urlPattern: ({request, url}) => ...,
    handler: '...',
    options: {
      cacheName: '...',
      expiration: {
        maxEntries: ...,
      },
    },
  }, {
    // Routing via a RegExp:
    urlPattern: new RegExp('...'),
    handler: '...',
    options: {
      cacheName: '...',
      plugins: [..., ...],
    },
  }],
  skipWaiting: ...,
});

מאפיינים

GenerateSWConfig

מאפיינים

  • additionalManifestEntries

    (string | ManifestEntry)[] אופציונלי

    רשימה של רשומות שיאוחסנו במטמון מראש, בנוסף לכל רשומה שנוצרת כחלק מהגדרת ה-build.

  • babelPresetEnvTargets

    string[] אופציונלי

    ערך ברירת המחדל הוא: ["chrome >= 56"]

    היעדים שצריך להעביר ל-babel-preset-env במהלך המרת ה-bundle של ה-service worker.

  • cacheId

    מחרוזת אופציונלי

    מזהה אופציונלי שיצורף מראש לשמות המטמון. האפשרות הזו שימושית בעיקר לפיתוח מקומי, שבו יכול להיות שמוצגים כמה אתרים מאותו מקור http://localhost:port.

  • גושים

    string[] אופציונלי

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

  • cleanupOutdatedCaches

    בוליאני אופציונלי

    ערך ברירת המחדל הוא: false

    האם ל-Workbox יהיה ניסיון לזהות ולמחוק נתונים שנשמרו מראש על ידי גרסאות ישנות יותר שלא תואמות.

  • clientsClaim

    בוליאני אופציונלי

    ערך ברירת המחדל הוא: false

    אם להתחיל לשלוט בלקוחות קיימים ברגע שה-service worker מופעל.

  • directoryIndex

    מחרוזת אופציונלי

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

  • disableDevLogs

    בוליאני אופציונלי

    ערך ברירת המחדל הוא: false

  • dontCacheBustURLsMatching

    ביטוי רגולרי (RegExp) אופציונלי

    נכסים שתואמים לתנאי הזה ייחשבו כנכסים עם גרסה ייחודית באמצעות כתובת ה-URL שלהם, והם פטורים מהפעלת ה-HTTP רגילה לביטול מטמון שמתבצעת בזמן האכלוס של המטמון המוקדם. אומנם לא חובה, אבל מומלץ שאם בתהליך ה-build הקיים כבר יוסיף ערך [hash] לכל שם קובץ, תצטרכו לספק RegExp כדי לזהות זאת, כי הוא יצמצם את רוחב הפס שצורך במהלך השמירה למטמון.

  • אל תכלול

    (string | RegExp | function)[] אופציונלי

    מציין אחד או יותר שמשמשים להחרגת נכסים מהמניפסט של המטמון מראש. המשמעות של ההגדרה הזו היא לפי אותם הכללים שמוגדרים לאפשרות exclude הרגילה של webpack. אם לא מציינים אותו, ערך ברירת המחדל הוא [/\.map$/, /^manifest.*\.js$].

  • excludeChunks

    string[] אופציונלי

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

  • ignoreURLParametersMatching

    RegExp[] אופציונלי

    כל שמות הפרמטרים של החיפוש שתואמים לאחד מהביטויים הרגולריים (RegExp) במערך הזה יוסרו לפני חיפוש התאמה של נתונים שנשמרו במטמון מראש. האפשרות הזו שימושית אם המשתמשים שלכם עשויים לבקש כתובות URL שמכילות, למשל, פרמטרים של כתובות URL שמשמשים למעקב אחר מקור התנועה. אם לא מציינים אותו, ערך ברירת המחדל הוא [/^utm_/, /^fbclid$/].

  • importScripts

    string[] אופציונלי

    רשימה של קובצי JavaScript שצריך להעביר אל importScripts() בתוך קובץ ה-service worker שנוצר. האפשרות הזו שימושית אם רוצים לאפשר ל-Workbox ליצור את קובץ ה-service worker ברמה העליונה, אבל רוצים לכלול קוד נוסף, כמו מאזין לאירועי דחיפה.

  • importScriptsViaChunks

    string[] אופציונלי

    שם אחד או יותר של קטעי קוד ב-Webpack. התוכן של הקטעים האלה ייכלל ב-service worker שנוצר, באמצעות קריאה ל-importScripts().

  • כוללים

    (string | RegExp | function)[] אופציונלי

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

  • inlineWorkboxRuntime

    ערך בוליאני אופציונלי

    ערך ברירת המחדל הוא: false

    האם קוד זמן הריצה של ספריית Workbox צריך להיכלל ב-service worker ברמה העליונה, או לפצל אותו לקובץ נפרד שצריך לפרוס לצד ה-service worker. הפרדה של סביבת זמן הריצה מאפשרת למשתמשים לא להוריד מחדש את הקוד של Workbox בכל פעם שמשתנה ה-service worker ברמה העליונה.

  • manifestEntries

    ManifestEntry[] אופציונלי

  • manifestTransforms

    ManifestTransform[] אופציונלי

    פונקציה אחת או יותר שיחולו ברצף על המניפסט שנוצר. אם מציינים גם את modifyURLPrefix או את dontCacheBustURLsMatching, הטרנספורמציות התואמות שלהם יחולו קודם.

  • maximumFileSizeToCacheInBytes

    מספר אופציונלי

    ערך ברירת המחדל הוא: 2097152

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

  • מצב

    מחרוזת אופציונלי

    אם המדיניות מוגדרת כ-production, המערכת תיצור חבילת Service Worker שעברה אופטימיזציה ולא כוללת מידע על ניפוי באגים. אם לא תגדירו אותו כאן באופן מפורש, המערכת תשתמש בערך mode שהוגדר ב-webpack הנוכחי.

  • modifyURLPrefix

    אובייקט אופציונלי

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

    דוגמה לשימוש:

    // Replace a '/dist/' prefix with '/', and also prepend
// '/static' to every URL.
modifyURLPrefix: {
  '/dist/': '/',
  '': '/static',
}
  • navigateFallback

    מחרוזת אופציונלי

    ערך ברירת המחדל הוא: null

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

  • navigateFallbackAllowlist

    RegExp[] אופציונלי

    מערך אופציונלי של ביטויים רגולריים שמגביל את כתובות ה-URL שעליהן חלה ההתנהגות של navigateFallback שהוגדרה. האפשרות הזו שימושית אם רוצים להתייחס רק לקבוצת משנה של כתובות ה-URL באתר כחלק מאפליקציה של דף יחיד. אם מוגדרות גם navigateFallbackDenylist וגם navigateFallbackAllowlist, רשימת הדחייה מקבלת עדיפות.

    הערה: יכול להיות שה-RegExps האלה ייבדקו כנגד כל כתובת URL של יעד במהלך ניווט. מומלץ להימנע משימוש בביטויים רגולריים מורכבים, אחרת המשתמשים עשויים להבחין בעיכובים בזמן הניווט באתר.

  • navigateFallbackDenylist

    RegExp[] אופציונלי

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

    הערה: יכול להיות שה-RegExps האלה ייבדקו כנגד כל כתובת URL של יעד במהלך ניווט. לא מומלץ להשתמש ב-Complex RegExps, אחרת המשתמשים עשויים לראות עיכובים בזמן הניווט באתר.

  • navigationPreload

    ערך בוליאני אופציונלי

    ערך ברירת המחדל הוא: false

    האם להפעיל טעינה מראש של ניווט ב-service worker שנוצר. כשהערך מוגדר כ-true, צריך להשתמש גם ב-runtimeCaching כדי להגדיר אסטרטגיית תגובה מתאימה שתתאים לבקשות הניווט, ולהשתמש בתגובה שהוטענה מראש.

  • offlineGoogleAnalytics

    בוליאני | GoogleAnalyticsInitializeOptions אופציונלי

    ערך ברירת המחדל הוא: false

    ההגדרה קובעת אם לכלול תמיכה ב-Google Analytics אופליין. בתאריך true, הקריאה ל-initialize() של workbox-google-analytics תתווסף ל-Service Worker שנוצר. כשהאובייקט מוגדר ל-Object, האובייקט יועבר לקריאה initialize(), כך שתוכלו להתאים אישית את ההתנהגות.

  • runtimeCaching

    RuntimeCaching[] אופציונלי

    כשמשתמשים בכלי ה-build של Workbox כדי ליצור את קובץ השירות (service worker), אפשר לציין הגדרה אחת או יותר לשמירה במטמון של סביבת זמן הריצה. לאחר מכן הקריאות האלה מתורגמות לקריאות workbox-routing.registerRoute באמצעות הגדרות ההתאמה והטיפול (handler) שתגדירו.

    למידע על כל האפשרויות, עיינו במשאבי העזרה של workbox-build.RuntimeCaching. בדוגמה הבאה אפשר לראות הגדרה אופיינית, עם שני נתיבים של זמן ריצה:

  • skipWaiting

    ערך בוליאני אופציונלי

    ערך ברירת המחדל הוא: false

    האם להוסיף קריאה לא מותנית ל-skipWaiting() ל-Service Worker שנוצר. אם הערך הוא false, במקום זאת יתווסף מאזין message, שיאפשר לדפי לקוח להפעיל את skipWaiting() על ידי קריאה ל-postMessage({type: 'SKIP_WAITING'}) ב-service worker שממתין.

  • sourcemap

    בוליאני אופציונלי

    ערך ברירת המחדל הוא: true

    האם ליצור מפת מקור לקובצי ה-service worker שנוצרו.

  • swDest

    מחרוזת אופציונלי

    ערך ברירת המחדל הוא: "service-worker.js"

    שם הנכס של קובץ Service Worker שנוצר על ידי הפלאגין הזה.

InjectManifest

הכיתה הזו תומכת בהידור של קובץ Service Worker שסופק דרך swSrc, ובהחדרה ל-Service Worker רשימת כתובות URL ופרטי גרסאות לצורך שמירה מראש במטמון על סמך צינור עיבוד הנתונים של נכסי ה-webpack.

משתמשים במופע של InjectManifest במערך plugins של קובץ ההגדרה של webpack.

בנוסף להחדרת המניפסט, הפלאגין יבצע הידור של הקובץ swSrc באמצעות האפשרויות מהתצורה הראשית של webpack.

// The following lists some common options; see the rest of the documentation
// for the full set of options and defaults.
new InjectManifest({
  exclude: [/.../, '...'],
  maximumFileSizeToCacheInBytes: ...,
  swSrc: '...',
});

מאפיינים

מאפיינים

default

סוג

אובייקט

מאפיינים

  • GenerateSW

    שאילתה

  • InjectManifest

    שאילתה