Skip to main content
skill CX Codex

service-worker — Claude Code skill: what it does, how to install

service-worker guides the coding assistant in configuring Workbox v7.4 caching, offline app shells, background sync, and push notifications.

MIT 121 installs ★ 29 updated 2026-08-17

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add oakoss/agent-skills --skill service-worker -a claude-code
Open on GitHub

What service-worker does

The skill provides guidelines for handling service worker lifecycles and Workbox v7.4 packages. It covers precaching static app shells with workbox-precaching, cache expiration limits via workbox-expiration, and strategy selection: CacheFirst for static assets, NetworkFirst for live API data, and StaleWhileRevalidate for quick responses.

It details Push API configuration with VAPID keys, the Static Routing API introduced in Chrome 123+, and safe client updates through workbox-window. Background Sync lacks support in Safari and Firefox, making a navigator.onLine fallback mandatory for reliable offline form submissions.

What it helps with

  • configure Workbox v7.4 caching strategies for static assets and API routes
  • implement offline app shell caching with an offline.html fallback page
  • queue failed network requests using workbox-background-sync
  • integrate web push notifications using the Push API and VAPID keys

Example prompts for the agent

  • Configure a Workbox service worker using CacheFirst for assets and NetworkFirst for API endpoints
  • Set up offline request queueing with Background Sync and a fallback for Safari
  • Add precaching for the application shell and route navigation fallbacks to offline.html

How to install service-worker

1Skills CLI (Vercel)

npx skills add oakoss/agent-skills --skill service-worker -a claude-code

2Manually: put the files in place

~/.claude/skills/service-worker/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/service-worker/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about service-worker

How to install service-worker in Claude Code?

Run npx skills add oakoss/agent-skills --skill service-worker -a claude-code in your terminal.

What does the service-worker skill do?

It guides the agent in writing service worker code, covering Workbox v7.4 strategies, precache manifests, push notifications, and browser support checks.

Does Background Sync work across all browsers?

Background Sync is supported only in Chrome 49+ and Edge 79+. Because Firefox and Safari do not support it, the skill advises a navigator.onLine fallback.

Source text

SKILL.md · MIT
---
name: service-worker
description: |
  Service worker lifecycle, caching strategies, background sync, push notifications, and static routing for progressive web apps. Covers Workbox v7.4 strategies (CacheFirst, NetworkFirst, StaleWhileRevalidate), workbox-precaching for app shells, Background Sync API with cross-browser fallbacks, Push API with VAPID keys, and the Service Worker Static Routing API (Chrome 123+).

  Use when registering service workers, implementing offline caching, configuring background sync, adding push notifications, optimizing fetch handling with static routes, or integrating service workers with local-first sync engines.
license: MIT
metadata:
  author: oakoss
  version: '1.0'
user-invocable: false
---

# Service Worker

## Overview

Service workers are event-driven scripts that run in a separate thread from the main page, intercepting network requests, managing caches, and enabling offline functionality. Workbox v7.4 (maintained by the Chrome Aurora team) provides a production-ready abstraction over the low-level Cache API and fetch event handling.

**When to use:** Progressive web apps needing offline support, apps requiring push notifications, background data synchronization, app shell caching, network request optimization with static routing.

**When NOT to use:** Simple static sites served from a CDN, server-rendered apps with no offline requirements, apps where stale data is unacceptable (use network-only), prototypes where caching complexity is premature.

## Quick Reference

| Pattern                | API / Tool                           | Key Points                                          |
| ---------------------- | ------------------------------------ | --------------------------------------------------- |
| Registration           | `navigator.serviceWorker.register()` | Register in window context, scope defaults to path  |
| Precaching             | `workbox-precaching`                 | Revision-hashed app shell, injected at build time   |
| Cache-first            | `CacheFirst` strategy                | Static assets, fonts, images                        |
| Network-first          | `NetworkFirst` strategy              | API responses needing freshness                     |
| Stale-while-revalidate | `StaleWhileRevalidate` strategy      | Balance between speed and freshness                 |
| Background sync        | `workbox-background-sync`            | Replay failed requests when back online             |
| Push notifications     | Push API + Notifications API         | VAPID keys, server-sent push, offline-first display |
| Static routing         | `event.addRoutes()` in install       | Bypass fetch handler for known routes               |
| Skip waiting           | `self.skipWaiting()`                 | Activate new SW immediately, use with caution       |
| Clients claim          | `self.clients.claim()`               | Control existing tabs without reload                |
| Navigation preload     | `navigationPreload.enable()`         | Parallel network request during SW startup          |
| Update prompt          | `workbox-window` Workbox class       | Detect updates, prompt user, postMessage to SW      |
| Offline fallback       | `workbox-recipes` offlineFallback    | Serve fallback page when cache and network fail     |
| Cache expiration       | `workbox-expiration`                 | maxEntries and maxAgeSeconds per cache              |

## Browser Support Quick Reference

