diff --git a/adev-es/src/app/routing/sub-navigation-data.ts b/adev-es/src/app/routing/sub-navigation-data.ts index 21d8477..d8ec6f6 100644 --- a/adev-es/src/app/routing/sub-navigation-data.ts +++ b/adev-es/src/app/routing/sub-navigation-data.ts @@ -1060,7 +1060,7 @@ const DOCS_SUB_NAVIGATION_DATA: NavigationItem[] = [ ], }, { - label: 'Extended Ecosystem', + label: 'Ecosistema Extendido', children: [ { label: 'NgModules', @@ -1121,42 +1121,42 @@ const DOCS_SUB_NAVIGATION_DATA: NavigationItem[] = [ label: 'Service Workers & PWAs', children: [ { - label: 'Overview', + label: 'Visión general', path: 'ecosystem/service-workers', contentPath: 'ecosystem/service-workers/overview', }, { - label: 'Getting started', + label: 'Empezando', path: 'ecosystem/service-workers/getting-started', contentPath: 'ecosystem/service-workers/getting-started', }, { - label: 'Custom service worker scripts', + label: 'Scripts de service worker personalizados', path: 'ecosystem/service-workers/custom-service-worker-scripts', contentPath: 'ecosystem/service-workers/custom-service-worker-scripts', }, { - label: 'Configuration file', + label: 'Archivo de configuración', path: 'ecosystem/service-workers/config', contentPath: 'ecosystem/service-workers/config', }, { - label: 'Communicating with the service worker', + label: 'Comunicación con el service worker', path: 'ecosystem/service-workers/communications', contentPath: 'ecosystem/service-workers/communications', }, { - label: 'Push notifications', + label: 'Notificaciones push', path: 'ecosystem/service-workers/push-notifications', contentPath: 'ecosystem/service-workers/push-notifications', }, { - label: 'Service worker devops', + label: 'Devops del service worker', path: 'ecosystem/service-workers/devops', contentPath: 'ecosystem/service-workers/devops', }, { - label: 'App shell pattern', + label: 'Patrón App shell', path: 'ecosystem/service-workers/app-shell', contentPath: 'ecosystem/service-workers/app-shell', }, diff --git a/adev-es/src/content/ecosystem/service-workers/app-shell.en.md b/adev-es/src/content/ecosystem/service-workers/app-shell.en.md new file mode 100644 index 0000000..31e86a0 --- /dev/null +++ b/adev-es/src/content/ecosystem/service-workers/app-shell.en.md @@ -0,0 +1,56 @@ +# App shell pattern + +The [App shell pattern](https://developer.chrome.com/blog/app-shell) is a way to render a portion of your application using a route at build time. +It can improve the user experience by quickly launching a static rendered page (a skeleton common to all pages) while the browser downloads the full client version and switches to it automatically after the code loads. + +This gives users a meaningful first paint of your application that appears quickly because the browser can render the HTML and CSS without the need to initialize any JavaScript. + + + +Do this with the following Angular CLI command: + +```shell +ng new my-app +``` + +For an existing application, you have to manually add the `Router` and defining a `` within your application. + + +Use the Angular CLI to automatically create the application shell. + +```shell +ng generate app-shell +``` + +For more information about this command, see [App shell command](cli/generate/app-shell). + +The command updates the application code and adds extra files to the project structure. + + +src +├── app +│ ├── app.config.server.ts # server application configuration +│ └── app-shell # app-shell component +│ ├── app-shell.component.html +│ ├── app-shell.component.scss +│ ├── app-shell.component.spec.ts +│ └── app-shell.component.ts +└── main.server.ts # main server application bootstrapping + + + + +```shell +ng build --configuration=development +``` + +Or to use the production configuration. + +```shell +ng build +``` + +To verify the build output, open dist/my-app/browser/index.html. +Look for default text `app-shell works!` to show that the application shell route was rendered as part of the output. + + diff --git a/adev-es/src/content/ecosystem/service-workers/app-shell.md b/adev-es/src/content/ecosystem/service-workers/app-shell.md index 31e86a0..2c23173 100644 --- a/adev-es/src/content/ecosystem/service-workers/app-shell.md +++ b/adev-es/src/content/ecosystem/service-workers/app-shell.md @@ -1,56 +1,56 @@ -# App shell pattern +# Patrón App shell -The [App shell pattern](https://developer.chrome.com/blog/app-shell) is a way to render a portion of your application using a route at build time. -It can improve the user experience by quickly launching a static rendered page (a skeleton common to all pages) while the browser downloads the full client version and switches to it automatically after the code loads. +El [patrón App shell](https://developer.chrome.com/blog/app-shell) es una forma de renderizar una parte de tu aplicación usando una ruta en tiempo de compilación. +Puede mejorar la experiencia de usuario al lanzar rápidamente una página estática renderizada (un esqueleto común a todas las páginas) mientras el navegador descarga la versión completa del cliente y cambia a ella automáticamente cuando el código termina de cargar. -This gives users a meaningful first paint of your application that appears quickly because the browser can render the HTML and CSS without the need to initialize any JavaScript. +Esto brinda a las personas usuarias un primer render significativo de tu aplicación que aparece rápidamente porque el navegador puede mostrar el HTML y el CSS sin necesidad de inicializar JavaScript. - -Do this with the following Angular CLI command: + +Hazlo con el siguiente comando de Angular CLI: ```shell ng new my-app ``` -For an existing application, you have to manually add the `Router` and defining a `` within your application. +Para una aplicación existente, debes agregar manualmente el `Router` y definir un `` dentro de tu aplicación. - -Use the Angular CLI to automatically create the application shell. + +Usa Angular CLI para crear automáticamente el shell de la aplicación. ```shell ng generate app-shell ``` -For more information about this command, see [App shell command](cli/generate/app-shell). +Para obtener más información sobre este comando, consulta [App shell command](cli/generate/app-shell). -The command updates the application code and adds extra files to the project structure. +El comando actualiza el código de la aplicación y agrega archivos adicionales a la estructura del proyecto. src ├── app -│ ├── app.config.server.ts # server application configuration -│ └── app-shell # app-shell component +│ ├── app.config.server.ts # configuración de la aplicación del servidor +│ └── app-shell # componente app-shell │ ├── app-shell.component.html │ ├── app-shell.component.scss │ ├── app-shell.component.spec.ts │ └── app-shell.component.ts -└── main.server.ts # main server application bootstrapping +└── main.server.ts # arranque principal de la aplicación del servidor - + ```shell ng build --configuration=development ``` -Or to use the production configuration. +O usa la configuración de producción. ```shell ng build ``` -To verify the build output, open dist/my-app/browser/index.html. -Look for default text `app-shell works!` to show that the application shell route was rendered as part of the output. +Para verificar el resultado de la compilación, abre dist/my-app/browser/index.html. +Busca el texto predeterminado `app-shell works!` para confirmar que la ruta del shell de la aplicación se renderizó como parte de la salida. diff --git a/adev-es/src/content/ecosystem/service-workers/communications.en.md b/adev-es/src/content/ecosystem/service-workers/communications.en.md new file mode 100644 index 0000000..71e9ffe --- /dev/null +++ b/adev-es/src/content/ecosystem/service-workers/communications.en.md @@ -0,0 +1,108 @@ +# Communicating with the Service Worker + +Enabling service worker support does more than just register the service worker; it also provides services you can use to interact with the service worker and control the caching of your application. + +## `SwUpdate` service + +The `SwUpdate` service gives you access to events that indicate when the service worker discovers and installs an available update for your application. + +The `SwUpdate` service supports three separate operations: + +- Receiving notifications when an updated version is _detected_ on the server, _installed and ready_ to be used locally or when an _installation fails_. +- Asking the service worker to check the server for new updates. +- Asking the service worker to activate the latest version of the application for the current tab. + +### Version updates + +The `versionUpdates` is an `Observable` property of `SwUpdate` and emits five event types: + +| Event types | Details | +| :------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `VersionDetectedEvent` | Emitted when the service worker has detected a new version of the app on the server and is about to start downloading it. | +| `NoNewVersionDetectedEvent` | Emitted when the service worker has checked the version of the app on the server and did not find a new version. | +| `VersionReadyEvent` | Emitted when a new version of the app is available to be activated by clients. It may be used to notify the user of an available update or prompt them to refresh the page. | +| `VersionInstallationFailedEvent` | Emitted when the installation of a new version failed. It may be used for logging/monitoring purposes. | +| `VersionFailedEvent` | Emitted when a version encounters a critical failure (such as broken hash errors) that affects all clients using that version. Provides error details for debugging and transparency. | + + + +### Checking for updates + +It's possible to ask the service worker to check if any updates have been deployed to the server. +The service worker checks for updates during initialization and on each navigation request —that is, when the user navigates from a different address to your application. +However, you might choose to manually check for updates if you have a site that changes frequently or want updates to happen on a schedule. + +Do this with the `checkForUpdate()` method: + + + +This method returns a `Promise` which indicates if an update is available for activation. +The check might fail, which will cause a rejection of the `Promise`. + + +In order to avoid negatively affecting the initial rendering of the page, by default the Angular service worker service waits for up to 30 seconds for the application to stabilize before registering the ServiceWorker script. + +Constantly polling for updates, for example, with [setInterval()](https://developer.mozilla.org/docs/Web/API/WindowOrWorkerGlobalScope/setInterval) or RxJS' [interval()](https://rxjs.dev/api/index/function/interval), prevents the application from stabilizing and the ServiceWorker script is not registered with the browser until the 30 seconds upper limit is reached. + +This is true for any kind of polling done by your application. +Check the [isStable](api/core/ApplicationRef#isStable) documentation for more information. + +Avoid that delay by waiting for the application to stabilize first, before starting to poll for updates, as shown in the preceding example. +Alternatively, you might want to define a different [registration strategy](api/service-worker/SwRegistrationOptions#registrationStrategy) for the ServiceWorker. + + +### Updating to the latest version + +You can update an existing tab to the latest version by reloading the page as soon as a new version is ready. +To avoid disrupting the user's progress, it is generally a good idea to prompt the user and let them confirm that it is OK to reload the page and update to the latest version: + + + + +Calling `activateUpdate()` updates a tab to the latest version without reloading the page, but this could break the application. + +Updating without reloading can create a version mismatch between the application shell and other page resources, such as lazy-loaded chunks, whose filenames may change between versions. + +You should only use `activateUpdate()`, if you are certain it is safe for your specific use case. + + +### Handling an unrecoverable state + +In some cases, the version of the application used by the service worker to serve a client might be in a broken state that cannot be recovered from without a full page reload. + +For example, imagine the following scenario: + +1. A user opens the application for the first time and the service worker caches the latest version of the application. + Assume the application's cached assets include `index.html`, `main..js` and `lazy-chunk..js`. + +1. The user closes the application and does not open it for a while. +1. After some time, a new version of the application is deployed to the server. + This newer version includes the files `index.html`, `main..js` and `lazy-chunk..js`. + +IMPORTANT: The hashes are different now, because the content of the files changed. The old version is no longer available on the server. + +1. In the meantime, the user's browser decides to evict `lazy-chunk..js` from its cache. + Browsers might decide to evict specific (or all) resources from a cache in order to reclaim disk space. + +1. The user opens the application again. + The service worker serves the latest version known to it at this point, namely the old version (`index.html` and `main..js`). + +1. At some later point, the application requests the lazy bundle, `lazy-chunk..js`. +1. The service worker is unable to find the asset in the cache (remember that the browser evicted it). + Nor is it able to retrieve it from the server (because the server now only has `lazy-chunk..js` from the newer version). + +In the preceding scenario, the service worker is not able to serve an asset that would normally be cached. +That particular application version is broken and there is no way to fix the state of the client without reloading the page. +In such cases, the service worker notifies the client by sending an `UnrecoverableStateEvent` event. +Subscribe to `SwUpdate#unrecoverable` to be notified and handle these errors. + + + +## More on Angular service workers + +You might also be interested in the following: + + + + + diff --git a/adev-es/src/content/ecosystem/service-workers/communications.md b/adev-es/src/content/ecosystem/service-workers/communications.md index 71e9ffe..602f63f 100644 --- a/adev-es/src/content/ecosystem/service-workers/communications.md +++ b/adev-es/src/content/ecosystem/service-workers/communications.md @@ -1,108 +1,108 @@ -# Communicating with the Service Worker +# Comunícate con el Service Worker -Enabling service worker support does more than just register the service worker; it also provides services you can use to interact with the service worker and control the caching of your application. +Habilitar el soporte de service worker implica algo más que registrarlo; también proporciona servicios que puedes usar para interactuar con el service worker y controlar la caché de tu aplicación. -## `SwUpdate` service +## Servicio `SwUpdate` -The `SwUpdate` service gives you access to events that indicate when the service worker discovers and installs an available update for your application. +El servicio `SwUpdate` te da acceso a eventos que indican cuándo el service worker descubre e instala una actualización disponible para tu aplicación. -The `SwUpdate` service supports three separate operations: +El servicio `SwUpdate` admite tres operaciones diferentes: -- Receiving notifications when an updated version is _detected_ on the server, _installed and ready_ to be used locally or when an _installation fails_. -- Asking the service worker to check the server for new updates. -- Asking the service worker to activate the latest version of the application for the current tab. +- Recibir notificaciones cuando se _detecta_ una versión actualizada en el servidor, cuando se _instala y está lista_ para usarse localmente o cuando una _instalación falla_. +- Pedirle al service worker que verifique en el servidor si hay nuevas actualizaciones. +- Pedirle al service worker que active la versión más reciente de la aplicación para la pestaña actual. -### Version updates +### Actualizaciones de versión -The `versionUpdates` is an `Observable` property of `SwUpdate` and emits five event types: +`versionUpdates` es una propiedad `Observable` de `SwUpdate` y emite cinco tipos de eventos: -| Event types | Details | -| :------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| `VersionDetectedEvent` | Emitted when the service worker has detected a new version of the app on the server and is about to start downloading it. | -| `NoNewVersionDetectedEvent` | Emitted when the service worker has checked the version of the app on the server and did not find a new version. | -| `VersionReadyEvent` | Emitted when a new version of the app is available to be activated by clients. It may be used to notify the user of an available update or prompt them to refresh the page. | -| `VersionInstallationFailedEvent` | Emitted when the installation of a new version failed. It may be used for logging/monitoring purposes. | -| `VersionFailedEvent` | Emitted when a version encounters a critical failure (such as broken hash errors) that affects all clients using that version. Provides error details for debugging and transparency. | +| Tipos de eventos | Detalles | +|:-------------------------------- |:------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `VersionDetectedEvent` | Se emite cuando el service worker detecta una nueva versión de la aplicación en el servidor y está a punto de comenzar a descargarla. | +| `NoNewVersionDetectedEvent` | Se emite cuando el service worker verifica la versión de la aplicación en el servidor y no encuentra una versión nueva. | +| `VersionReadyEvent` | Se emite cuando hay una nueva versión disponible para que los clientes la activen. Puede usarse para notificar a la persona usuaria que hay una actualización disponible o para pedirle que actualice la página. | +| `VersionInstallationFailedEvent` | Se emite cuando la instalación de una nueva versión falla. Puede utilizarse con fines de registro o monitoreo. | +| `VersionFailedEvent` | Se emite cuando una versión encuentra una falla crítica (como errores de hashes rotos) que afecta a todas las personas usuarias que utilizan esa versión. Proporciona detalles del error para depuración y transparencia. | -### Checking for updates +### Verificando actualizaciones -It's possible to ask the service worker to check if any updates have been deployed to the server. -The service worker checks for updates during initialization and on each navigation request —that is, when the user navigates from a different address to your application. -However, you might choose to manually check for updates if you have a site that changes frequently or want updates to happen on a schedule. +Es posible pedirle al service worker que revise si se desplegó alguna actualización en el servidor. +El service worker busca actualizaciones durante la inicialización y en cada solicitud de navegación—es decir, cuando la persona usuaria navega desde una dirección diferente hacia tu aplicación. +Sin embargo, podrías optar por verificar las actualizaciones manualmente si tu sitio cambia con frecuencia o si quieres que las actualizaciones sucedan según un cronograma. -Do this with the `checkForUpdate()` method: +Hazlo con el método `checkForUpdate()`: -This method returns a `Promise` which indicates if an update is available for activation. -The check might fail, which will cause a rejection of the `Promise`. +Este método devuelve un `Promise` que indica si hay una actualización disponible para activar. +La verificación puede fallar, lo que provocará que la `Promise` se rechace. - -In order to avoid negatively affecting the initial rendering of the page, by default the Angular service worker service waits for up to 30 seconds for the application to stabilize before registering the ServiceWorker script. + +Para evitar que el renderizado inicial de la página se vea afectado de forma negativa, el servicio del service worker de Angular espera de manera predeterminada hasta 30 segundos a que la aplicación se estabilice antes de registrar el script del ServiceWorker. -Constantly polling for updates, for example, with [setInterval()](https://developer.mozilla.org/docs/Web/API/WindowOrWorkerGlobalScope/setInterval) or RxJS' [interval()](https://rxjs.dev/api/index/function/interval), prevents the application from stabilizing and the ServiceWorker script is not registered with the browser until the 30 seconds upper limit is reached. +Consultar constantemente si hay actualizaciones, por ejemplo, con [setInterval()](https://developer.mozilla.org/docs/Web/API/WindowOrWorkerGlobalScope/setInterval) o con [interval()](https://rxjs.dev/api/index/function/interval) de RxJS, impide que la aplicación se estabilice y evita que el script del ServiceWorker se registre en el navegador hasta que se alcanza el límite máximo de 30 segundos. -This is true for any kind of polling done by your application. -Check the [isStable](api/core/ApplicationRef#isStable) documentation for more information. +Esto aplica a cualquier tipo de sondeo que haga tu aplicación. +Consulta la documentación de [isStable](api/core/ApplicationRef#isStable) para obtener más información. -Avoid that delay by waiting for the application to stabilize first, before starting to poll for updates, as shown in the preceding example. -Alternatively, you might want to define a different [registration strategy](api/service-worker/SwRegistrationOptions#registrationStrategy) for the ServiceWorker. +Evita ese retraso esperando primero a que la aplicación se estabilice antes de comenzar a consultar por actualizaciones, como se muestra en el ejemplo anterior. +Como alternativa, puedes definir una [estrategia de registro](api/service-worker/SwRegistrationOptions#registrationStrategy) diferente para el ServiceWorker. -### Updating to the latest version +### Actualizando a la versión más reciente -You can update an existing tab to the latest version by reloading the page as soon as a new version is ready. -To avoid disrupting the user's progress, it is generally a good idea to prompt the user and let them confirm that it is OK to reload the page and update to the latest version: +Puedes actualizar una pestaña existente a la versión más reciente recargando la página tan pronto como una nueva versión esté lista. +Para evitar interrumpir el progreso de la persona usuaria, en general es recomendable mostrar un aviso y pedir que confirme si desea recargar la página y actualizar a la versión más reciente: - -Calling `activateUpdate()` updates a tab to the latest version without reloading the page, but this could break the application. + +Llamar a `activateUpdate()` actualiza una pestaña a la versión más reciente sin recargar la página, pero esto podría romper la aplicación. -Updating without reloading can create a version mismatch between the application shell and other page resources, such as lazy-loaded chunks, whose filenames may change between versions. +Actualizar sin recargar puede crear una discrepancia de versiones entre el shell de la aplicación y otros recursos de la página, como los chunks cargados de forma diferida, cuyos nombres de archivo pueden cambiar entre versiones. -You should only use `activateUpdate()`, if you are certain it is safe for your specific use case. +Debes usar `activateUpdate()` solo si estás seguro de que es seguro para tu caso específico. -### Handling an unrecoverable state +### Manejar un estado irrecuperable -In some cases, the version of the application used by the service worker to serve a client might be in a broken state that cannot be recovered from without a full page reload. +En algunos casos, la versión de la aplicación que el service worker usa para atender a una persona usuaria puede quedar en un estado roto que no se puede recuperar sin recargar completamente la página. -For example, imagine the following scenario: +Por ejemplo, imagina el siguiente escenario: -1. A user opens the application for the first time and the service worker caches the latest version of the application. - Assume the application's cached assets include `index.html`, `main..js` and `lazy-chunk..js`. +1. Una persona usuaria abre la aplicación por primera vez y el service worker almacena en caché la versión más reciente de la aplicación. + Supón que los recursos cacheados de la aplicación incluyen `index.html`, `main..js` y `lazy-chunk..js`. -1. The user closes the application and does not open it for a while. -1. After some time, a new version of the application is deployed to the server. - This newer version includes the files `index.html`, `main..js` and `lazy-chunk..js`. +1. La persona usuaria cierra la aplicación y no la abre durante un tiempo. +1. Después de un tiempo, se despliega en el servidor una nueva versión de la aplicación. + Esta versión más reciente incluye los archivos `index.html`, `main..js` y `lazy-chunk..js`. -IMPORTANT: The hashes are different now, because the content of the files changed. The old version is no longer available on the server. +IMPORTANTE: Los hashes ahora son diferentes porque el contenido de los archivos cambió. La versión anterior ya no está disponible en el servidor. -1. In the meantime, the user's browser decides to evict `lazy-chunk..js` from its cache. - Browsers might decide to evict specific (or all) resources from a cache in order to reclaim disk space. +1. Mientras tanto, el navegador de la persona usuaria decide expulsar `lazy-chunk..js` de su caché. + Los navegadores pueden decidir expulsar recursos específicos (o todos) de una caché para recuperar espacio en disco. + +1. La persona usuaria vuelve a abrir la aplicación. + El service worker sirve la última versión que conoce en ese momento, es decir, la versión anterior (`index.html` y `main..js`). -1. The user opens the application again. - The service worker serves the latest version known to it at this point, namely the old version (`index.html` and `main..js`). +1. En algún momento posterior, la aplicación solicita el bundle diferido `lazy-chunk..js`. +1. El service worker no puede encontrar el recurso en la caché (recuerda que el navegador lo expulsó). + Tampoco puede obtenerlo del servidor (porque el servidor ahora solo tiene `lazy-chunk..js` de la versión más reciente). -1. At some later point, the application requests the lazy bundle, `lazy-chunk..js`. -1. The service worker is unable to find the asset in the cache (remember that the browser evicted it). - Nor is it able to retrieve it from the server (because the server now only has `lazy-chunk..js` from the newer version). - -In the preceding scenario, the service worker is not able to serve an asset that would normally be cached. -That particular application version is broken and there is no way to fix the state of the client without reloading the page. -In such cases, the service worker notifies the client by sending an `UnrecoverableStateEvent` event. -Subscribe to `SwUpdate#unrecoverable` to be notified and handle these errors. +En el escenario anterior, el service worker no puede servir un recurso que normalmente estaría en caché. +Esa versión particular de la aplicación está rota y no hay forma de corregir el estado del cliente sin recargar la página. +En esos casos, el service worker notifica al cliente enviando un evento `UnrecoverableStateEvent`. +Suscríbete a `SwUpdate#unrecoverable` para recibir la notificación y manejar estos errores. -## More on Angular service workers +## Más sobre los service workers de Angular -You might also be interested in the following: +También podría interesarte lo siguiente: - + diff --git a/adev-es/src/content/ecosystem/service-workers/config.en.md b/adev-es/src/content/ecosystem/service-workers/config.en.md new file mode 100644 index 0000000..8f13339 --- /dev/null +++ b/adev-es/src/content/ecosystem/service-workers/config.en.md @@ -0,0 +1,387 @@ +# Service Worker configuration file + +This topic describes the properties of the service worker configuration file. + +## Modifying the configuration + +The `ngsw-config.json` JSON configuration file specifies which files and data URLs the Angular service worker should cache and how it should update the cached files and data. +The [Angular CLI](tools/cli) processes this configuration file during `ng build`. + +All file paths must begin with `/`, which corresponds to the deployment directory — usually `dist/` in CLI projects. + +Unless otherwise commented, patterns use a **limited\*** glob format that internally will be converted into regex: + +| Glob formats | Details | +| :----------- | :----------------------------------------------------------------------------------------------------- | +| `**` | Matches 0 or more path segments | +| `*` | Matches 0 or more characters excluding `/` | +| `?` | Matches exactly one character excluding `/` | +| `!` prefix | Marks the pattern as being negative, meaning that only files that don't match the pattern are included | + + +Pay attention that some characters with a special meaning in a regular expression are not escaped and also the pattern is not wrapped in `^`/`$` in the internal glob to regex conversion. + +`$` is a special character in regex that matches the end of the string and will not be automatically escaped when converting the glob pattern to a regular expression. + +If you want to literally match the `$` character, you have to escape it yourself (with `\\$`). For example, the glob pattern `/foo/bar/$value` results in an unmatchable expression, because it is impossible to have a string that has any characters after it has ended. + +The pattern will not be automatically wrapped in `^` and `$` when converting it to a regular expression. Therefore, the patterns will partially match the request URLs. + +If you want your patterns to match the beginning and/or end of URLs, you can add `^`/`$` yourself. For example, the glob pattern `/foo/bar/*.js` will match both `.js` and `.json` files. If you want to only match `.js` files, use `/foo/bar/*.js$`. + + +Example patterns: + +| Patterns | Details | +| :----------- | :------------------------------------ | +| `/**/*.html` | Specifies all HTML files | +| `/*.html` | Specifies only HTML files in the root | +| `!/**/*.map` | Exclude all sourcemaps | + +## Service worker configuration properties + +The following sections describe each property of the configuration file. + +### `appData` + +This section enables you to pass any data you want that describes this particular version of the application. +The `SwUpdate` service includes that data in the update notifications. +Many applications use this section to provide additional information for the display of UI popups, notifying users of the available update. + +### `index` + +Specifies the file that serves as the index page to satisfy navigation requests. +Usually this is `/index.html`. + +### `assetGroups` + +_Assets_ are resources that are part of the application version that update along with the application. +They can include resources loaded from the page's origin as well as third-party resources loaded from CDNs and other external URLs. +As not all such external URLs might be known at build time, URL patterns can be matched. + +HELPFUL: For the service worker to handle resources that are loaded from different origins, make sure that [CORS](https://developer.mozilla.org/docs/Web/HTTP/CORS) is correctly configured on each origin's server. + +This field contains an array of asset groups, each of which defines a set of asset resources and the policy by which they are cached. + +```ts +{ + "assetGroups": [ + { + … + }, + { + … + } + ] +} +``` + +HELPFUL: When the ServiceWorker handles a request, it checks asset groups in the order in which they appear in `ngsw-config.json`. +The first asset group that matches the requested resource handles the request. + +It is recommended that you put the more specific asset groups higher in the list. +For example, an asset group that matches `/foo.js` should appear before one that matches `*.js`. + +Each asset group specifies both a group of resources and a policy that governs them. +This policy determines when the resources are fetched and what happens when changes are detected. + +Asset groups follow the Typescript interface shown here: + +```ts +interface AssetGroup { + name: string; + installMode?: 'prefetch' | 'lazy'; + updateMode?: 'prefetch' | 'lazy'; + resources: { + files?: string[]; + urls?: string[]; + }; + cacheQueryOptions?: { + ignoreSearch?: boolean; + }; +} +``` + +Each `AssetGroup` is defined by the following asset group properties. + +#### `name` + +A `name` is mandatory. +It identifies this particular group of assets between versions of the configuration. + +#### `installMode` + +The `installMode` determines how these resources are initially cached. +The `installMode` can be either of two values: + +| Values | Details | +| :--------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `prefetch` | Tells the Angular service worker to fetch every single listed resource while it's caching the current version of the application. This is bandwidth-intensive but ensures resources are available whenever they're requested, even if the browser is currently offline. | +| `lazy` | Does not cache any of the resources up front. Instead, the Angular service worker only caches resources for which it receives requests. This is an on-demand caching mode. Resources that are never requested are not cached. This is useful for things like images at different resolutions, so the service worker only caches the correct assets for the particular screen and orientation. | + +Defaults to `prefetch`. + +#### `updateMode` + +For resources already in the cache, the `updateMode` determines the caching behavior when a new version of the application is discovered. +Any resources in the group that have changed since the previous version are updated in accordance with `updateMode`. + +| Values | Details | +| :--------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `prefetch` | Tells the service worker to download and cache the changed resources immediately. | +| `lazy` | Tells the service worker to not cache those resources. Instead, it treats them as unrequested and waits until they're requested again before updating them. An `updateMode` of `lazy` is only valid if the `installMode` is also `lazy`. | + +Defaults to the value `installMode` is set to. + +#### `resources` + +This section describes the resources to cache, broken up into the following groups: + +| Resource groups | Details | +| :-------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `files` | Lists patterns that match files in the distribution directory. These can be single files or glob-like patterns that match a number of files. | +| `urls` | Includes both URLs and URL patterns that are matched at runtime. These resources are not fetched directly and do not have content hashes, but they are cached according to their HTTP headers. This is most useful for CDNs such as the Google Fonts service.
_(Negative glob patterns are not supported and `?` will be matched literally; that is, it will not match any character other than `?`.)_ | + +#### `cacheQueryOptions` + +These options are used to modify the matching behavior of requests. +They are passed to the browsers `Cache#match` function. +See [MDN](https://developer.mozilla.org/docs/Web/API/Cache/match) for details. +Currently, only the following options are supported: + +| Options | Details | +| :------------- | :-------------------------------------------- | +| `ignoreSearch` | Ignore query parameters. Defaults to `false`. | + +### `dataGroups` + +Unlike asset resources, data requests are not versioned along with the application. +They're cached according to manually-configured policies that are more useful for situations such as API requests and other data dependencies. + +This field contains an array of data groups, each of which defines a set of data resources and the policy by which they are cached. + +```json +{ + "dataGroups": [ + { + … + }, + { + … + } + ] +} +``` + +HELPFUL: When the ServiceWorker handles a request, it checks data groups in the order in which they appear in `ngsw-config.json`. +The first data group that matches the requested resource handles the request. + +It is recommended that you put the more specific data groups higher in the list. +For example, a data group that matches `/api/foo.json` should appear before one that matches `/api/*.json`. + +Data groups follow this Typescript interface: + +```ts +export interface DataGroup { + name: string; + urls: string[]; + version?: number; + cacheConfig: { + maxSize: number; + maxAge: string; + timeout?: string; + refreshAhead?: string; + strategy?: 'freshness' | 'performance'; + }; + cacheQueryOptions?: { + ignoreSearch?: boolean; + }; +} +``` + +Each `DataGroup` is defined by the following data group properties. + +#### `name` + +Similar to `assetGroups`, every data group has a `name` which uniquely identifies it. + +#### `urls` + +A list of URL patterns. +URLs that match these patterns are cached according to this data group's policy. +Only non-mutating requests (GET and HEAD) are cached. + +- Negative glob patterns are not supported +- `?` is matched literally; that is, it matches _only_ the character `?` + +#### `version` + +Occasionally APIs change formats in a way that is not backward-compatible. +A new version of the application might not be compatible with the old API format and thus might not be compatible with existing cached resources from that API. + +`version` provides a mechanism to indicate that the resources being cached have been updated in a backwards-incompatible way, and that the old cache entries —those from previous versions— should be discarded. + +`version` is an integer field and defaults to `1`. + +#### `cacheConfig` + +The following properties define the policy by which matching requests are cached. + +##### `maxSize` + +The maximum number of entries, or responses, in the cache. + +CRITICAL: Open-ended caches can grow in unbounded ways and eventually exceed storage quotas, resulting in eviction. + +##### `maxAge` + +The `maxAge` parameter indicates how long responses are allowed to remain in the cache before being considered invalid and evicted. `maxAge` is a duration string, using the following unit suffixes: + +| Suffixes | Details | +| :------- | :----------- | +| `d` | Days | +| `h` | Hours | +| `m` | Minutes | +| `s` | Seconds | +| `u` | Milliseconds | + +For example, the string `3d12h` caches content for up to three and a half days. + +##### `timeout` + +This duration string specifies the network timeout. +The network timeout is how long the Angular service worker waits for the network to respond before using a cached response, if configured to do so. +`timeout` is a duration string, using the following unit suffixes: + +| Suffixes | Details | +| :------- | :----------- | +| `d` | Days | +| `h` | Hours | +| `m` | Minutes | +| `s` | Seconds | +| `u` | Milliseconds | + +For example, the string `5s30u` translates to five seconds and 30 milliseconds of network timeout. + +##### `refreshAhead` + +This duration string specifies the time ahead of the expiration of a cached resource when the Angular service worker should proactively attempt to refresh the resource from the network. +The `refreshAhead` duration is an optional configuration that determines how much time before the expiration of a cached response the service worker should initiate a request to refresh the resource from the network. + +| Suffixes | Details | +| :------- | :----------- | +| `d` | Days | +| `h` | Hours | +| `m` | Minutes | +| `s` | Seconds | +| `u` | Milliseconds | + +For example, the string `1h30m` translates to one hour and 30 minutes ahead of the expiration time. + +##### `strategy` + +The Angular service worker can use either of two caching strategies for data resources. + +| Caching strategies | Details | +| :----------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `performance` | The default, optimizes for responses that are as fast as possible. If a resource exists in the cache, the cached version is used, and no network request is made. This allows for some staleness, depending on the `maxAge`, in exchange for better performance. This is suitable for resources that don't change often; for example, user avatar images. | +| `freshness` | Optimizes for currency of data, preferentially fetching requested data from the network. Only if the network times out, according to `timeout`, does the request fall back to the cache. This is useful for resources that change frequently; for example, account balances. | + +HELPFUL: You can also emulate a third strategy, [staleWhileRevalidate](https://developers.google.com/web/fundamentals/instant-and-offline/offline-cookbook/#stale-while-revalidate), which returns cached data if it is available, but also fetches fresh data from the network in the background for next time. +To use this strategy set `strategy` to `freshness` and `timeout` to `0u` in `cacheConfig`. + +This essentially does the following: + +1. Try to fetch from the network first. +2. If the network request does not complete immediately, that is after a timeout of 0 ms, ignore the cache age and fall back to the cached value. +3. Once the network request completes, update the cache for future requests. +4. If the resource does not exist in the cache, wait for the network request anyway. + +##### `cacheOpaqueResponses` + +Whether the Angular service worker should cache opaque responses or not. + +If not specified, the default value depends on the data group's configured strategy: + +| Strategies | Details | +| :------------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Groups with the `freshness` strategy | The default value is `true` and the service worker caches opaque responses. These groups will request the data every time and only fall back to the cached response when offline or on a slow network. Therefore, it doesn't matter if the service worker caches an error response. | +| Groups with the `performance` strategy | The default value is `false` and the service worker doesn't cache opaque responses. These groups would continue to return a cached response until `maxAge` expires, even if the error was due to a temporary network or server issue. Therefore, it would be problematic for the service worker to cache an error response. | + + + +In case you are not familiar, an [opaque response](https://fetch.spec.whatwg.org#concept-filtered-response-opaque) is a special type of response returned when requesting a resource that is on a different origin which doesn't return CORS headers. +One of the characteristics of an opaque response is that the service worker is not allowed to read its status, meaning it can't check if the request was successful or not. +See [Introduction to `fetch()`](https://developers.google.com/web/updates/2015/03/introduction-to-fetch#response_types) for more details. + +If you are not able to implement CORS — for example, if you don't control the origin — prefer using the `freshness` strategy for resources that result in opaque responses. + + + +#### `cacheQueryOptions` + +See [assetGroups](#assetgroups) for details. + +### `navigationUrls` + +This optional section enables you to specify a custom list of URLs that will be redirected to the index file. + +#### Handling navigation requests + +The ServiceWorker redirects navigation requests that don't match any `asset` or `data` group to the specified [index file](#index). +A request is considered to be a navigation request if: + +- Its [method](https://developer.mozilla.org/docs/Web/API/Request/method) is `GET` +- Its [mode](https://developer.mozilla.org/docs/Web/API/Request/mode) is `navigation` +- It accepts a `text/html` response as determined by the value of the `Accept` header +- Its URL matches the following criteria: + - The URL must not contain a file extension (that is, a `.`) in the last path segment + - The URL must not contain `__` + +HELPFUL: To configure whether navigation requests are sent through to the network or not, see the [navigationRequestStrategy](#navigationrequeststrategy) section and [applicationMaxAge](#applicationmaxage) sections. + +#### Matching navigation request URLs + +While these default criteria are fine in most cases, it is sometimes desirable to configure different rules. +For example, you might want to ignore specific routes, such as those that are not part of the Angular app, and pass them through to the server. + +This field contains an array of URLs and [glob-like](#modifying-the-configuration) URL patterns that are matched at runtime. +It can contain both negative patterns (that is, patterns starting with `!`) and non-negative patterns and URLs. + +Only requests whose URLs match _any_ of the non-negative URLs/patterns and _none_ of the negative ones are considered navigation requests. +The URL query is ignored when matching. + +If the field is omitted, it defaults to: + +```ts + +[ +'/**', // Include all URLs. +'!/**/*.*', // Exclude URLs to files (containing a file extension in the last segment). +'!/**/*__*', // Exclude URLs containing `__` in the last segment. +'!/**/*__*/**', // Exclude URLs containing `__` in any other segment. +] + +``` + +### `navigationRequestStrategy` + +This optional property enables you to configure how the service worker handles navigation requests: + +```json + +{ + "navigationRequestStrategy": "freshness" +} +``` + +| Possible values | Details | +| :-------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `'performance'` | The default setting. Serves the specified [index file](#index), which is typically cached. | +| `'freshness'` | Passes the requests through to the network and falls back to the `performance` behavior when offline. This value is useful when the server redirects the navigation requests elsewhere using a `3xx` HTTP redirect status code. Reasons for using this value include:
  • Redirecting to an authentication website when authentication is not handled by the application
  • Redirecting specific URLs to avoid breaking existing links/bookmarks after a website redesign
  • Redirecting to a different website, such as a server-status page, while a page is temporarily down
| + +IMPORTANT: The `freshness` strategy usually results in more requests sent to the server, which can increase response latency. It is recommended that you use the default performance strategy whenever possible. + +### `applicationMaxAge` + +This optional property enables you to configure how long the service worker will cache any requests. Within the `maxAge`, files will be served from cache. Beyond it, all requests will only be served from the network, including asset and data requests. diff --git a/adev-es/src/content/ecosystem/service-workers/config.md b/adev-es/src/content/ecosystem/service-workers/config.md index 8f13339..e69de29 100644 --- a/adev-es/src/content/ecosystem/service-workers/config.md +++ b/adev-es/src/content/ecosystem/service-workers/config.md @@ -1,387 +0,0 @@ -# Service Worker configuration file - -This topic describes the properties of the service worker configuration file. - -## Modifying the configuration - -The `ngsw-config.json` JSON configuration file specifies which files and data URLs the Angular service worker should cache and how it should update the cached files and data. -The [Angular CLI](tools/cli) processes this configuration file during `ng build`. - -All file paths must begin with `/`, which corresponds to the deployment directory — usually `dist/` in CLI projects. - -Unless otherwise commented, patterns use a **limited\*** glob format that internally will be converted into regex: - -| Glob formats | Details | -| :----------- | :----------------------------------------------------------------------------------------------------- | -| `**` | Matches 0 or more path segments | -| `*` | Matches 0 or more characters excluding `/` | -| `?` | Matches exactly one character excluding `/` | -| `!` prefix | Marks the pattern as being negative, meaning that only files that don't match the pattern are included | - - -Pay attention that some characters with a special meaning in a regular expression are not escaped and also the pattern is not wrapped in `^`/`$` in the internal glob to regex conversion. - -`$` is a special character in regex that matches the end of the string and will not be automatically escaped when converting the glob pattern to a regular expression. - -If you want to literally match the `$` character, you have to escape it yourself (with `\\$`). For example, the glob pattern `/foo/bar/$value` results in an unmatchable expression, because it is impossible to have a string that has any characters after it has ended. - -The pattern will not be automatically wrapped in `^` and `$` when converting it to a regular expression. Therefore, the patterns will partially match the request URLs. - -If you want your patterns to match the beginning and/or end of URLs, you can add `^`/`$` yourself. For example, the glob pattern `/foo/bar/*.js` will match both `.js` and `.json` files. If you want to only match `.js` files, use `/foo/bar/*.js$`. - - -Example patterns: - -| Patterns | Details | -| :----------- | :------------------------------------ | -| `/**/*.html` | Specifies all HTML files | -| `/*.html` | Specifies only HTML files in the root | -| `!/**/*.map` | Exclude all sourcemaps | - -## Service worker configuration properties - -The following sections describe each property of the configuration file. - -### `appData` - -This section enables you to pass any data you want that describes this particular version of the application. -The `SwUpdate` service includes that data in the update notifications. -Many applications use this section to provide additional information for the display of UI popups, notifying users of the available update. - -### `index` - -Specifies the file that serves as the index page to satisfy navigation requests. -Usually this is `/index.html`. - -### `assetGroups` - -_Assets_ are resources that are part of the application version that update along with the application. -They can include resources loaded from the page's origin as well as third-party resources loaded from CDNs and other external URLs. -As not all such external URLs might be known at build time, URL patterns can be matched. - -HELPFUL: For the service worker to handle resources that are loaded from different origins, make sure that [CORS](https://developer.mozilla.org/docs/Web/HTTP/CORS) is correctly configured on each origin's server. - -This field contains an array of asset groups, each of which defines a set of asset resources and the policy by which they are cached. - -```ts -{ - "assetGroups": [ - { - … - }, - { - … - } - ] -} -``` - -HELPFUL: When the ServiceWorker handles a request, it checks asset groups in the order in which they appear in `ngsw-config.json`. -The first asset group that matches the requested resource handles the request. - -It is recommended that you put the more specific asset groups higher in the list. -For example, an asset group that matches `/foo.js` should appear before one that matches `*.js`. - -Each asset group specifies both a group of resources and a policy that governs them. -This policy determines when the resources are fetched and what happens when changes are detected. - -Asset groups follow the Typescript interface shown here: - -```ts -interface AssetGroup { - name: string; - installMode?: 'prefetch' | 'lazy'; - updateMode?: 'prefetch' | 'lazy'; - resources: { - files?: string[]; - urls?: string[]; - }; - cacheQueryOptions?: { - ignoreSearch?: boolean; - }; -} -``` - -Each `AssetGroup` is defined by the following asset group properties. - -#### `name` - -A `name` is mandatory. -It identifies this particular group of assets between versions of the configuration. - -#### `installMode` - -The `installMode` determines how these resources are initially cached. -The `installMode` can be either of two values: - -| Values | Details | -| :--------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `prefetch` | Tells the Angular service worker to fetch every single listed resource while it's caching the current version of the application. This is bandwidth-intensive but ensures resources are available whenever they're requested, even if the browser is currently offline. | -| `lazy` | Does not cache any of the resources up front. Instead, the Angular service worker only caches resources for which it receives requests. This is an on-demand caching mode. Resources that are never requested are not cached. This is useful for things like images at different resolutions, so the service worker only caches the correct assets for the particular screen and orientation. | - -Defaults to `prefetch`. - -#### `updateMode` - -For resources already in the cache, the `updateMode` determines the caching behavior when a new version of the application is discovered. -Any resources in the group that have changed since the previous version are updated in accordance with `updateMode`. - -| Values | Details | -| :--------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `prefetch` | Tells the service worker to download and cache the changed resources immediately. | -| `lazy` | Tells the service worker to not cache those resources. Instead, it treats them as unrequested and waits until they're requested again before updating them. An `updateMode` of `lazy` is only valid if the `installMode` is also `lazy`. | - -Defaults to the value `installMode` is set to. - -#### `resources` - -This section describes the resources to cache, broken up into the following groups: - -| Resource groups | Details | -| :-------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| `files` | Lists patterns that match files in the distribution directory. These can be single files or glob-like patterns that match a number of files. | -| `urls` | Includes both URLs and URL patterns that are matched at runtime. These resources are not fetched directly and do not have content hashes, but they are cached according to their HTTP headers. This is most useful for CDNs such as the Google Fonts service.
_(Negative glob patterns are not supported and `?` will be matched literally; that is, it will not match any character other than `?`.)_ | - -#### `cacheQueryOptions` - -These options are used to modify the matching behavior of requests. -They are passed to the browsers `Cache#match` function. -See [MDN](https://developer.mozilla.org/docs/Web/API/Cache/match) for details. -Currently, only the following options are supported: - -| Options | Details | -| :------------- | :-------------------------------------------- | -| `ignoreSearch` | Ignore query parameters. Defaults to `false`. | - -### `dataGroups` - -Unlike asset resources, data requests are not versioned along with the application. -They're cached according to manually-configured policies that are more useful for situations such as API requests and other data dependencies. - -This field contains an array of data groups, each of which defines a set of data resources and the policy by which they are cached. - -```json -{ - "dataGroups": [ - { - … - }, - { - … - } - ] -} -``` - -HELPFUL: When the ServiceWorker handles a request, it checks data groups in the order in which they appear in `ngsw-config.json`. -The first data group that matches the requested resource handles the request. - -It is recommended that you put the more specific data groups higher in the list. -For example, a data group that matches `/api/foo.json` should appear before one that matches `/api/*.json`. - -Data groups follow this Typescript interface: - -```ts -export interface DataGroup { - name: string; - urls: string[]; - version?: number; - cacheConfig: { - maxSize: number; - maxAge: string; - timeout?: string; - refreshAhead?: string; - strategy?: 'freshness' | 'performance'; - }; - cacheQueryOptions?: { - ignoreSearch?: boolean; - }; -} -``` - -Each `DataGroup` is defined by the following data group properties. - -#### `name` - -Similar to `assetGroups`, every data group has a `name` which uniquely identifies it. - -#### `urls` - -A list of URL patterns. -URLs that match these patterns are cached according to this data group's policy. -Only non-mutating requests (GET and HEAD) are cached. - -- Negative glob patterns are not supported -- `?` is matched literally; that is, it matches _only_ the character `?` - -#### `version` - -Occasionally APIs change formats in a way that is not backward-compatible. -A new version of the application might not be compatible with the old API format and thus might not be compatible with existing cached resources from that API. - -`version` provides a mechanism to indicate that the resources being cached have been updated in a backwards-incompatible way, and that the old cache entries —those from previous versions— should be discarded. - -`version` is an integer field and defaults to `1`. - -#### `cacheConfig` - -The following properties define the policy by which matching requests are cached. - -##### `maxSize` - -The maximum number of entries, or responses, in the cache. - -CRITICAL: Open-ended caches can grow in unbounded ways and eventually exceed storage quotas, resulting in eviction. - -##### `maxAge` - -The `maxAge` parameter indicates how long responses are allowed to remain in the cache before being considered invalid and evicted. `maxAge` is a duration string, using the following unit suffixes: - -| Suffixes | Details | -| :------- | :----------- | -| `d` | Days | -| `h` | Hours | -| `m` | Minutes | -| `s` | Seconds | -| `u` | Milliseconds | - -For example, the string `3d12h` caches content for up to three and a half days. - -##### `timeout` - -This duration string specifies the network timeout. -The network timeout is how long the Angular service worker waits for the network to respond before using a cached response, if configured to do so. -`timeout` is a duration string, using the following unit suffixes: - -| Suffixes | Details | -| :------- | :----------- | -| `d` | Days | -| `h` | Hours | -| `m` | Minutes | -| `s` | Seconds | -| `u` | Milliseconds | - -For example, the string `5s30u` translates to five seconds and 30 milliseconds of network timeout. - -##### `refreshAhead` - -This duration string specifies the time ahead of the expiration of a cached resource when the Angular service worker should proactively attempt to refresh the resource from the network. -The `refreshAhead` duration is an optional configuration that determines how much time before the expiration of a cached response the service worker should initiate a request to refresh the resource from the network. - -| Suffixes | Details | -| :------- | :----------- | -| `d` | Days | -| `h` | Hours | -| `m` | Minutes | -| `s` | Seconds | -| `u` | Milliseconds | - -For example, the string `1h30m` translates to one hour and 30 minutes ahead of the expiration time. - -##### `strategy` - -The Angular service worker can use either of two caching strategies for data resources. - -| Caching strategies | Details | -| :----------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `performance` | The default, optimizes for responses that are as fast as possible. If a resource exists in the cache, the cached version is used, and no network request is made. This allows for some staleness, depending on the `maxAge`, in exchange for better performance. This is suitable for resources that don't change often; for example, user avatar images. | -| `freshness` | Optimizes for currency of data, preferentially fetching requested data from the network. Only if the network times out, according to `timeout`, does the request fall back to the cache. This is useful for resources that change frequently; for example, account balances. | - -HELPFUL: You can also emulate a third strategy, [staleWhileRevalidate](https://developers.google.com/web/fundamentals/instant-and-offline/offline-cookbook/#stale-while-revalidate), which returns cached data if it is available, but also fetches fresh data from the network in the background for next time. -To use this strategy set `strategy` to `freshness` and `timeout` to `0u` in `cacheConfig`. - -This essentially does the following: - -1. Try to fetch from the network first. -2. If the network request does not complete immediately, that is after a timeout of 0 ms, ignore the cache age and fall back to the cached value. -3. Once the network request completes, update the cache for future requests. -4. If the resource does not exist in the cache, wait for the network request anyway. - -##### `cacheOpaqueResponses` - -Whether the Angular service worker should cache opaque responses or not. - -If not specified, the default value depends on the data group's configured strategy: - -| Strategies | Details | -| :------------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| Groups with the `freshness` strategy | The default value is `true` and the service worker caches opaque responses. These groups will request the data every time and only fall back to the cached response when offline or on a slow network. Therefore, it doesn't matter if the service worker caches an error response. | -| Groups with the `performance` strategy | The default value is `false` and the service worker doesn't cache opaque responses. These groups would continue to return a cached response until `maxAge` expires, even if the error was due to a temporary network or server issue. Therefore, it would be problematic for the service worker to cache an error response. | - - - -In case you are not familiar, an [opaque response](https://fetch.spec.whatwg.org#concept-filtered-response-opaque) is a special type of response returned when requesting a resource that is on a different origin which doesn't return CORS headers. -One of the characteristics of an opaque response is that the service worker is not allowed to read its status, meaning it can't check if the request was successful or not. -See [Introduction to `fetch()`](https://developers.google.com/web/updates/2015/03/introduction-to-fetch#response_types) for more details. - -If you are not able to implement CORS — for example, if you don't control the origin — prefer using the `freshness` strategy for resources that result in opaque responses. - - - -#### `cacheQueryOptions` - -See [assetGroups](#assetgroups) for details. - -### `navigationUrls` - -This optional section enables you to specify a custom list of URLs that will be redirected to the index file. - -#### Handling navigation requests - -The ServiceWorker redirects navigation requests that don't match any `asset` or `data` group to the specified [index file](#index). -A request is considered to be a navigation request if: - -- Its [method](https://developer.mozilla.org/docs/Web/API/Request/method) is `GET` -- Its [mode](https://developer.mozilla.org/docs/Web/API/Request/mode) is `navigation` -- It accepts a `text/html` response as determined by the value of the `Accept` header -- Its URL matches the following criteria: - - The URL must not contain a file extension (that is, a `.`) in the last path segment - - The URL must not contain `__` - -HELPFUL: To configure whether navigation requests are sent through to the network or not, see the [navigationRequestStrategy](#navigationrequeststrategy) section and [applicationMaxAge](#applicationmaxage) sections. - -#### Matching navigation request URLs - -While these default criteria are fine in most cases, it is sometimes desirable to configure different rules. -For example, you might want to ignore specific routes, such as those that are not part of the Angular app, and pass them through to the server. - -This field contains an array of URLs and [glob-like](#modifying-the-configuration) URL patterns that are matched at runtime. -It can contain both negative patterns (that is, patterns starting with `!`) and non-negative patterns and URLs. - -Only requests whose URLs match _any_ of the non-negative URLs/patterns and _none_ of the negative ones are considered navigation requests. -The URL query is ignored when matching. - -If the field is omitted, it defaults to: - -```ts - -[ -'/**', // Include all URLs. -'!/**/*.*', // Exclude URLs to files (containing a file extension in the last segment). -'!/**/*__*', // Exclude URLs containing `__` in the last segment. -'!/**/*__*/**', // Exclude URLs containing `__` in any other segment. -] - -``` - -### `navigationRequestStrategy` - -This optional property enables you to configure how the service worker handles navigation requests: - -```json - -{ - "navigationRequestStrategy": "freshness" -} -``` - -| Possible values | Details | -| :-------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `'performance'` | The default setting. Serves the specified [index file](#index), which is typically cached. | -| `'freshness'` | Passes the requests through to the network and falls back to the `performance` behavior when offline. This value is useful when the server redirects the navigation requests elsewhere using a `3xx` HTTP redirect status code. Reasons for using this value include:
  • Redirecting to an authentication website when authentication is not handled by the application
  • Redirecting specific URLs to avoid breaking existing links/bookmarks after a website redesign
  • Redirecting to a different website, such as a server-status page, while a page is temporarily down
| - -IMPORTANT: The `freshness` strategy usually results in more requests sent to the server, which can increase response latency. It is recommended that you use the default performance strategy whenever possible. - -### `applicationMaxAge` - -This optional property enables you to configure how long the service worker will cache any requests. Within the `maxAge`, files will be served from cache. Beyond it, all requests will only be served from the network, including asset and data requests. diff --git a/adev-es/src/content/ecosystem/service-workers/custom-service-worker-scripts.en.md b/adev-es/src/content/ecosystem/service-workers/custom-service-worker-scripts.en.md new file mode 100644 index 0000000..d5fdcaa --- /dev/null +++ b/adev-es/src/content/ecosystem/service-workers/custom-service-worker-scripts.en.md @@ -0,0 +1,105 @@ +# Custom service worker scripts + +While the Angular service worker provides excellent capabilities, you may need to add custom functionality such as handling push notifications, background sync, or other service worker events. You can create a custom service worker script that imports and extends the Angular service worker. + +## Creating a custom service worker + +To create a custom service worker that extends Angular's functionality: + +1. Create a custom service worker file (e.g., `custom-sw.js`) in your `src` directory: + +```js +// Import the Angular service worker +importScripts('./ngsw-worker.js'); + +(function () { + 'use strict'; + + // Add custom notification click handler + self.addEventListener('notificationclick', (event) => { + console.log('Custom notification click handler'); + console.log('Notification details:', event.notification); + + // Handle notification click - open URL if provided + if (clients.openWindow && event.notification.data.url) { + event.waitUntil(clients.openWindow(event.notification.data.url)); + console.log('Opening URL:', event.notification.data.url); + } + }); + + // Add custom background sync handler + self.addEventListener('sync', (event) => { + console.log('Custom background sync handler'); + + if (event.tag === 'background-sync') { + event.waitUntil(doBackgroundSync()); + } + }); + + function doBackgroundSync() { + // Implement your background sync logic here + return fetch('https://example.com/api/sync') + .then((response) => response.json()) + .then((data) => console.log('Background sync completed:', data)) + .catch((error) => console.error('Background sync failed:', error)); + } +})(); +``` + +2. Update your `angular.json` file to use the custom service worker: + +```json +{ + "projects": { + "your-app": { + "architect": { + "build": { + "options": { + "assets": [ + { + "glob": "**/*", + "input": "public" + }, + "app/src/custom-sw.js" + ] + } + } + } + } + } +} +``` + +3. Configure the service worker registration to use your custom script: + +```ts +import { ApplicationConfig, isDevMode } from '@angular/core'; +import { provideServiceWorker } from '@angular/service-worker'; + +export const appConfig: ApplicationConfig = { + providers: [ + provideServiceWorker('custom-sw.js', { + enabled: !isDevMode(), + registrationStrategy: 'registerWhenStable:30000', + }), + ], +}; +``` + +### Best practices for custom service workers + +When extending the Angular service worker: + +- **Always import the Angular service worker first** using `importScripts('./ngsw-worker.js')` to ensure you get all the caching and update functionality +- **Wrap your custom code in an IIFE** (Immediately Invoked Function Expression) to avoid polluting the global scope +- **Use `event.waitUntil()`** for asynchronous operations to ensure they complete before the service worker is terminated +- **Test thoroughly** in both development and production environments +- **Handle errors gracefully** to prevent your custom code from breaking the Angular service worker functionality + +### Common use cases + +Custom service workers are commonly used for: + +- **Push notifications**: Handle incoming push messages and display notifications +- **Background sync**: Sync data when the network connection is restored +- **Custom navigation**: Handle special routing or offline page scenarios diff --git a/adev-es/src/content/ecosystem/service-workers/custom-service-worker-scripts.md b/adev-es/src/content/ecosystem/service-workers/custom-service-worker-scripts.md index d5fdcaa..b967236 100644 --- a/adev-es/src/content/ecosystem/service-workers/custom-service-worker-scripts.md +++ b/adev-es/src/content/ecosystem/service-workers/custom-service-worker-scripts.md @@ -1,52 +1,52 @@ -# Custom service worker scripts +# Scripts personalizados de service worker -While the Angular service worker provides excellent capabilities, you may need to add custom functionality such as handling push notifications, background sync, or other service worker events. You can create a custom service worker script that imports and extends the Angular service worker. +Aunque el service worker de Angular ofrece excelentes capacidades, es posible que necesites agregar funcionalidad personalizada, como manejar notificaciones push, sincronización en segundo plano u otros eventos de service worker. Puedes crear un script de service worker personalizado que importe y amplíe el service worker de Angular. -## Creating a custom service worker +## Crear un service worker personalizado -To create a custom service worker that extends Angular's functionality: +Para crear un service worker personalizado que extienda la funcionalidad de Angular: -1. Create a custom service worker file (e.g., `custom-sw.js`) in your `src` directory: +1. Crea un archivo de service worker personalizado (por ejemplo, `custom-sw.js`) en tu directorio `src`: ```js -// Import the Angular service worker +// Importa el service worker de Angular importScripts('./ngsw-worker.js'); (function () { 'use strict'; - // Add custom notification click handler + // Agrega un manejador personalizado para el clic en notificaciones self.addEventListener('notificationclick', (event) => { - console.log('Custom notification click handler'); - console.log('Notification details:', event.notification); - - // Handle notification click - open URL if provided + console.log('Manejador personalizado de clic en notificaciones'); + console.log('Detalles de la notificación:', event.notification); + + // Gestiona el clic en la notificación: abre la URL si está disponible if (clients.openWindow && event.notification.data.url) { event.waitUntil(clients.openWindow(event.notification.data.url)); - console.log('Opening URL:', event.notification.data.url); + console.log('Abriendo URL:', event.notification.data.url); } }); - // Add custom background sync handler + // Agrega un manejador personalizado para sincronización en segundo plano self.addEventListener('sync', (event) => { - console.log('Custom background sync handler'); - + console.log('Manejador personalizado de sincronización en segundo plano'); + if (event.tag === 'background-sync') { event.waitUntil(doBackgroundSync()); } }); function doBackgroundSync() { - // Implement your background sync logic here + // Implementa aquí la lógica de sincronización en segundo plano return fetch('https://example.com/api/sync') - .then((response) => response.json()) - .then((data) => console.log('Background sync completed:', data)) - .catch((error) => console.error('Background sync failed:', error)); + .then(response => response.json()) + .then(data => console.log('Sincronización en segundo plano completa:', data)) + .catch(error => console.error('La sincronización en segundo plano falló:', error)); } })(); ``` -2. Update your `angular.json` file to use the custom service worker: +2. Actualiza tu archivo `angular.json` para usar el service worker personalizado: ```json { @@ -70,7 +70,7 @@ importScripts('./ngsw-worker.js'); } ``` -3. Configure the service worker registration to use your custom script: +3. Configura el registro del service worker para usar tu script personalizado: ```ts import { ApplicationConfig, isDevMode } from '@angular/core'; @@ -86,20 +86,20 @@ export const appConfig: ApplicationConfig = { }; ``` -### Best practices for custom service workers +### Mejores prácticas para service workers personalizados -When extending the Angular service worker: +Al extender el service worker de Angular: -- **Always import the Angular service worker first** using `importScripts('./ngsw-worker.js')` to ensure you get all the caching and update functionality -- **Wrap your custom code in an IIFE** (Immediately Invoked Function Expression) to avoid polluting the global scope -- **Use `event.waitUntil()`** for asynchronous operations to ensure they complete before the service worker is terminated -- **Test thoroughly** in both development and production environments -- **Handle errors gracefully** to prevent your custom code from breaking the Angular service worker functionality +- **Importa siempre primero el service worker de Angular** mediante `importScripts('./ngsw-worker.js')` para asegurarte de conservar toda la funcionalidad de caché y actualización. +- **Envuelve tu código personalizado en un IIFE** (Immediately Invoked Function Expression) para evitar contaminar el ámbito global. +- **Usa `event.waitUntil()`** en las operaciones asíncronas para garantizar que finalicen antes de que el service worker se termine. +- **Prueba exhaustivamente** en entornos de desarrollo y producción. +- **Maneja los errores con cuidado** para evitar que tu código personalizado rompa la funcionalidad del service worker de Angular. -### Common use cases +### Casos de uso comunes -Custom service workers are commonly used for: +Los service workers personalizados se utilizan con frecuencia para: -- **Push notifications**: Handle incoming push messages and display notifications -- **Background sync**: Sync data when the network connection is restored -- **Custom navigation**: Handle special routing or offline page scenarios +- **Notificaciones push**: manejar mensajes push entrantes y mostrar notificaciones +- **Sincronización en segundo plano**: sincronizar datos cuando se restablece la conexión de red +- **Navegación personalizada**: gestionar escenarios especiales de routing o páginas offline diff --git a/adev-es/src/content/ecosystem/service-workers/devops.en.md b/adev-es/src/content/ecosystem/service-workers/devops.en.md new file mode 100644 index 0000000..fb3b0ea --- /dev/null +++ b/adev-es/src/content/ecosystem/service-workers/devops.en.md @@ -0,0 +1,317 @@ +# Service worker devops + +This page is a reference for deploying and supporting production applications that use the Angular service worker. +It explains how the Angular service worker fits into the larger production environment, the service worker's behavior under various conditions, and available resources and fail-safes. + +## Service worker and caching of application resources + +Imagine the Angular service worker as a forward cache or a Content Delivery Network (CDN) edge that is installed in the end user's web browser. +The service worker responds to requests made by the Angular application for resources or data from a local cache, without needing to wait for the network. +Like any cache, it has rules for how content is expired and updated. + +### Application versions + +In the context of an Angular service worker, a "version" is a collection of resources that represent a specific build of the Angular application. +Whenever a new build of the application is deployed, the service worker treats that build as a new version of the application. +This is true even if only a single file is updated. +At any given time, the service worker might have multiple versions of the application in its cache and it might be serving them simultaneously. +For more information, see the [Application tabs](#application-tabs) section. + +To preserve application integrity, the Angular service worker groups all files into a version together. +The files grouped into a version usually include HTML, JS, and CSS files. +Grouping of these files is essential for integrity because HTML, JS, and CSS files frequently refer to each other and depend on specific content. +For example, an `index.html` file might have a `