이 가이드에서는 Workbox v6에 도입된 브레이킹 체인지와 Workbox v5에서 업그레이드할 때 변경해야 하는 사항에 대한 예를 중점적으로 설명합니다.
이전 버전과 호환되지 않는 변경사항
워크박스 코어
workbox-core
의 skipWaiting()
메서드는 더 이상 install
핸들러를 추가하지 않으며 self.skipWaiting()
를 호출하는 것과 동일합니다.
이제 Workbox v7에서 skipWaiting()
가 삭제될 수 있으므로 이제부터는 self.skipWaiting()
를 대신 사용하세요.
작업 상자 사전 캐싱
- HTTP 리디렉션에 해당하는 URL에 대한 교차 출처 HTML 문서를 더 이상
workbox-precaching
로 탐색 요청을 충족하는 데 사용할 수 없습니다. 이 시나리오는 일반적으로 드물게 사용됩니다. - 이제 특정 요청에 관해 사전 캐시된 응답을 조회할 때
workbox-precaching
에서fbclid
URL 쿼리 매개변수를 무시합니다. - 이제
PrecacheController
생성자는 문자열이 아닌 특정 속성이 매개변수로 있는 객체를 가져옵니다. 이 객체는cacheName
(v5에서 생성자에 전달된 문자열과 동일한 용도로 사용),plugins
(v5의addPlugins()
메서드 대체),fallbackToNetwork
(v5에서createHandler()
및 `createHandlerBoundToURL()에 전달된 유사한 옵션 대체) 등의 속성을 지원합니다. - 이제
PrecacheController
의install()
및activate()
메서드는 정확히 하나의 매개변수를 사용하며 각각 상응하는InstallEvent
또는ActivateEvent
로 설정해야 합니다. addRoute()
메서드가PrecacheController
에서 삭제되었습니다. 대신 새PrecacheRoute
클래스를 사용하여 등록할 수 있는 경로를 만들 수 있습니다.precacheAndRoute()
메서드가PrecacheController
에서 삭제되었습니다. 이 메서드는workbox-precaching
모듈에서 내보낸 정적 도우미 메서드로 여전히 존재합니다. 대신PrecacheRoute
을(를) 사용할 수 있으므로 삭제되었습니다.createMatchCalback()
메서드가PrecacheController
에서 삭제되었습니다. 대신 새PrecacheRoute
를 사용할 수 있습니다.createHandler()
메서드가PrecacheController
에서 삭제되었습니다. 대신PrecacheController
객체의strategy
속성을 사용하여 요청을 처리할 수 있습니다.createHandler()
정적 내보내기가workbox-precaching
모듈에서 이미 삭제되었습니다. 대신 개발자는PrecacheController
인스턴스를 구성하고strategy
속성을 사용해야 합니다.precacheAndRoute()
에 등록된 경로는 이제 내부적으로workbox-routing
의Router
클래스를 사용하는 '실제' 경로입니다. 이로 인해registerRoute()
및precacheAndRoute()
호출을 인터리브 처리하면 경로의 평가 순서가 달라질 수 있습니다.
워크박스 라우팅
이제 setDefaultHandler()
메서드는 적용되는 HTTP 메서드에 상응하는 두 번째 매개변수(선택사항)를 사용하며 기본값은 'GET'
입니다.
setDefaultHandler()
를 사용하고 모든 요청이GET
인 경우에는 변경할 필요가 없습니다.GET
(POST
,PUT
등)이 아닌 요청이 있는 경우setDefaultHandler()
는 더 이상 이러한 요청을 일치시키지 않습니다.
빌드 구성
workbox-build
및 workbox-cli
의 getManifest
및 injectManifest
모드의 mode
옵션은 지원되지 않아 삭제되었습니다. 이는 InjectManifest
플러그인에서 mode
를 지원하는 workbox-webpack-plugin
에는 적용되지 않습니다.
빌드 도구에 Node.js v10 이상 필요
v10 이전의 Node.js 버전은 workbox-webpack-plugin
, workbox-build
또는 workbox-cli
에서 더 이상 지원되지 않습니다. v8 이전 버전의 Node.js를 실행하는 경우 런타임을 지원되는 버전으로 업데이트하세요.
새로운 개선사항
작업 상자 전략
Workbox v6에서는 타사 개발자가 자신만의 Workbox 전략을 정의할 수 있는 새로운 방법을 도입했습니다. 이를 통해 서드 파티 개발자는 요구사항을 완전히 충족하는 방식으로 Workbox를 확장할 수 있습니다.
새 전략 기본 클래스
v6에서는 모든 Workbox 전략 클래스가 새로운 Strategy
기본 클래스를 확장해야 합니다. 기본으로 제공되는 모든 전략은 이를 지원하기 위해 다시 작성되었습니다.
Strategy
기본 클래스는 다음 두 가지 주요 작업을 담당합니다.
- 모든 전략 핸들러에 공통된 플러그인 수명 주기 콜백을 호출합니다 (예: 핸들러가 시작, 응답, 종료될 때).
- 전략에서 처리하는 각 개별 요청의 상태를 관리할 수 있는 '핸들러' 인스턴스를 만듭니다.
새 'handler' 클래스
이전에는 내부 모듈에서 fetchWrapper
및 cacheWrapper
를 호출했습니다. 이는 이름에서 알 수 있듯이 다양한 가져오기 및 캐시 API를 후크를 사용하여 수명 주기에 래핑합니다. 이는 현재 플러그인이 작동할 수 있도록 하는 메커니즘이지만 개발자에게 노출되지는 않습니다.
새 '핸들러' 클래스인 StrategyHandler
는 맞춤 전략이 fetch()
또는 cacheMatch()
를 호출하고 전략 인스턴스에 추가된 플러그인을 자동으로 호출할 수 있도록 이러한 메서드를 노출합니다.
또한 이 클래스를 사용하면 개발자가 자신의 전략에 맞는 맞춤형 수명 주기 콜백을 추가할 수 있으며, 기존 플러그인 인터페이스와 '단순하게 작동'합니다.
새 플러그인 수명 주기 상태
Workbox v5에서 플러그인은 스테이트리스(Stateless)입니다. 즉, /index.html
요청이 requestWillFetch
및 cachedResponseWillBeUsed
콜백을 모두 트리거하면 이 두 콜백은 서로 통신하거나 동일한 요청에 의해 트리거되었음을 알 수 없습니다.
v6에서는 모든 플러그인 콜백에도 새로운 state
객체가 전달됩니다. 이 상태 객체는 이 특정 플러그인 객체와 이 특정 전략 호출 (예: handle()
호출)에만 고유합니다. 이를 통해 개발자는 한 콜백이 동일한 플러그인의 다른 콜백이 수행한 작업에 따라 조건부로 작업을 수행할 수 있는 플러그인을 작성할 수 있습니다 (예: requestWillFetch
및 fetchDidSucceed
또는 fetchDidFail
실행 간의 시간 델타 계산).
새 플러그인 수명 주기 콜백
개발자가 플러그인 수명 주기 상태를 완전히 활용할 수 있도록 새로운 플러그인 수명 주기 콜백을 추가했습니다.
handlerWillStart
: 핸들러 로직 실행이 시작되기 전에 호출됩니다. 이 콜백은 초기 핸들러 상태 (예: 시작 시간 기록)를 설정하는 데 사용할 수 있습니다.handlerWillRespond
: 전략handle()
메서드가 응답을 반환하기 전에 호출됩니다. 이 콜백은 응답을 경로 핸들러 또는 다른 맞춤 로직으로 반환하기 전에 수정하는 데 사용할 수 있습니다.handlerDidRespond
: 전략의handle()
메서드가 응답을 반환한 후에 호출됩니다. 이 콜백은 예를 들어 다른 플러그인에 의해 변경된 후 등에 최종 응답 세부정보를 기록하는 데 사용할 수 있습니다.handlerDidComplete
: 이 전략의 호출에서 이벤트에 추가된 전체 기간 연장 프로미스가 완료된 후 호출됩니다. 이 콜백은 계산하기 위해 핸들러가 완료될 때까지 기다려야 하는 모든 데이터 (예: 캐시 적중 상태, 캐시 지연 시간, 네트워크 지연 시간)를 보고하는 데 사용할 수 있습니다.handlerDidError
: 핸들러가 모든 소스에서 유효한 응답을 제공할 수 없는 경우 호출됩니다. 이 콜백은 네트워크 오류의 대안으로 '대체' 콘텐츠를 제공하는 데 사용할 수 있습니다.
자체 맞춤 전략을 구현하는 개발자는 이러한 콜백을 직접 호출하는 것에 관해 걱정할 필요가 없습니다. 이 모든 작업은 새로운 Strategy
기본 클래스에 의해 처리됩니다.
핸들러의 더 정확한 TypeScript 유형
다양한 콜백 메서드의 TypeScript 정의가 정규화되었습니다. 이렇게 하면 TypeScript를 사용하고 자체 코드를 작성하여 핸들러를 구현하거나 호출하는 개발자에게 더 나은 환경이 제공됩니다.
작업 상자-창
새 messageSkipWaiting() 메서드
'대기 중' 서비스 워커에 활성화를 지시하는 프로세스를 간소화하기 위해 새 메서드 messageSkipWaiting()
가 workbox-window
모듈에 추가되었습니다. 이를 통해 다음과 같은 몇 가지 사항이 개선되었습니다.
- Workbox에서 생성한 서비스 워커가
skipWaiting()
를 트리거하기 위해 확인하는 사실상의 표준 메시지 본문인{type: 'SKIP_WAITING'}
를 사용하여postMessage()
를 호출합니다. workbox-window
가 등록된 서비스 워커와 동일한 서비스 워커가 아니더라도 이 메시지를 게시할 올바른 '대기 중' 서비스 워커를 선택합니다.
isExternal 속성으로 '외부' 이벤트 삭제
workbox-window
의 모든 "external" 이벤트가 isExternal
속성이 true
로 설정된 '일반' 이벤트 대신 삭제되었습니다. 이렇게 하면 구분에 관심이 있는 개발자는 이 속성을 계속 감지할 수 있고 알 필요가 없는 개발자는 속성을 무시할 수 있습니다.
'사용자에게 페이지 새로고침 제공' 레시피 클리너
위의 두 가지 변경사항 덕분에 '사용자에게 페이지 새로고침 제공' 레시피를 단순화할 수 있습니다.
MULTI_LINE_CODE_PLACEHOLDER_0
워크박스 라우팅
새로운 불리언 매개변수 sameOrigin
가 workbox-routing
에 사용되는 matchCallback
함수에 전달됩니다. 요청이 동일한 출처 URL에 대한 요청이면 true
로 설정되고 그렇지 않으면 false로 설정됩니다.
이렇게 하면 일반적인 상용구가 간소화됩니다.
MULTI_LINE_CODE_PLACEHOLDER_1
Workbox-expiration의 matchOptions
이제 workbox-expiration
에서 matchOptions
를 설정할 수 있으며 이는 CacheQueryOptions
로 기본 cache.delete()
호출에 전달됩니다. 대부분의 개발자는 이 작업을 수행할 필요가 없습니다.
작업 상자 사전 캐싱
워크박스 전략 사용
workbox-strategies
를 베이스로 사용하도록 workbox-precaching
를 다시 작성했습니다. 이로 인해 브레이킹 체인지가 발생하지 않아야 하며, 두 모듈이 네트워크와 캐시에 액세스하는 방식에 있어 장기적으로 더 나은 일관성으로 이어져야 합니다.
이제 사전 캐싱을 통해 항목을 일괄 처리하지 않고 하나씩 처리합니다.
사전 캐시 매니페스트의 항목을 한 번에 모두 요청하고 캐시하려고 시도하는 대신 (제한 방법을 알아내기 위해 브라우저에 맡기는) 한 번에 하나의 항목만 요청되고 캐시되도록 workbox-precaching
가 업데이트되었습니다.
이렇게 하면 사전 캐싱 중에 net::ERR_INSUFFICIENT_RESOURCES
오류가 발생할 가능성이 줄어들고 사전 캐싱과 웹 앱의 동시 요청 사이의 대역폭 경합도 줄어듭니다.
PrecacheFallbackPlugin을 사용하면 더 쉬운 오프라인 대체 가능
이제 workbox-precaching
에 v6에 추가된 새로운 handlerDidError
수명 주기 메서드를 구현하는 PrecacheFallbackPlugin
가 포함됩니다.
이렇게 하면 응답을 사용할 수 없을 때 사전 캐시된 URL을 특정 전략에 대한 '대체'로 쉽게 지정할 수 있습니다. 플러그인은 필요한 수정 매개변수를 포함하여 사전 캐시된 URL에 대한 올바른 캐시 키를 올바르게 구성합니다.
다음은 NetworkOnly
전략이 탐색 요청에 관한 응답(즉, 맞춤 오프라인 HTML 페이지 표시)을 생성할 수 없을 때 사전 캐시된 /offline.html
로 응답하는 데 사용하는 샘플입니다.
MULTI_LINE_CODE_PLACEHOLDER_2
런타임 캐싱의 precacheFallback
서비스 워커를 직접 작성하는 대신 generateSW
를 사용하여 서비스 워커를 만드는 경우 runtimeCaching
에 새로운 precacheFallback
구성 옵션을 사용하여 동일한 작업을 할 수 있습니다.
{
// ... other generateSW config options...
runtimeCaching: [{
urlPattern: ({request}) => request.mode === 'navigate',
handler: 'NetworkOnly',
options: {
precacheFallback: {
// This URL needs to be included in your precache manifest.
fallbackURL: '/offline.html',
},
},
}],
}
도움말 보기
대부분의 마이그레이션은 간단할 것으로 예상됩니다. 이 가이드에서 다루지 않은 문제가 발생하면 GitHub에서 문제를 열어 알려주세요.