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

ב-Workbox יש שני יישומי פלאגין של 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

  • אתם מעוניינים בדרך הקלה ביותר להוספת קובץ שירות (service 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: '...',
    }),
  ],
};

הפעולה הזו תיצור מניפסט של מטמון (pre-cache) על סמך נכסי ה-Webpack שנאספו בהגדרות שלכם ותכניס אותו לקובץ ה-Service Worker המצורף.

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

מידע נוסף

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

סוגים

GenerateSW

בכיתה הזו יש תמיכה ביצירת קובץ שירות (service worker) חדש ומוכן לשימוש כחלק מתהליך הידור של 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

    (מחרוזת | ManifestEntry)[] אופציונלי

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

  • babelPresetEnvTargets

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

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

    היעדים שצריך להעביר ל-babel-preset-env בעת העברת החבילה של קובץ השירות (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 | function)[] אופציונלי

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

  • excludeChunks

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

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

  • ignoreURLParametersMatching

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

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

  • importScripts

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

    רשימה של קובצי JavaScript שצריך להעביר אל importScripts() בקובץ ה-Service Worker שנוצר. זו אפשרות שימושית כשרוצים לאפשר ל-Workbox ליצור קובץ Service Worker ברמה העליונה, אבל רוצים לכלול קוד נוסף, כמו Push event listener.

  • importScriptsViaChunks

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

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

  • כוללים

    (מחרוזת | RegExp | function)[] אופציונלי

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

  • inlineWorkboxRuntime

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

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

    האם צריך לכלול את קוד זמן הריצה של ספריית Workbox ב-Service Worker ברמה העליונה, או לפצל אותו לקובץ נפרד שצריך לפרוס יחד עם ה-Service Worker. המשמעות של שמירת זמן ריצה נפרדת היא שהמשתמשים לא יצטרכו להוריד מחדש את קוד תיבת העבודה בכל פעם שה-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 שרשום במניפסט של המטמון מראש. ניתן להשתמש בו בתרחיש של אפליקציית דף יחיד, שבו רוצים שכל הניווטים ישתמשו ב-App Shell HTML נפוץ.

  • navigateFallbackAllowlist

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

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

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

  • navigateFallbackDenylist

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

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

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

  • navigationPreload

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

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

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

  • offlineGoogleAnalytics

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

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

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

  • runtimeCaching

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

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

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

  • skipWaiting

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

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

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

  • מפת מקור

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

    ערך ברירת המחדל הוא: 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: '...',
});

תכונות

  • Constructor

    void

    יוצר מופע של InjectManifest.

    הפונקציה constructor נראית כך:

    (config: WebpackInjectManifestOptions) => {...}

    • config

      WebpackInjectManifestOptions

  • config

    WebpackInjectManifestOptions

תכונות

default

סוג

אובייקט

תכונות

  • GenerateSW

    שאילתה

  • InjectManifest

    שאילתה