Skip to content

Commit 8f8d113

Browse files
SkyZeroZxthePunderWoman
authored andcommitted
docs: Add docs service worker to new options (angular#63436)
Add docs service worker to new options PR Close angular#63436
1 parent 7ccf368 commit 8f8d113

File tree

1 file changed

+153
-0
lines changed

1 file changed

+153
-0
lines changed

adev/src/content/ecosystem/service-workers/getting-started.md

Lines changed: 153 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -159,6 +159,159 @@ Now look at how the browser and service worker handle the updated application.
159159

160160
The service worker installed the updated version of your application _in the background_, and the next time the page is loaded or reloaded, the service worker switches to the latest version.
161161

162+
## Service worker configuration
163+
164+
Angular service workers support comprehensive configuration options through the `SwRegistrationOptions` interface, providing fine-grained control over registration behavior, caching, and script execution.
165+
166+
### Enabling and disabling service workers
167+
168+
The `enabled` option controls whether the service worker will be registered and related services will attempt to communicate with it.
169+
170+
<docs-code language="typescript">
171+
172+
import { ApplicationConfig, isDevMode } from '@angular/core';
173+
import { provideServiceWorker } from '@angular/service-worker';
174+
175+
export const appConfig: ApplicationConfig = {
176+
providers: [
177+
provideServiceWorker('ngsw-worker.js', {
178+
enabled: !isDevMode(), // Disable in development, enable in production
179+
}),
180+
],
181+
};
182+
183+
</docs-code>
184+
185+
186+
### Cache control with updateViaCache
187+
188+
The `updateViaCache` option controls how the browser consults the HTTP cache during service worker updates. This provides fine-grained control over when the browser fetches updated service worker scripts and imported modules.
189+
190+
<docs-code language="typescript">
191+
192+
export const appConfig: ApplicationConfig = {
193+
providers: [
194+
provideServiceWorker('ngsw-worker.js', {
195+
enabled: !isDevMode(),
196+
updateViaCache: 'imports',
197+
}),
198+
],
199+
};
200+
201+
</docs-code>
202+
203+
The `updateViaCache` option accepts the following values:
204+
205+
* **`'imports'`** - The HTTP cache is consulted for the service worker script's imported scripts, but not for the service worker script itself
206+
* **`'all'`** - The HTTP cache is consulted for both the service worker script and its imported scripts
207+
* **`'none'`** - The HTTP cache is not consulted for the service worker script or its imported scripts
208+
209+
### ES Module support with type option
210+
211+
The `type` option enables specifying the script type when registering service workers, providing support for ES module features in your service worker scripts.
212+
213+
<docs-code language="typescript">
214+
215+
export const appConfig: ApplicationConfig = {
216+
providers: [
217+
provideServiceWorker('ngsw-worker.js', {
218+
enabled: !isDevMode(),
219+
type: 'module', // Enable ES module features
220+
}),
221+
],
222+
};
223+
224+
</docs-code>
225+
226+
The `type` option accepts the following values:
227+
228+
* **`'classic'`** (default) - Traditional service worker script execution. ES module features such as `import` and `export` are NOT allowed in the script
229+
* **`'module'`** - Registers the script as an ES module. Allows use of `import`/`export` syntax and module features
230+
231+
### Registration scope control
232+
233+
The `scope` option defines the service worker's registration scope, determining what range of URLs it can control.
234+
235+
<docs-code language="typescript">
236+
237+
export const appConfig: ApplicationConfig = {
238+
providers: [
239+
provideServiceWorker('ngsw-worker.js', {
240+
enabled: !isDevMode(),
241+
scope: '/app/', // Service worker will only control URLs under /app/
242+
}),
243+
],
244+
};
245+
246+
</docs-code>
247+
248+
* Controls which URLs the service worker can intercept and manage
249+
* By default, the scope is the directory containing the service worker script
250+
* Used when calling `ServiceWorkerContainer.register()`
251+
252+
### Registration strategy configuration
253+
254+
The `registrationStrategy` option defines when the service worker will be registered with the browser, providing control over the timing of registration.
255+
256+
<docs-code language="typescript">
257+
258+
export const appConfig: ApplicationConfig = {
259+
providers: [
260+
provideServiceWorker('ngsw-worker.js', {
261+
enabled: !isDevMode(),
262+
registrationStrategy: 'registerWhenStable:30000',
263+
}),
264+
],
265+
};
266+
267+
</docs-code>
268+
269+
Available registration strategies:
270+
271+
* **`'registerWhenStable:timeout'`** (default: `'registerWhenStable:30000'`) - Register as soon as the application stabilizes (no pending micro-/macro-tasks) but no later than the specified timeout in milliseconds
272+
* **`'registerImmediately'`** - Register the service worker immediately
273+
* **`'registerWithDelay:timeout'`** - Register with a delay of the specified timeout in milliseconds
274+
275+
<docs-code language="typescript">
276+
277+
// Register immediately
278+
export const immediateConfig: ApplicationConfig = {
279+
providers: [
280+
provideServiceWorker('ngsw-worker.js', {
281+
enabled: !isDevMode(),
282+
registrationStrategy: 'registerImmediately',
283+
}),
284+
],
285+
};
286+
287+
// Register with a 5-second delay
288+
export const delayedConfig: ApplicationConfig = {
289+
providers: [
290+
provideServiceWorker('ngsw-worker.js', {
291+
enabled: !isDevMode(),
292+
registrationStrategy: 'registerWithDelay:5000',
293+
}),
294+
],
295+
};
296+
297+
</docs-code>
298+
299+
You can also provide an Observable factory function for custom registration timing:
300+
301+
<docs-code language="typescript">
302+
import { timer } from 'rxjs';
303+
304+
export const customConfig: ApplicationConfig = {
305+
providers: [
306+
provideServiceWorker('ngsw-worker.js', {
307+
enabled: !isDevMode(),
308+
registrationStrategy: () => timer(10_000), // Register after 10 seconds
309+
}),
310+
],
311+
};
312+
313+
</docs-code>
314+
162315
## More on Angular service workers
163316

164317
You might also be interested in the following:

0 commit comments

Comments
 (0)