| Feature             | Chrome | Firefox | Safari | Edge |
| ------------------- | ------ | ------- | ------ | ---- |
| Service Workers     | 40+    | 44+     | 11.1+  | 17+  |
| Background Sync     | 49+    | No      | No     | 79+  |
| Periodic Sync       | 80+    | No      | No     | 80+  |
| Push API            | 50+    | 44+     | 16.4+  | 17+  |
| Navigation Preload  | 59+    | 99+     | 15.4+  | 18+  |
| Static Routing API  | 123+   | No      | No     | 123+ |
| Background Fetch    | 74+    | No      | No     | 79+  |
| Storage Persistence | 52+    | 55+     | 15.2+  | 79+  |

## Common Mistakes

| Mistake                                        | Correct Pattern                                                         |
| ---------------------------------------------- | ----------------------------------------------------------------------- |
| Caching API responses with CacheFirst          | Use NetworkFirst or StaleWhileRevalidate for dynamic data               |
| Calling skipWaiting unconditionally            | Prompt user before activating to avoid breaking in-flight navigations   |
| Not versioning precache manifests              | Use workbox-build or workbox-webpack-plugin to inject revision hashes   |
| Ignoring cache storage limits                  | Implement cache expiration with workbox-expiration plugin               |
| Using sync access handle in service worker     | OPFS createSyncAccessHandle is dedicated-worker only; use async methods |
| Assuming Background Sync works everywhere      | Chrome/Edge only (~80%); implement navigator.onLine fallback            |
| Caching opaque responses without size limits   | Opaque responses pad cache quota; limit with maxEntries                 |
| Not handling service worker update races       | Use workbox-window to coordinate update lifecycle with the page         |
| Registering SW before page load completes      | Register in window load event to avoid competing for bandwidth          |
| Letting sync engine data flow through SW cache | Let the sync engine handle data; SW handles app shell and static assets |
| Not cleaning up old caches on activate         | Delete outdated caches in activate event to free storage                |
| Missing offline fallback for navigations       | Precache an offline.html and serve it when network and cache both fail  |

## Workbox Package Reference

| Package                      | Purpose                                           |
| ---------------------------- | ------------------------------------------------- |
| `workbox-precaching`         | Build-time asset caching with revision management |
| `workbox-routing`            | URL pattern matching and strategy routing         |
| `workbox-strategies`         | CacheFirst, NetworkFirst, StaleWhileRevalidate    |
| `workbox-expiration`         | Cache size and age limits                         |
| `workbox-cacheable-response` | Filter responses by status or header              |
| `workbox-background-sync`    | Queue and replay failed requests                  |
| `workbox-window`             | Page-side registration and update management      |
| `workbox-recipes`            | Pre-built patterns (offline fallback, warm cache) |
| `workbox-build`              | Build tool for generating precache manifests      |
| `workbox-navigation-preload` | Enable navigation preload in activate             |

## Delegation

> If the `local-first` skill is available, delegate architecture decisions, sync engine selection, and offline data strategy to it.
> Otherwise, recommend: `pnpm dlx skills add oakoss/agent-skills -s local-first -a claude-code -y`
> If the `electricsql` skill is available, delegate sync engine patterns, shape subscriptions, and real-time data replication to it.
> Otherwise, recommend: `pnpm dlx skills add oakoss/agent-skills -s electricsql -a claude-code -y`

- **Caching strategy review**: Use `Task` agent to audit route-to-strategy mappings
- **Offline testing**: Use `Task` agent to simulate offline scenarios and verify fallback behavior
- **Push notification design**: Use `Plan` agent to design notification payload and action strategies

## References

- [Service worker lifecycle and update management](references/lifecycle.md)
- [Workbox caching strategies and precaching](references/caching-strategies.md)
- [Background sync with cross-browser fallbacks](references/background-sync.md)
- [Static Routing API for fetch handler bypass](references/static-routing.md)
- [Push notifications with VAPID and offline integration](references/push-notifications.md)
- [Local-first integration and storage patterns](references/local-first-patterns.md)

© oakoss · MIT · oakoss/agent-skills

Similar skills

All skills for Frontend and UI →

From the same set106

The whole set →
shell-integration The shell-integration Claude Code skill provides terminal integration guides and Bash, Zsh, and Fish patterns for completions, prompt hooks, and portable POSIX wrappers. CX Codex +1 123installs usability-tester usability-tester plans usability test sessions, evaluates interfaces against heuristic standards, and scores UX friction points using severity formulas. CX Codex +1 122installs react-email Build responsive HTML emails from React Email components and render them as HTML or plain text. Useful for transactional messages and marketing templates. CX Codex +1 122installs rag-implementer rag-implementer guides an agent through a retrieval-augmented generation build, from chunking and embeddings to hybrid retrieval and quality metrics. CX Codex +1 121installs cli-power-tools cli-power-tools guides coding agents to use fast Rust-based command-line utilities and structured parsers instead of legacy shell pipelines. CX Codex +1 121installs quality-auditor quality-auditor runs a weighted audit across 12 dimensions, scores each one against cited evidence and hands back a prioritized fix list. CX Codex +1 120installs package-publishing package-publishing guides npm package metadata, ESM and CJS builds, and TypeScript declarations. Useful when preparing a library’s public entry points or publishing workflow. CX Codex +1 119installs svelte A reference sheet that teaches a coding agent Svelte 5 runes and SvelteKit routing, plus a table for moving Svelte 4 code onto the new API. CX Codex +1 117installs

Project sponsors

Companies that keep this analytics open