Workbox-webpack-plugin

Workbox는 두 가지 webpack 플러그인을 제공합니다. 하나는 완전한 서비스 워커를 생성하는 것이며 다른 하나는 서비스 워커 파일에 삽입되는 사전 캐시할 애셋 목록을 생성하는 것입니다.

플러그인은 workbox-webpack-plugin 모듈에서 GenerateSW 및 InjectManifest라는 두 개의 클래스로 구현됩니다. 다음 질문에 대한 답변은 사용할 올바른 플러그인과 구성을 선택하는 데 도움이 될 수 있습니다.

사용할 플러그인

GenerateSW

GenerateSW 플러그인은 서비스 워커 파일을 만들어 webpack 애셋 파이프라인에 추가합니다.

GenerateSW 사용 시점

  • 파일을 사전 캐시하려고 합니다.
  • 간단한 런타임 캐싱 요구사항이 있습니다.

GenerateSW를 사용하면 안 되는 경우

  • 다른 서비스 워커 기능 (예: 웹 푸시)을 사용하려고 합니다.
  • 추가 스크립트를 가져오거나 커스텀 캐싱 전략을 위한 로직을 추가하려고 합니다.

InjectManifest

InjectManifest 플러그인은 사전 캐시 매니페스트를 사전 캐시하고 기존 서비스 워커 파일에 추가할 URL 목록을 생성합니다. 그렇지 않으면 파일이 그대로 유지됩니다.

InjectManifest 사용 시점

  • 서비스 워커를 더 세부적으로 제어하려는 경우.
  • 파일을 사전 캐시하려고 합니다.
  • 라우팅 및 전략을 맞춤설정해야 합니다.
  • 서비스 워커를 다른 플랫폼 기능 (예: 웹 푸시)과 함께 사용하려고 합니다.

InjectManifest를 사용하면 안 되는 경우

  • 사이트에 서비스 워커를 추가하는 가장 쉬운 방법이 좋습니다.

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

그러면 구성에서 선택한 모든 웹팩 애셋과 제공된 런타임 캐싱 규칙에 대한 사전 캐싱이 설정된 서비스 워커가 생성됩니다.

전체 구성 옵션은 참조 문서에서 확인할 수 있습니다.

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: '...',
    }),
  ],
};

그러면 구성에서 선택한 웹팩 애셋을 기반으로 사전 캐시 매니페스트가 생성되어 번들되고 컴파일된 서비스 워커 파일에 주입됩니다.

전체 구성 옵션은 참조 문서에서 확인할 수 있습니다.

추가 정보

더 큰 웹팩 빌드의 컨텍스트 내에서 플러그인 사용에 관한 안내는 웹팩 문서의 '프로그레시브 웹 애플리케이션' 섹션을 참고하세요.

유형

GenerateSW

이 클래스는 웹팩 컴파일 프로세스의 일부로 즉시 사용 가능한 새로운 서비스 워커 파일을 만드는 것을 지원합니다.

webpack 구성의 plugins 배열에서 GenerateSW 인스턴스를 사용합니다.

