Learn about our RFC process, Open RFC meetings & more.Join in the discussion! »


1.0.1 • Public • Published

Service Worker Includes

Service Worker Inlcudes (SWIs) are a pattern for improving cache performance and correctness of service workers by caching infrequently changed portions of an HTML document, like a site's global header or footer, separately from the frequently changing portions, like the content. They are based on Server Side Includes and currently supports the include directive and the virtual parameter, and requires the include be part of the Service Worker precache. SWIs work by removing the static-rendered includes in served HTML before it enters the user's cache, and replacing the includes with their content when the HTML is served from cache. This allows content and certain components to be cached separately, allowing only a portion of a page's cached content to need to be invalidated when things like global components change.

In order to use SWIs, you need to wrap the include's rendered HTML in a start include comment, <!--#include virtual="/path/from/root/to/component.txt"-->, and and end include comment <!--#endinclude-->. This can be done fairly easily in most templating languages, with the following demo done using Nunjucks' macro definitions. The navigation component (reproduced below from static site scaffold) does this to allow navigation to be included:

{% macro nav(locale, ssi = true) %} {% if ssi %}<!--#include virtual="/_components/{{locale}}/nav.txt"-->{% endif %}
    <li><a href="/{{locale}}">Home</a></li>
    <li><a href="/{{locale}}/typography">Typography</a></li>
{% if ssi %}<!--#endinclude-->{% endif %} {% endmacro %}

Then, use that macro as you normally would throughout your project. Remember to compile this template with ssi = false to /_components/{{locale}}/nav.txt and to precache it using your Service Worker in order to have it available to this script!


Service Worker Includes is designed to work with service workers built with Workbox 5.0.0-rc.1 or greater. To use it, import it and include it as a plugin in your Workbox strategy, for instance here with a Stale While Revalidate strategy:

import { StaleWhileRevalidate } from 'workbox-strategies';
import { CacheableResponsePlugin } from 'workbox-cacheable-response';
import { serviceWorkerIncludePlugin } from 'service-worker-includes';
import { registerRoute } from 'workbox-routing';
// Create a Stale While Revalidate strategy
const htmlCachingStrategy = new StaleWhileRevalidate({
  cacheName: 'pages-cache',
  plugins: [
    new CacheableResponsePlugin({
      statuses: [200, 301, 404],
// Use it for navigations
registerRoute(({ request }) => request.mode === 'navigate', htmlCachingStrategy);



npm i service-worker-includes

DownloadsWeekly Downloads






Unpacked Size

8.21 kB

Total Files


Last publish


  • avatar