Workbox has been built to be modular, allowing developers to select the
pieces they want to use without forcing them to download everything in a
single file.

There is however overlap between modules, for example, each module will like
need to interact with the console, throw meaningful errors and make use of
the network or cache. To avoid each module implementing the same logic,
`workbox-core` contains this common code which each module relies on.

This module does provide some functionality to developers, but beyond log
levels and caching, `workbox-core` offers internal logic to each module,
rather than the end developer.

## View and Change the Default Cache Names

Workbox defines it's caches via `cacheNames`:

```javascript
import {cacheNames} from 'workbox-core';

console.log(cacheNames.precache);
console.log(cacheNames.runtime);
console.log(cacheNames.googleAnalytics);
```

These cache names are constructed in the format of a prefix, a name and
suffix, where the name changes based on the use of the cache.

`<prefix>-<cache-id>-<suffix>`

You can change these default names by altering all or some of the values
passed to `setCacheNameDetails()`.

```javascript
import {cacheNames, setCacheNameDetails} from 'workbox-core';

setCacheNameDetails({
  prefix: 'my-app',
  suffix: 'v1',
  precache: 'install-time',
  runtime: 'run-time',
  googleAnalytics: 'ga',
});

// Will print 'my-app-install-time-v1'
console.log(cacheNames.precache);

// Will print 'my-app-run-time-v1'
console.log(cacheNames.runtime);

// Will print 'my-app-ga-v1'
console.log(cacheNames.googleAnalytics);
```

The main use case for the prefix and suffix is that if you use Workbox for
multiple projects and use the same localhost port for each project, setting a
custom prefix for each module will prevent the caches from conflicting
with each other.

## Clients Claim