// 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)[] 선택사항

    빌드 구성의 일부로 생성된 항목 외에 사전 캐시될 항목 목록입니다.

  • babelPresetEnvTargets

    string[] 선택사항

    기본값은 ["chrome >= 56"]입니다.

    서비스 워커 번들을 트랜스파일할 때 babel-preset-env에 전달할 대상

  • cacheId

    문자열 선택사항

    캐시 이름 앞에 추가되는 선택적 ID입니다. 이는 주로 여러 사이트가 동일한 http://localhost:port 출처에서 제공될 수 있는 로컬 개발에 유용합니다.

  • 청크

    string[] 선택사항

    해당 출력 파일이 사전 캐시 매니페스트에 포함되어야 하는 하나 이상의 청크 이름입니다.

  • cleanupOutdatedCaches

    부울 선택사항

    기본값은 false입니다.

    Workbox가 호환되지 않는 이전 버전에서 생성된 사전 캐시를 식별하고 삭제하려고 시도할지 여부를 나타냅니다.

  • clientsClaim

    부울 선택사항

    기본값은 false입니다.

    서비스 워커가 활성화되는 즉시 기존 클라이언트를 제어하기 시작해야 하는지 여부입니다.

  • directoryIndex

    문자열 선택사항

    /로 끝나는 URL의 탐색 요청이 사전 캐시된 URL과 일치하지 않으면 이 값이 URL에 추가되고 사전 캐시 일치 여부를 확인합니다. 이 이름은 웹 서버가 디렉터리 색인에 사용 중인 이름으로 설정해야 합니다.

  • disableDevLogs

    부울 선택사항

    기본값은 false입니다.

  • dontCacheBustURLsMatching

    RegExp 선택사항

    이 애셋과 일치하는 애셋은 URL을 통해 고유하게 버전이 지정된 것으로 간주되며, 사전 캐시를 채울 때 수행되는 일반 HTTP 캐시 무효화에서 제외됩니다. 필수는 아니지만 기존 빌드 프로세스에서 이미 [hash] 값을 각 파일 이름에 삽입한 경우 이를 감지하는 RegExp를 제공하여 사전 캐싱할 때 소비되는 대역폭을 줄이는 것이 좋습니다.

  • 제외

    (string|RegExp|function)[] optional

    사전 캐시 매니페스트에서 애셋을 제외하는 데 사용되는 하나 이상의 지정자입니다. 이는 webpack의 표준 exclude 옵션과 동일한 규칙에 따라 해석됩니다. 제공하지 않은 경우 기본값은 [/\.map$/, /^manifest.*\.js$]입니다.

  • excludeChunks

    string[] 선택사항

    해당 출력 파일을 사전 캐시 매니페스트에서 제외해야 하는 하나 이상의 청크 이름입니다.

  • ignoreURLParametersMatching

    RegExp[] 선택사항

    이 배열의 RegExp 중 하나와 일치하는 모든 검색 매개변수 이름은 사전 캐시 일치를 찾기 전에 삭제됩니다. 이 기능은 사용자가 트래픽 소스를 추적하는 데 사용되는 URL 매개변수 등을 포함하는 URL을 요청할 수 있는 경우에 유용합니다. 제공하지 않은 경우 기본값은 [/^utm_/, /^fbclid$/]입니다.

  • importScripts

    string[] 선택사항

    생성된 서비스 워커 파일 내의 importScripts()에 전달해야 하는 JavaScript 파일 목록입니다. 이는 Workbox에서 최상위 서비스 워커 파일을 만들도록 하면서 푸시 이벤트 리스너와 같은 추가 코드를 포함하고자 할 때 유용합니다.

  • importScriptsViaChunks

    string[] 선택사항

    하나 이상의 웹팩 청크 이름입니다. 이러한 청크의 콘텐츠는 importScripts() 호출을 통해 생성된 서비스 워커에 포함됩니다.

  • include

    (string|RegExp|function)[] optional

    사전 캐시 매니페스트에 애셋을 포함하는 데 사용되는 하나 이상의 지정자입니다. 이는 webpack의 표준 include 옵션과 동일한 규칙에 따라 해석됩니다.

  • inlineWorkboxRuntime

    부울 선택사항

    기본값은 false입니다.

    Workbox 라이브러리의 런타임 코드를 최상위 서비스 워커에 포함해야 하는지, 아니면 서비스 워커와 함께 배포해야 하는 별도의 파일로 분할해야 하는지 여부입니다. 런타임을 별도로 유지하면 최상위 서비스 워커가 변경될 때마다 사용자가 Workbox 코드를 다시 다운로드할 필요가 없습니다.

  • manifestEntries

    ManifestEntry[] 선택사항

  • manifestTransforms

    ManifestTransform[] 선택사항

    생성된 매니페스트에 순차적으로 적용될 하나 이상의 함수. modifyURLPrefix 또는 dontCacheBustURLsMatching도 지정하면 해당 변환이 먼저 적용됩니다.

  • maximumFileSizeToCacheInBytes

    number 선택사항

    기본값은 2097152입니다.

    이 값은 사전 캐시될 파일의 최대 크기를 결정하는 데 사용할 수 있습니다. 이렇게 하면 패턴 중 하나와 일치시킬 수 있는 매우 큰 파일을 실수로 미리 캐시하는 것을 방지할 수 있습니다.

  • 모드

    문자열 선택사항

    'production'으로 설정하면 디버깅 정보를 제외하는 최적화된 서비스 워커 번들이 생성됩니다. 여기에서 명시적으로 구성하지 않은 경우 현재 webpack 컴파일에 구성된 mode 값이 사용됩니다.

  • modifyURLPrefix

    객체 선택사항

    대체 문자열 값에 문자열 접두사를 매핑하는 개체입니다. 예를 들어 웹 호스팅 설정이 로컬 파일 시스템 설정과 일치하지 않는 경우 매니페스트 항목에서 경로 접두어를 삭제하거나 추가하는 데 사용할 수 있습니다. 유연성을 더한 대안으로 manifestTransforms 옵션을 사용할 수 있으며, 제공된 로직을 사용하여 매니페스트의 항목을 수정하는 함수를 제공할 수 있습니다.

    사용 예:

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

    문자열 선택사항

    기본값은 null입니다.

    지정하면 사전 캐시되지 않은 URL에 대한 모든 탐색 요청이 제공된 URL의 HTML로 처리됩니다. 사전 캐시 매니페스트에 나열된 HTML 문서의 URL을 전달해야 합니다. 이 방법은 모든 탐색에서 일반적인 앱 셸 HTML을 사용해야 하는 단일 페이지 앱 시나리오에서 사용하기 위한 것입니다.

  • navigateFallbackAllowlist

    RegExp[] 선택사항

    구성된 navigateFallback 동작이 적용되는 URL을 제한하는 정규 표현식의 배열(선택사항)입니다. 이는 사이트 URL의 하위 집합만 단일 페이지 앱의 일부로 취급해야 하는 경우에 유용합니다. navigateFallbackDenylist와 navigateFallbackAllowlist가 모두 구성된 경우 차단 목록이 우선합니다.

    참고: 이러한 정규식은 탐색 중에 모든 도착 URL에 대해 평가될 수 있습니다. 복잡한 RegExps를 사용하지 마세요. 사용하지 않으면 사용자가 사이트를 탐색할 때 지연이 발생할 수 있습니다.

  • navigateFallbackDenylist

    RegExp[] 선택사항

    구성된 navigateFallback 동작이 적용되는 URL을 제한하는 정규 표현식의 배열(선택사항)입니다. 이는 사이트 URL의 하위 집합만 단일 페이지 앱의 일부로 취급해야 하는 경우에 유용합니다. navigateFallbackDenylist와 navigateFallbackAllowlist가 모두 구성된 경우 차단 목록이 우선 적용됩니다.

    참고: 이러한 정규식은 탐색 중에 모든 도착 URL에 대해 평가될 수 있습니다. 복잡한 RegExps를 사용하지 마세요. 사용하지 않으면 사용자가 사이트를 탐색할 때 지연이 발생할 수 있습니다.

  • navigationPreload

    부울 선택사항

    기본값은 false입니다.

    생성된 서비스 워커에서 탐색 미리 로드를 사용 설정할지 여부입니다. true로 설정하면 runtimeCaching를 사용하여 탐색 요청과 일치하는 적절한 응답 전략을 설정하고 미리 로드된 응답을 활용해야 합니다.

  • offlineGoogleAnalytics

    boolean|GoogleAnalyticsInitializeOptions optional

    기본값은 false입니다.

    오프라인 Google 애널리틱스에 대한 지원을 포함할지 여부를 제어합니다. true이면 workbox-google-analytics의 initialize() 호출이 생성된 서비스 워커에 추가됩니다. Object로 설정하면 객체가 initialize() 호출에 전달되므로 동작을 맞춤설정할 수 있습니다.

  • runtimeCaching

    RuntimeCaching[] 선택사항

    Workbox의 빌드 도구를 사용하여 서비스 워커를 생성할 때 런타임 캐싱 구성을 하나 이상 지정할 수 있습니다. 그런 다음 정의된 일치 및 핸들러 구성을 사용하여 workbox-routing.registerRoute 호출로 변환됩니다.

    모든 옵션은 workbox-build.RuntimeCaching 문서를 참고하세요. 아래 예는 두 개의 런타임 경로가 정의된 일반적인 구성을 보여줍니다.

  • skipWaiting

    부울 선택사항

    기본값은 false입니다.

    생성된 서비스 워커에 비조건부 skipWaiting() 호출을 추가할지 여부. false인 경우 message 리스너가 대신 추가되어 클라이언트 페이지가 대기 중인 서비스 워커에서 postMessage({type: 'SKIP_WAITING'})를 호출하여 skipWaiting()를 트리거할 수 있습니다.

  • 소스맵

    부울 선택사항

    기본값은 true입니다.

    생성된 서비스 워커 파일의 소스맵을 생성할지 여부입니다.

  • swDest

    문자열 선택사항

    기본값은 "service-worker.js"입니다.

    이 플러그인이 생성한 서비스 워커 파일의 애셋 이름입니다.

InjectManifest

이 클래스는 swSrc를 통해 제공되는 서비스 워커 파일을 컴파일하고 웹팩 애셋 파이프라인을 기반으로 사전 캐싱을 수행하기 위한 URL 목록과 버전 정보를 해당 서비스 워커에 삽입할 수 있도록 지원합니다.

webpack 구성의 plugins 배열에서 InjectManifest 인스턴스를 사용합니다.

매니페스트를 삽입하는 것 외에도 이 플러그인은 기본 webpack 구성의 옵션을 사용하여 swSrc 파일의 컴파일을 실행합니다.

// 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

    query

  • InjectManifest

    query