Workbox-webpack-plugin

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

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

사용할 플러그인

GenerateSW

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

GenerateSW 사용 시점

  • 파일을 미리 캐시하려고 합니다.
  • 간단한 런타임 캐싱이 필요합니다.

GenerateSW를 사용하지 않는 경우

  • 다른 Service Worker 기능 (예: 웹 푸시)을 사용하려 합니다.
  • 스크립트를 추가로 가져오거나 맞춤 캐싱 전략에 로직을 추가하려고 합니다.

InjectManifest

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

InjectManifest 사용 시점

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

InjectManifest를 사용하지 않는 경우

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

GenerateSW 플러그인

다음과 같이 webpack 구성에 GenerateSW 플러그인을 추가할 수 있습니다.

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

이렇게 하면 구성에서 선택한 모든 webpack 애셋의 사전 캐싱 설정 및 제공된 런타임 캐싱 규칙이 포함된 서비스 워커가 생성됩니다.

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

InjectManifest 플러그인

다음과 같이 webpack 구성에 InjectManifest 플러그인을 추가할 수 있습니다.

// 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 빌드의 컨텍스트 내에서 플러그인을 사용하는 방법에 관한 안내는 webpack 문서의 '프로그레시브 웹 애플리케이션' 섹션을 참고하세요.

유형

GenerateSW

이 클래스는 webpack 컴파일 프로세스의 일부로 즉시 사용할 수 있는 새 서비스 워커 파일을 만드는 것을 지원합니다.

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

    (string | ManifestEntry)[] 선택사항

    빌드 구성의 일부로 생성된 항목 외에도 미리 캐시할 항목 목록입니다.

  • babelPresetEnvTargets

    string[] 선택사항

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

    서비스 워커 번들을 트랜스파일할 때 babel-preset-env에 전달할 타겟입니다.

  • cacheId

    문자열 선택사항

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

  • 덩어리

    string[] 선택사항

    사전 캐시 매니페스트에 포함되어야 하는 해당 출력 파일이 있는 청크 이름 1개 이상

  • cleanupOutdatedCaches

    불리언 선택사항

    기본값은 false입니다.

    호환되지 않는 이전 버전에서 생성된 미리 캐시를 Workbox에서 식별하고 삭제해야 하는지 여부입니다.

  • clientsClaim

    불리언 선택사항

    기본값은 false입니다.

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

  • directoryIndex

    문자열 선택사항

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

  • disableDevLogs

    불리언 선택사항

    기본값은 false입니다.

  • dontCacheBustURLsMatching

    정규식 선택사항

    이에 일치하는 애셋은 URL을 통해 고유하게 버전이 지정된 것으로 가정되며, 미리 캐시를 채울 때 실행되는 일반적인 HTTP 캐시 무효화는 적용되지 않습니다. 필수는 아니지만 기존 빌드 프로세스가 이미 각 파일 이름에 [hash] 값을 삽입하는 경우 이를 감지하는 RegExp를 제공하는 것이 좋습니다. 이렇게 하면 미리 캐시할 때 사용되는 대역폭이 줄어듭니다.

  • 제외

    (string | RegExp | function)[] 선택사항

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

  • excludeChunks

    string[] 선택사항

    해당 출력 파일을 미리 캐시 매니페스트에서 제외해야 하는 청크 이름 1개 이상

  • ignoreURLParametersMatching

    RegExp[] 선택사항

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

  • importScripts

    string[] 선택사항

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

  • importScriptsViaChunks

    string[] 선택사항

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

  • include

    (문자열 | 정규식 | 함수)[] 선택사항

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

  • inlineWorkboxRuntime

    불리언 선택사항

    기본값은 false입니다.

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

  • manifestEntries

    ManifestEntry[] 선택사항

  • manifestTransforms

    ManifestTransform[] 선택사항

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

  • maximumFileSizeToCacheInBytes

    번호 선택사항

    기본값은 2097152입니다.

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

  • 모드

    문자열(선택사항)

    '프로덕션'으로 설정하면 디버깅 정보를 제외한 최적화된 서비스 워커 번들이 생성됩니다. 여기에서 명시적으로 구성되지 않은 경우 현재 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에 대해 평가될 수 있습니다. 복잡한 정규식을 사용하지 마세요. 사용자가 사이트를 탐색할 때 지연이 발생할 수 있습니다.

  • navigateFallbackDenylist

    RegExp[] 선택사항

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

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

  • navigationPreload

    불리언 선택사항

    기본값은 false입니다.

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

  • offlineGoogleAnalytics

    불리언 | GoogleAnalyticsInitializeOptions 선택사항

    기본값은 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()를 트리거할 수 있습니다.

  • sourcemap

    불리언 선택사항

    기본값은 true입니다.

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

  • swDest

    문자열(선택사항)

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

    이 플러그인에서 만든 서비스 워커 파일의 애셋 이름입니다.

InjectManifest

이 클래스는 swSrc를 통해 제공되는 서비스 워커 파일을 컴파일하고, webpack 애셋 파이프라인을 기반으로 사전 캐싱을 위해 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

    검색어

  • InjectManifest

    검색어