Some developers want to be able to publish a new service worker and have it
control already-open web pages as soon as it activates, which will not
happen [by default](https://web.dev/service-worker-lifecycle#clientsclaim).

If you find yourself wanting this behavior, `workbox-core` provides a helper method:

```javascript
import {clientsClaim} from 'workbox-core';

// This clientsClaim() should be at the top level
// of your service worker, not inside of, e.g.,
// an event handler.
clientsClaim();
```

The `clientsClaim()` method in `workbox-core` automatically adds an `activate`
event listener to your service worker, and inside of it, calls
`self.clients.claim()`. Calling `self.clients.claim()` before the current service
worker activates will lead to a
[runtime exception](https://w3c.github.io/ServiceWorker/#dom-clients-claim),
and `workbox-core`'s wrapper helps ensure that you call it at the right time.

### The skipWaiting wrapper is deprecated

Previous to Workbox v6, developers were also encouraged to use the `skipWaiting()`
method from `workbox-core`. However, this method offered little value beyond what
developers would get if they called `self.skipWaiting()` explicitly.

Because the legacy `workbox-core` wrapper also registered an `install` event handler
in which `self.skipWaiting()` was called, the wrapper would not behave as expected
if it were called inside of another event handler, like `message`, after installation
had already completed.

For these reasons, `workbox-core`'s `skipWaiting()` is deprecated, and developers
should switch to calling `self.skipWaiting()` directly. Unlike with
`self.clients.claim()`, `self.skipWaiting()` will not throw an exception if called
at the "wrong" time, so there is no need to wrap it in an event handler.

> [!NOTE]
> **Note:** If your web app lazy-loads resources that are uniquely versioned with, e.g., hashes in their URLs, it's recommended that you avoid using skip waiting. Enabling it could [lead to
> failures](https://stackoverflow.com/questions/51715127) when lazily-loading URLs that were previously precached and were purged during an updated service worker's activation.

<br />

## Types

### CacheDidUpdateCallback()

```typescript
workbox-core.CacheDidUpdateCallback(
  param: CacheDidUpdateCallbackParam,
): Promise<void>
```

#### Parameters

- param [CacheDidUpdateCallbackParam](https://developer.chrome.com/docs/workbox/modules/workbox-core.md.txt#type-CacheDidUpdateCallbackParam)

#### Returns

- Promise\<void\>

### CacheDidUpdateCallbackParam

#### Properties

- cacheName string
- event ExtendableEvent
- newResponse Response
- oldResponse Response optional
- request Request
- state [MapLikeObject](https://developer.chrome.com/docs/workbox/modules/workbox-core.md.txt#type-MapLikeObject) optional

### CachedResponseWillBeUsedCallback()

```typescript
workbox-core.CachedResponseWillBeUsedCallback(
  param: CachedResponseWillBeUsedCallbackParam,
): Promise<void | Response>
```

#### Parameters

- param [CachedResponseWillBeUsedCallbackParam](https://developer.chrome.com/docs/workbox/modules/workbox-core.md.txt#type-CachedResponseWillBeUsedCallbackParam)

#### Returns

- Promise\<void \| Response\>

### CachedResponseWillBeUsedCallbackParam

#### Properties

- cacheName string
- cachedResponse Response optional
- event ExtendableEvent
- matchOptions CacheQueryOptions optional
- request Request
- state [MapLikeObject](https://developer.chrome.com/docs/workbox/modules/workbox-core.md.txt#type-MapLikeObject) optional

### CacheKeyWillBeUsedCallback()

```typescript
workbox-core.CacheKeyWillBeUsedCallback(
  param: CacheKeyWillBeUsedCallbackParam,
): Promise<string | Request>
```

#### Parameters

- param [CacheKeyWillBeUsedCallbackParam](https://developer.chrome.com/docs/workbox/modules/workbox-core.md.txt#type-CacheKeyWillBeUsedCallbackParam)

#### Returns

- Promise\<string \| Request\>

### CacheKeyWillBeUsedCallbackParam

#### Properties

- event ExtendableEvent
- mode string
- params any optional
- request Request
- state [MapLikeObject](https://developer.chrome.com/docs/workbox/modules/workbox-core.md.txt#type-MapLikeObject) optional

### CacheWillUpdateCallback()

```typescript
workbox-core.CacheWillUpdateCallback(
  param: CacheWillUpdateCallbackParam,
): Promise<void | Response>
```

#### Parameters

- param [CacheWillUpdateCallbackParam](https://developer.chrome.com/docs/workbox/modules/workbox-core.md.txt#type-CacheWillUpdateCallbackParam)

#### Returns

- Promise\<void \| Response\>

### CacheWillUpdateCallbackParam

#### Properties

- event ExtendableEvent
- request Request
- response Response
- state [MapLikeObject](https://developer.chrome.com/docs/workbox/modules/workbox-core.md.txt#type-MapLikeObject) optional

### FetchDidFailCallback()

```typescript
workbox-core.FetchDidFailCallback(
  param: FetchDidFailCallbackParam,
): Promise<void>
```

#### Parameters

- param [FetchDidFailCallbackParam](https://developer.chrome.com/docs/workbox/modules/workbox-core.md.txt#type-FetchDidFailCallbackParam)

#### Returns

- Promise\<void\>

### FetchDidFailCallbackParam

#### Properties

- error Error
- event ExtendableEvent
- originalRequest Request
- request Request
- state [MapLikeObject](https://developer.chrome.com/docs/workbox/modules/workbox-core.md.txt#type-MapLikeObject) optional

### FetchDidSucceedCallback()

```typescript
workbox-core.FetchDidSucceedCallback(
  param: FetchDidSucceedCallbackParam,
): Promise<Response>
```

#### Parameters

- param [FetchDidSucceedCallbackParam](https://developer.chrome.com/docs/workbox/modules/workbox-core.md.txt#type-FetchDidSucceedCallbackParam)

#### Returns

- Promise\<Response\>

### FetchDidSucceedCallbackParam

#### Properties

- event ExtendableEvent
- request Request
- response Response
- state [MapLikeObject](https://developer.chrome.com/docs/workbox/modules/workbox-core.md.txt#type-MapLikeObject) optional

### HandlerCallbackOptions

#### Enum

[RouteHandlerCallbackOptions](https://developer.chrome.com/docs/workbox/modules/workbox-core.md.txt#type-RouteHandlerCallbackOptions)
[ManualHandlerCallbackOptions](https://developer.chrome.com/docs/workbox/modules/workbox-core.md.txt#type-ManualHandlerCallbackOptions)

<br />

### HandlerDidCompleteCallback()

```typescript
workbox-core.HandlerDidCompleteCallback(
  param: HandlerDidCompleteCallbackParam,
): Promise<void>
```

#### Parameters

- param [HandlerDidCompleteCallbackParam](https://developer.chrome.com/docs/workbox/modules/workbox-core.md.txt#type-HandlerDidCompleteCallbackParam)

#### Returns

- Promise\<void\>

### HandlerDidCompleteCallbackParam

#### Properties

- error Error optional
- event ExtendableEvent
- request Request
- response Response optional
- state [MapLikeObject](https://developer.chrome.com/docs/workbox/modules/workbox-core.md.txt#type-MapLikeObject) optional

### HandlerDidErrorCallback()

```typescript
workbox-core.HandlerDidErrorCallback(
  param: HandlerDidErrorCallbackParam,
): Promise<Response>
```

#### Parameters

- param [HandlerDidErrorCallbackParam](https://developer.chrome.com/docs/workbox/modules/workbox-core.md.txt#type-HandlerDidErrorCallbackParam)

#### Returns

- Promise\<Response\>

### HandlerDidErrorCallbackParam

#### Properties

- error Error
- event ExtendableEvent
- request Request
- state [MapLikeObject](https://developer.chrome.com/docs/workbox/modules/workbox-core.md.txt#type-MapLikeObject) optional

### HandlerDidRespondCallback()

```typescript
workbox-core.HandlerDidRespondCallback(
  param: HandlerDidRespondCallbackParam,
): Promise<void>
```

#### Parameters

- param [HandlerDidRespondCallbackParam](https://developer.chrome.com/docs/workbox/modules/workbox-core.md.txt#type-HandlerDidRespondCallbackParam)

#### Returns

- Promise\<void\>

### HandlerDidRespondCallbackParam

#### Properties

- event ExtendableEvent
- request Request
- response Response optional
- state [MapLikeObject](https://developer.chrome.com/docs/workbox/modules/workbox-core.md.txt#type-MapLikeObject) optional

### HandlerWillRespondCallback()

```typescript
workbox-core.HandlerWillRespondCallback(
  param: HandlerWillRespondCallbackParam,
): Promise<Response>
```

#### Parameters

- param [HandlerWillRespondCallbackParam](https://developer.chrome.com/docs/workbox/modules/workbox-core.md.txt#type-HandlerWillRespondCallbackParam)

#### Returns

- Promise\<Response\>

### HandlerWillRespondCallbackParam

#### Properties

- event ExtendableEvent
- request Request
- response Response
- state [MapLikeObject](https://developer.chrome.com/docs/workbox/modules/workbox-core.md.txt#type-MapLikeObject) optional

### HandlerWillStartCallback()

```typescript
workbox-core.HandlerWillStartCallback(
  param: HandlerWillStartCallbackParam,
): Promise<void>
```

#### Parameters

- param [HandlerWillStartCallbackParam](https://developer.chrome.com/docs/workbox/modules/workbox-core.md.txt#type-HandlerWillStartCallbackParam)

#### Returns

- Promise\<void\>

### HandlerWillStartCallbackParam

#### Properties

- event ExtendableEvent
- request Request
- state [MapLikeObject](https://developer.chrome.com/docs/workbox/modules/workbox-core.md.txt#type-MapLikeObject) optional

### ManualHandlerCallback()

```typescript
workbox-core.ManualHandlerCallback(
  options: ManualHandlerCallbackOptions,
): Promise<Response>
```

The "handler" callback is invoked whenever a `Router` matches a URL/Request
to a `Route` via its `RouteMatchCallback`. This handler callback should
return a `Promise` that resolves with a `Response`.

If a non-empty array or object is returned by the `RouteMatchCallback` it
will be passed in as this handler's `options.params` argument.

#### Parameters

- options [ManualHandlerCallbackOptions](https://developer.chrome.com/docs/workbox/modules/workbox-core.md.txt#type-ManualHandlerCallbackOptions)

#### Returns

- Promise\<Response\>

### ManualHandlerCallbackOptions

Options passed to a `ManualHandlerCallback` function.

#### Properties

- event ExtendableEvent
- request string \| Request

### MapLikeObject

### PluginState

Using a plain `MapLikeObject` for now, but could extend/restrict this
in the future.

#### Type

[MapLikeObject](https://developer.chrome.com/docs/workbox/modules/workbox-core.md.txt#type-MapLikeObject)

### RequestWillFetchCallback()

```typescript
workbox-core.RequestWillFetchCallback(
  param: RequestWillFetchCallbackParam,
): Promise<Request>
```

#### Parameters

- param [RequestWillFetchCallbackParam](https://developer.chrome.com/docs/workbox/modules/workbox-core.md.txt#type-RequestWillFetchCallbackParam)

#### Returns

- Promise\<Request\>

### RequestWillFetchCallbackParam

#### Properties

- event ExtendableEvent
- request Request
- state [MapLikeObject](https://developer.chrome.com/docs/workbox/modules/workbox-core.md.txt#type-MapLikeObject) optional

### RouteHandler

Either a `RouteHandlerCallback` or a `RouteHandlerObject`.
Most APIs in `workbox-routing` that accept route handlers take either.

#### Enum

[RouteHandlerCallback](https://developer.chrome.com/docs/workbox/modules/workbox-core.md.txt#method-RouteHandlerCallback)
[RouteHandlerObject](https://developer.chrome.com/docs/workbox/modules/workbox-core.md.txt#type-RouteHandlerObject)

<br />

### RouteHandlerCallback()

```typescript
workbox-core.RouteHandlerCallback(
  options: RouteHandlerCallbackOptions,
): Promise<Response>
```

The "handler" callback is invoked whenever a `Router` matches a URL/Request
to a `Route` via its `RouteMatchCallback`. This handler callback should
return a `Promise` that resolves with a `Response`.

If a non-empty array or object is returned by the `RouteMatchCallback` it
will be passed in as this handler's `options.params` argument.

#### Parameters

- options [RouteHandlerCallbackOptions](https://developer.chrome.com/docs/workbox/modules/workbox-core.md.txt#type-RouteHandlerCallbackOptions)

#### Returns

- Promise\<Response\>

### RouteHandlerCallbackOptions

Options passed to a `RouteHandlerCallback` function.

#### Properties

- event ExtendableEvent
- params [MapLikeObject](https://developer.chrome.com/docs/workbox/modules/workbox-core.md.txt#type-MapLikeObject) \| string\[\] optional
- request Request
- url URL

### RouteHandlerObject

An object with a `handle` method of type `RouteHandlerCallback`.

A `Route` object can be created with either an `RouteHandlerCallback`
function or this `RouteHandler` object. The benefit of the `RouteHandler`
is it can be extended (as is done by the `workbox-strategies` package).

#### Properties

- handle [RouteHandlerCallback](https://developer.chrome.com/docs/workbox/modules/workbox-core.md.txt#method-RouteHandlerCallback)

### RouteMatchCallback()

```typescript
workbox-core.RouteMatchCallback(
  options: RouteMatchCallbackOptions,
): any
```

The "match" callback is used to determine if a `Route` should apply for a
particular URL and request. When matching occurs in response to a fetch
event from the client, the `event` object is also supplied. However, since
the match callback can be invoked outside of a fetch event, matching logic
should not assume the `event` object will always be available.
If the match callback returns a truthy value, the matching route's
`RouteHandlerCallback` will be invoked immediately. If the value returned
is a non-empty array or object, that value will be set on the handler's
`options.params` argument.

#### Parameters

- options [RouteMatchCallbackOptions](https://developer.chrome.com/docs/workbox/modules/workbox-core.md.txt#type-RouteMatchCallbackOptions)

#### Returns

- any

### RouteMatchCallbackOptions

Options passed to a `RouteMatchCallback` function.

#### Properties

- event ExtendableEvent
- request Request
- sameOrigin boolean
- url URL

### WorkboxPlugin

An object with optional lifecycle callback properties for the fetch and
cache operations.

#### Properties

- cacheDidUpdate [CacheDidUpdateCallback](https://developer.chrome.com/docs/workbox/modules/workbox-core.md.txt#method-CacheDidUpdateCallback) optional
- cacheKeyWillBeUsed [CacheKeyWillBeUsedCallback](https://developer.chrome.com/docs/workbox/modules/workbox-core.md.txt#method-CacheKeyWillBeUsedCallback) optional
- cacheWillUpdate [CacheWillUpdateCallback](https://developer.chrome.com/docs/workbox/modules/workbox-core.md.txt#method-CacheWillUpdateCallback) optional
- cachedResponseWillBeUsed [CachedResponseWillBeUsedCallback](https://developer.chrome.com/docs/workbox/modules/workbox-core.md.txt#method-CachedResponseWillBeUsedCallback) optional
- fetchDidFail [FetchDidFailCallback](https://developer.chrome.com/docs/workbox/modules/workbox-core.md.txt#method-FetchDidFailCallback) optional
- fetchDidSucceed [FetchDidSucceedCallback](https://developer.chrome.com/docs/workbox/modules/workbox-core.md.txt#method-FetchDidSucceedCallback) optional
- handlerDidComplete [HandlerDidCompleteCallback](https://developer.chrome.com/docs/workbox/modules/workbox-core.md.txt#method-HandlerDidCompleteCallback) optional
- handlerDidError [HandlerDidErrorCallback](https://developer.chrome.com/docs/workbox/modules/workbox-core.md.txt#method-HandlerDidErrorCallback) optional
- handlerDidRespond [HandlerDidRespondCallback](https://developer.chrome.com/docs/workbox/modules/workbox-core.md.txt#method-HandlerDidRespondCallback) optional
- handlerWillRespond [HandlerWillRespondCallback](https://developer.chrome.com/docs/workbox/modules/workbox-core.md.txt#method-HandlerWillRespondCallback) optional
- handlerWillStart [HandlerWillStartCallback](https://developer.chrome.com/docs/workbox/modules/workbox-core.md.txt#method-HandlerWillStartCallback) optional
- requestWillFetch [RequestWillFetchCallback](https://developer.chrome.com/docs/workbox/modules/workbox-core.md.txt#method-RequestWillFetchCallback) optional

### WorkboxPluginCallbackParam

#### Properties

- cacheDidUpdate [CacheDidUpdateCallbackParam](https://developer.chrome.com/docs/workbox/modules/workbox-core.md.txt#type-CacheDidUpdateCallbackParam)
- cacheKeyWillBeUsed [CacheKeyWillBeUsedCallbackParam](https://developer.chrome.com/docs/workbox/modules/workbox-core.md.txt#type-CacheKeyWillBeUsedCallbackParam)
- cacheWillUpdate [CacheWillUpdateCallbackParam](https://developer.chrome.com/docs/workbox/modules/workbox-core.md.txt#type-CacheWillUpdateCallbackParam)
- cachedResponseWillBeUsed [CachedResponseWillBeUsedCallbackParam](https://developer.chrome.com/docs/workbox/modules/workbox-core.md.txt#type-CachedResponseWillBeUsedCallbackParam)
- fetchDidFail [FetchDidFailCallbackParam](https://developer.chrome.com/docs/workbox/modules/workbox-core.md.txt#type-FetchDidFailCallbackParam)
- fetchDidSucceed [FetchDidSucceedCallbackParam](https://developer.chrome.com/docs/workbox/modules/workbox-core.md.txt#type-FetchDidSucceedCallbackParam)
- handlerDidComplete [HandlerDidCompleteCallbackParam](https://developer.chrome.com/docs/workbox/modules/workbox-core.md.txt#type-HandlerDidCompleteCallbackParam)
- handlerDidError [HandlerDidErrorCallbackParam](https://developer.chrome.com/docs/workbox/modules/workbox-core.md.txt#type-HandlerDidErrorCallbackParam)
- handlerDidRespond [HandlerDidRespondCallbackParam](https://developer.chrome.com/docs/workbox/modules/workbox-core.md.txt#type-HandlerDidRespondCallbackParam)
- handlerWillRespond [HandlerWillRespondCallbackParam](https://developer.chrome.com/docs/workbox/modules/workbox-core.md.txt#type-HandlerWillRespondCallbackParam)
- handlerWillStart [HandlerWillStartCallbackParam](https://developer.chrome.com/docs/workbox/modules/workbox-core.md.txt#type-HandlerWillStartCallbackParam)
- requestWillFetch [RequestWillFetchCallbackParam](https://developer.chrome.com/docs/workbox/modules/workbox-core.md.txt#type-RequestWillFetchCallbackParam)

## Properties

### cacheNames

Get the current cache names and prefix/suffix used by Workbox.

`cacheNames.precache` is used for precached assets,
`cacheNames.googleAnalytics` is used by `workbox-google-analytics` to
store `analytics.js`, and `cacheNames.runtime` is used for everything else.

`cacheNames.prefix` can be used to retrieve just the current prefix value.
`cacheNames.suffix` can be used to retrieve just the current suffix value.

#### Type

object

#### Properties

- googleAnalytics string
- precache string
- prefix string
- runtime string
- suffix string

## Methods

### clientsClaim()

```typescript
workbox-core.clientsClaim(): void
```

Claim any currently available clients once the service worker
becomes active. This is normally used in conjunction with `skipWaiting()`.

### copyResponse()

```typescript
workbox-core.copyResponse(
  response: Response,
  modifier?: function,
): Promise<Response>
```

Allows developers to copy a response and modify its `headers`, `status`,
or `statusText` values (the values settable via a
\[`ResponseInit`\]`https://developer.mozilla.org/en-US/docs/Web/API/Response/Response#Syntax`
object in the constructor).
To modify these values, pass a function as the second argument. That
function will be invoked with a single object with the response properties
`{headers, status, statusText}`. The return value of this function will
be used as the `ResponseInit` for the new `Response`. To change the values
either modify the passed parameter(s) and return it, or return a totally
new object.

This method is intentionally limited to same-origin responses, regardless of
whether CORS was used or not.

#### Parameters

- response Response
- modifier function optional


  The `modifier` parameter looks like:

  ```typescript
  (responseInit: ResponseInit) => ResponseInit
  ```

  <br />

  - responseInit ResponseInit
  - returnsResponseInit

#### Returns

- Promise\<Response\>

### registerQuotaErrorCallback()

```typescript
workbox-core.registerQuotaErrorCallback(
  callback: Function,
): void
```

Adds a function to the set of quotaErrorCallbacks that will be executed if
there's a quota error.

#### Parameters

- callback Function

### setCacheNameDetails()

```typescript
workbox-core.setCacheNameDetails(
  details: PartialCacheNameDetails,
): void
```

Modifies the default cache names used by the Workbox packages.
Cache names are generated as `<prefix>-<Cache Name>-<suffix>`.

#### Parameters

- details PartialCacheNameDetails

### skipWaiting()

```typescript
workbox-core.skipWaiting(): void
```

This method is deprecated, and will be removed in Workbox v7.

Calling self.skipWaiting() is equivalent, and should be used instead.

<br />