Skip to main content

sw 0.3.0 copy "sw: ^0.3.0" to clipboard
sw: ^0.3.0 copied to clipboard

A command-line tool to generate service worker files for web applications. It simplifies the process of creating service workers.

0.3.0 — 2026-10-30 #

Fixed #

  • Docs: an app that does not declare Roboto lost all of its text when started without a network. Flutter's engine fetches that font from fonts.gstatic.com, which the worker cannot cache, while the layout, buttons and images stay in place. The README now says to declare it, and the example bundles it and pre-caches its fonts. Found on an iPad. (README.md, example/pubspec.yaml, .github/workflows/pages.yml)

  • Service Worker: the refill of an evicted Core or Required file did not retry a 5xx or 429, although this changelog and docs/service-worker.md said it did. One 503 on the hash-busted URL went straight to the plain fallback, and a second one reached the page. It now retries like precache before falling back. (packages/sw/src/sw/fetch-handler.ts)

  • Service Worker: a lazy cache write refused before reading the body (Vary: *, say) left its copy of the response buffering the body the page was reading, until the stall timeout cut it. The copy is now released. (packages/sw/src/sw/cache-manager.ts)

  • Service Worker: a file fetched on a cache miss was often not stored. The write cloned the response after an await, by which time the page could already be reading it, so the clone threw and the file stayed uncached until a later request happened to win the race. This hit lazily cached files and the self-healing refill of evicted ones. The clone now happens before the first await.

  • Bootstrap: flutter build web --no-web-resources-cdn was ignored. Flutter records that choice as "useLocalCanvasKit": true in _flutter.buildConfig, but the generator dropped it, and the bootstrap probed gstatic.com on every load and then loaded the engine from the CDN whenever it answered. The probe is a cache: "no-store" request, so it cost a network round trip on every load, returning visitors included, before the engine download could start, and up to two 8 s timeouts where gstatic.com is blocked or slow. The bundled canvaskit/ files the app chose to serve were never used, so the service worker never cached them either. The generator now passes useLocalCanvasKit through to the bootstrap config (only when true), and loadCanvasKit goes straight to the local directory for such builds; the variant in use is cached lazily on first load like any other Optional file. Builds without the flag behave as before. The generator's summary also reports which source the bootstrap will use. (lib/src/flutter_build.dart, lib/src/injector.dart, lib/src/generator.dart, packages/sw/src/bootstrap/canvaskit-loader.ts, packages/sw/src/bootstrap/pipeline.ts, packages/sw/src/shared/types.ts)

  • Generator: cleanup pruned canvaskit/chromium/canvaskit.js while keeping its .wasm. getCanvasKitVariant loads that pair on Chromium-class browsers with the canvaskit renderer; the missing half went unnoticed while the engine came from the CDN, but a --no-web-resources-cdn build loads it locally, where hosts with an SPA rewrite answer the missing script with index.html and the app never starts. The keep-set now lists both files. (lib/src/generator.dart)

  • Service Worker: files whose names contain a space or a non-ASCII character were never served from the cache. The manifest is keyed by the name on disk (assets/my photo.png), but the worker looked requests up by the percent-encoded URL path (assets/my%20photo.png). Core and Required files like that were precached and then fetched from the network anyway; Optional ones were never cached. Keys are now decoded with decodeURI, which leaves an escaped / escaped. (packages/sw/src/shared/utils.ts)

  • Service Worker: an HTML page answering a request for a script, wasm, image or JSON file was cached under that file's name. A host with an SPA rewrite (Firebase, Netlify, try_files … /index.html) answers a file the deploy lacks with the app shell and status 200, and cache-first then served it as that file until the next deploy. Precache now fails such an entry (for a Core file that fails the install, which is retried on the next load), and the lazy cache skips it. HTML files themselves are unaffected. (packages/sw/src/sw/cache-manager.ts, packages/sw/src/shared/utils.ts)

  • Bootstrap: recovering from a foreign service worker (the transition from Flutter's own) awaited getRegistrations() and unregister() with no deadline, before the pipeline's own budget applies. Those wait on the per-scope job queue that a stuck install wedges, so the page could hang before the loading widget appeared. The cleanup is now bounded by RESET_TIMEOUT_MS (3 s) and the reload is unconditional. (packages/sw/src/bootstrap/sw-registration.ts)

  • Bootstrap: Bootstrap.applyUpdate() could hang forever when the waiting worker turned redundant instead of activating, since controllerchange then never fires. It now resolves false at once when the worker turns redundant, or after SW_BOOTSTRAP_TIMEOUT_MS (10 s) when nothing lands, and leaves the page as it is. (packages/sw/src/bootstrap/sw-registration.ts)

  • Bootstrap: the flutter-first-frame listener that dismisses the loading widget was added only after the app loader resolved, so a first frame dispatched earlier left the widget up until Dart removed it. It is now registered before the app loads. (packages/sw/src/bootstrap/pipeline.ts)

  • Generator: keep-maps, no-cleanup and comments in sw.yaml were ignored, although docs/configuration.md documents them: the flags were read from the command line only. They now follow the same CLI > YAML > env precedence as every other option, with SW_KEEP_MAPS, SW_NO_CLEANUP and SW_COMMENTS as the environment variables. An invalid value exits with status 64, like an invalid number. (lib/src/config.dart)

  • Generator: cleanup deleted flutter_bootstrap.js even when index.html still loaded it, which happens when the step that swaps in an index.html loading bootstrap.js is skipped, and the deployed page was blank. The file is now kept in that case, with a warning that the page will not use bootstrap.js or the service worker. (lib/src/cleanup.dart)

  • Generator: bootstrap.js carried flutter.js's //# sourceMappingURL=flutter.js.map, which points at a map that is not deployed. The comment is stripped, and a ; now separates the loader from the bootstrap IIFE. (lib/src/generator.dart)

  • Docs: docs/configuration.md referred to a nonexistent --exclude flag (it is --no-glob) and gave the version default as a timestamp (it is a hash of the manifest).

  • Bootstrap: the first load after a deploy ran the previous build's Dart code on the new build's engine. The previous worker still controls that page and serves its cached main.dart.*, while index.html and bootstrap.js come from the new build and the bootstrap loads CanvasKit or skwasm for the new engine revision. On the same engine that mix works, but after a Flutter upgrade it fails in the engine (WebAssembly.instantiate(): Import #N). The worker now reports its build's engineRevision in its getVersion reply, and the bootstrap asks the controller for it. On the same engine the page boots with it at once, without the 4 s activation wait it used to spend for nothing; the new worker takes over on the next load. On a different engine, or an unknown one (workers from earlier releases don't report it, so the first load after upgrading waits once), the bootstrap waits up to SW_UPDATE_INSTALL_TIMEOUT_MS (60 s) for the new worker to install, hands control to it before any app file is requested, and reloads once if the handover is lost. A failed install leaves the page on its current controller, as before. (packages/sw/src/bootstrap/sw-registration.ts, packages/sw/src/bootstrap/pipeline.ts, packages/sw/src/sw/message-handler.ts, packages/sw/src/sw/index.ts, lib/src/injector.dart, lib/src/generator.dart)

  • Service Worker: activating one version deleted the temp cache of a version still installing beside it, which happens when the bootstrap hands control to a waiting worker while a newer deploy installs. That version then activated with an empty content cache. Cleanup now keeps the temp caches of the registration's installing and waiting workers; an abandoned install's leftovers still go. (packages/sw/src/sw/activate-handler.ts, packages/sw/src/sw/cache-manager.ts)

  • Service Worker: any failure during activate, including navigationPreload.enable() after a successful swap, deleted every cache whose name started with the prefix: this version's fresh content cache, a pending install's temp cache, and the caches of another app with a longer prefix. Swap, cleanup and navigation preload are now contained separately; a failed swap drops only this version's content and temp caches and clears the stored manifest, so it starts over from the network. Cleanup claims only this app's caches: prefix app-cache no longer claims app-cache2-…, nor app-cache-admin-… once that app's app-cache-admin-manifest cache exists (see the cache-ownership entry below). Apps sharing an origin still need distinct prefixes; two apps on the same prefix cannot be told apart. (packages/sw/src/sw/activate-handler.ts, packages/sw/src/sw/cache-manager.ts)

  • Service Worker: under a <base href> with a space or a non-ASCII character (/my%20app/), no key was re-based onto the scope, because request paths are now decoded and the scope was not. Every manifest lookup missed, the __/ pass-through stopped matching (/my%20app/__/auth/handler reached the app-shell branch), and activate deleted the freshly swapped Core and Required files whose hash changed. The scope path is decoded the same way. (packages/sw/src/shared/utils.ts)

  • Bootstrap: the version in sw.js?v= was not encoded, so a --version such as 1.0.0+3 read back as 1.0.0 3 in the worker, and activate deleted the temp cache of that pending version; & or # cut the version short. It is now encoded with encodeURIComponent; the default hash versions are unchanged. (packages/sw/src/bootstrap/sw-registration.ts)

  • Bootstrap: on an engine change the bootstrap reloaded a page that was already on the new worker, when another tab handed control over meanwhile or the controllerchange landed just after the 4 s handover timeout. It now checks the controller before reloading. (packages/sw/src/bootstrap/sw-registration.ts)

  • Generator: the ; between flutter.js and the bootstrap landed inside a trailing line comment of flutter.js, should a release end it with one other than the stripped source-map comment; it now goes on a line of its own. (lib/src/generator.dart)

  • Generator: cleanup kept flutter_bootstrap.js and warned that the page would not use the service worker for a commented-out script tag, a data-src attribute, or a file merely ending in that name (my_flutter_bootstrap.js, flutter_bootstrap.json). (lib/src/cleanup.dart)

  • CI: the check that nothing secret reaches pub.dev ran on the setup action's sparse checkout, which lacks .pubignore, and before the tests create coverage/ and reports/; the dry run itself failed on the missing LICENSE, and || true hid it. It now runs last, on the whole tree, and fails when the dry run fails. (.github/workflows/checkout.yml)

  • Docs: the --version default (a hash of the manifest, not a timestamp), CanvasKit listed as Core (it is Optional), index.html missing from Required, the full list of environment variables, engineRevision in SWConfig, and --comments, which is accepted but has no effect yet.

  • Docs: the README promised a "pre-cached shell for offline". The app cannot start offline: the shell loads bootstrap.js, which is never cached so that shell, bootstrap and worker always come from one deploy. The docs now say so, and say why it stays that way.

Audit findings from #30:

  • Service Worker: a body cut short in transit (a chunked response closed early, a truncating proxy) was cached and then served cache-first until the next deploy, breaking the app for that user only. Pre-cached and lazily cached bodies are now counted against the manifest's size while they stream into the cache (nothing is buffered), and a mismatch stores nothing; the log names the key and both sizes. index.html is exempt. A declared Content-Length never replaces the manifest's size. Precache fetches a mismatched entry once more and stores the second copy, with a warning, when it has the build's size, or when the host re-encodes the response (Content-Encoding other than identity, as a minifier or an injected snippet does) and the length repeats (or both copies are longer); an uncompressed body of the wrong size, an empty body for a non-empty file, a length that changes, or a second copy short of its own Content-Length fails the entry. (packages/sw/src/shared/utils.ts, packages/sw/src/sw/cache-manager.ts)

  • Service Worker: a Range request (media seeking) was answered from the cache with the whole file, and a 206 slice could be cached as the whole file. Range requests now go to the network, and only a plain 200 is cached lazily. (packages/sw/src/sw/fetch-handler.ts, packages/sw/src/sw/cache-manager.ts)

  • Service Worker: a transient 503 or 429 for a Core file failed the install. Precache and the refill of a missing Core or Required entry retry 5xx and 429, honouring a numeric Retry-After capped at 5 s; a 4xx is final, and navigations are unchanged. The refill now fetches the hash-busted URL with cache: 'reload', so it cannot be answered by a stale HTTP cache entry, and falls back once to the page's own request. (packages/sw/src/shared/utils.ts, packages/sw/src/sw/fetch-handler.ts)

  • Service Worker: an abandoned install (tab closed mid-precache, a waiting worker superseded by a newer deploy) left its full temp cache behind until some later activate. Each install now removes temp caches of its prefix that no installing, waiting or active worker of the registration owns, and keeps all of them when the waiting worker's version cannot be read. A QuotaExceededError is logged with the storage estimate. (packages/sw/src/sw/install-handler.ts, packages/sw/src/sw/cache-manager.ts, packages/sw/src/sw/quota.ts)

  • Bootstrap: an engine loaded from the CDN passed a one-byte probe of its .js, which says nothing about the .wasm; a proxy that blocks the .wasm left the app on an error. A failure of the app that involves the CDN engine (see the CDN fallback entry below) now pins the tab session to the local engine and reloads once (only when sessionStorage can record that, so it cannot loop); a missing _flutter.loader, which no engine fixes, is shown at once. A failed CDN probe is remembered for the session, so later loads skip up to two 8 s timeouts. (packages/sw/src/bootstrap/canvaskit-loader.ts, packages/sw/src/bootstrap/pipeline.ts, packages/sw/src/bootstrap/flutter-loader.ts)

  • Bootstrap: a failure in initializeEngine() never reached the pipeline, because flutter.js does not await onEntrypointLoaded, so the splash stayed up with no error; and a loading widget that failed to mount threw out of the pipeline, so the app never started. Both are handled now. (packages/sw/src/bootstrap/flutter-loader.ts, packages/sw/src/bootstrap/pipeline.ts, packages/sw/src/bootstrap/api.ts)

  • Bootstrap: the reset button deleted every cache on the origin, including other apps'. It now deletes only this build's caches, by the worker's ownership rule: {prefix}-… for this build's prefix (passed in the bootstrap config as cachePrefix), minus the caches of an app whose prefix extends it (see the cache-ownership entry below); without a prefix it deletes all, as before. (packages/sw/src/bootstrap/loading-widget.ts, lib/src/injector.dart)

  • Bootstrap: loading widget fixes: the icon is built without innerHTML (Trusted Types), the <style> carries the page's CSP nonce, a bubbling child transitionend no longer removes the widget early, pointer-events is restored to its original value, the progress ring is an ARIA progressbar, the status is a polite live region (an alert on error) that is not rewritten with the same text, long status lines wrap, and reduced motion turns off every animation. (packages/sw/src/bootstrap/loading-widget.ts, packages/sw/src/bootstrap/config.ts)

  • Generator: running it twice over the same output failed with flutter_bootstrap.js not found; it now says the build was already processed and to re-run flutter build web. Unknown keys in sw.yaml (with a suggestion), keys with no value, a missing explicit --config, an unknown theme, a non-hex color, a progress value outside 0..100, min-progress above max-progress, an unknown renderer, symlinks in the build, and *.part.js files left in Ignore now print a warning; none of them changes the output. (lib/src/config.dart, lib/src/generator.dart, lib/src/files.dart)

  • Generator: ignored files were hashed for nothing, and every hash read the whole file into memory; MD5 is now streamed and computed for manifest entries only. Hashes and the default version are unchanged. Canvaskit pruning no longer follows symlinks. (An output name with a directory, --output=js/sw.js, is now rejected with status 64; see below.) (lib/src/manifest.dart, lib/src/files.dart, lib/src/generator.dart, lib/src/cleanup.dart)

  • Docs: the README advised long-lived caching for files other than sw.js, bootstrap.js and index.html. Flutter's file names carry no hash, so main.dart.js cached for a year outlives a deploy; the examples now send no-cache for everything (the worker still serves Core and Required files from its own cache). A section on application/wasm and cross-origin isolation was added.

  • CI: the publish workflow only checked the embedded assets before publishing; it now also type-checks and tests the TypeScript and analyzes and tests the Dart package, with read-only permissions for that job. (.github/workflows/deploy.yml)

  • Service Worker: a cache-first miss made the page wait for the cache write. cacheFirst awaited lazyCacheResponse (a cache.put of a clone) before handing the response to respondWith, and the lazy guard had no stall timeout. Refilling an evicted Core or Required file (say main.dart.wasm) from a body that stalled hung the request for good; on a healthy transfer the page still waited for the whole download plus the store, while the tee buffered every byte it hadn't read yet. The response is now returned as soon as its headers arrive, and the write runs beside it under event.waitUntil, cut off after BODY_STALL_TIMEOUT_MS (30 s) of silence. The app-shell refresh on a navigation had the same pattern and is fixed the same way. (packages/sw/src/sw/fetch-handler.ts, packages/sw/src/sw/cache-manager.ts)

  • Service Worker: the body size check stored the wrong files. An uncompressed response that declared a Content-Length other than the manifest's size was checked against the declared length. So a CDN that ignores the ?v= query (CloudFront's default cache key) could serve the previous build's file whole, with that file's length, and it was pinned under the new version until the next deploy. The second precache fetch accepted any length that repeated, so a deterministic truncation (the same short body twice) was stored too, and so were two empty 200 bodies for a non-empty file. A size other than the manifest's is now accepted only when the host re-encodes the response (Content-Encoding present and not identity) and the length repeats on the second fetch: that is the rewriting host the tolerance was meant for (a minifier, an injected snippet). An uncompressed body of the wrong size, or an empty body for a non-empty file, always fails. A 204 (ok, no body) on precache now counts as a size mismatch and gets the same second look; before, the guard's error was thrown outside the step that handles a mismatch. index.html stays exempt. (packages/sw/src/shared/utils.ts, packages/sw/src/sw/cache-manager.ts)

  • Service Worker / Bootstrap: cleanup and the reset button still deleted the caches of another app whose prefix extends ours. Matching on {prefix}- meant prefix app-cache claimed every cache of an app with prefix app-cache-admin, including the temp cache its install was still writing. Both now use one rule, ownCacheNames: a cache is ours if it starts with {prefix}- and is not shadowed. Any X-manifest cache where X starts with {prefix}- marks X as another app's prefix in use, and every name under X- is left alone. To make that marker reliable, install opens the manifest cache before it creates its temp cache. A failed swap now clears the stored manifest instead of deleting the manifest cache, and a version whose content cache name collides with the manifest cache never deletes it. Caches of earlier workers of the same app (0.2.0 used the same names) are still cleaned. An app on an older release is protected from its first activate on, once its manifest cache exists. The orphaned-temp cleanup also keeps the content cache of a kept version whose name has the temp shape (a version starting with temp-). (packages/sw/src/shared/cache-ownership.ts, packages/sw/src/sw/cache-manager.ts, packages/sw/src/sw/install-handler.ts, packages/sw/src/sw/activate-handler.ts, packages/sw/src/bootstrap/loading-widget.ts)

  • Service Worker: activate deleted the temp cache of a worker still installing. Install keeps every temp cache when the waiting worker's ?v= can't be read, but activate skipped unreadable pending workers and deleted their temp caches in the middle of their install. Activate also read the registration before listing caches, so a worker that started installing in between had its fresh temp cache listed but not kept. Activate now keeps every temp cache when an installing or waiting worker's version can't be read, and reads the registration after the cache listing. (packages/sw/src/sw/activate-handler.ts, packages/sw/src/sw/registration.ts, packages/sw/src/sw/cache-manager.ts)

  • Bootstrap: when the engine came from the CDN, any failure of the app reloaded the page onto the local engine, not only one caused by the engine: a main.dart.js 404 in a deploy race, a network blip, or an engine/app mismatch (WebAssembly.instantiate(): Import #N) did too. Offline, that reload landed on a blank page, since bootstrap.js is never cached, instead of the error screen and its reset button. The fallback now runs only when the failure involves the CDN engine: the error names a URL under the CDN base, or names no URL and a one-byte no-store probe of the CDN engine's .wasm fails. An error naming any other URL (the app's main.dart.js / .mjs, including flutter.js's script error event) shows the error. It never runs while navigator.onLine is false, nor when a probe of the local engine shows the origin unreachable as well. (packages/sw/src/bootstrap/canvaskit-loader.ts, packages/sw/src/bootstrap/pipeline.ts)

  • Bootstrap: on an engine change, a page whose new worker was activated by another tab while it waited for the install reloaded, although that worker was about to claim it: with nothing left in waiting, the handover returned false at once. When the pending worker is activating or activated, the bootstrap now waits up to SW_REGISTRATION_TIMEOUT_MS (4 s) for the page's controller to change and boots on it; it reloads once only if the claim never lands. (packages/sw/src/bootstrap/sw-registration.ts)

  • Bootstrap: the one-shot engine-update reload guard stayed set after a load that found a newer worker on the same engine, so a later engine-changing deploy in the same tab got no reload and booted the previous build's Dart code on the new engine. The guard is now cleared on every path where the page boots on one build: same engine, a handover that lands, and nothing pending. (packages/sw/src/bootstrap/sw-registration.ts)

  • Bootstrap: a build config without an engineRevision silently sent every update down the slow unknown-engine path (waiting up to 60 s for the new worker to install). The bootstrap now logs one console.warn per load naming the cause. (packages/sw/src/bootstrap/sw-registration.ts)

  • Bootstrap: the wait for a new engine's worker to install (up to 60 s, plus the 4 s handover) runs outside the 10 s registration cap, and a large precache on a slow link sends no sw-progress until a resource completes. After 30 s the loading widget declared a stall and showed its reset button, whose reset unregistered the very worker being waited for. The wait is bounded on its own, so it now reports itself to the widget as an "Installing update" step at its start and every 10 s until it ends; stall detection resumes afterwards. (packages/sw/src/bootstrap/sw-registration.ts, packages/sw/src/bootstrap/pipeline.ts)

  • Bootstrap: Bootstrap.applyUpdate() resolved false and did not reload after a hard reload, although the waiting worker activated: such a page has no controller, clients.claim() does not take it, and controllerchange never fires. It now also resolves true (and reloads, by default) when the waiting worker reaches activated, and resolves false at once when it turns redundant instead of after the 10 s timeout. (packages/sw/src/bootstrap/sw-registration.ts)

  • Bootstrap: controllerchange and statechange listeners outlived the waits that added them (the bootstrap handover, applyUpdate(), the first-install activation wait), and the handover's 4 s timer kept running after a successful handover. Every such wait now removes its listener and clears its timer whichever way it ends. (packages/sw/src/bootstrap/sw-registration.ts)

  • Generator: an output name with a directory part (--output=js/sw.js, or the same in sw.yaml or SW_OUTPUT) created the directory and wrote the worker there. Its default scope is then /js/, so it never controlled the page and nothing reported it. ../sw.js and absolute names wrote outside the build, and the bootstrap still registered them. --output and --bootstrap-output now have to be plain file names: a /, \, .., a drive or absolute path, an empty name, or the same name for both exits with status 64 and says why. The generator no longer creates directories. generate() runs the same checks for configurations built in code. (lib/src/config.dart, lib/src/generator.dart)

  • Generator: YAML values went through toString(). glob: ["**.js", "assets/**"] became the single glob [**.js, assets/**], a character class, so the manifest was nearly empty and nothing warned about it. glob, no-glob, core, required, optional and ignore now accept a YAML list, joined with ; like the CLI and environment forms. A mapping, a nested list, an empty item, or a list for a single-value option exits with status 64 and names the key and file. Plain scalars keep the text the user wrote, so version: 1.10 stays 1.10 instead of becoming 1.1, and title: 0x1F stays 0x1F instead of becoming 31. Quoted and block scalars are used as written. (lib/src/config.dart)

  • Generator: index.html was stamped with the version before the flutter.js and "already processed" checks ran and before the outputs were written. If a later step failed, the shell was left stamped. A re-run then hashed the changed shell, derived a different version, and had no placeholder left to stamp. Every check that can fail now runs first. The shell is stamped in memory, its manifest entry is taken from the stamped bytes, and it is written after sw.js and bootstrap.js. A failed run leaves index.html byte-identical and can be repeated as is. (lib/src/generator.dart, lib/src/cleanup.dart)

  • Generator: an invalid glob (--core='[') threw from inside generate() and was reported as a crash, with a stack trace and exit status 1. Globs from the CLI, YAML and the environment are now compiled while the configuration is parsed. A bad one exits with status 64 and names the option and the pattern. (lib/src/config.dart)

  • Generator: a shell built with <script>{{flutter_bootstrap_js}}</script> gets Flutter's whole loader pasted in. It boots the app without bootstrap.js or the service worker, and nothing said so: only <script src=…> tags were detected. Cleanup now recognises an inline script that sets _flutter.buildConfig or calls _flutter.loader.load(, and warns the user to replace it in web/index.html with the bootstrap script tag. The shell is not rewritten. An inline script that injects flutter_bootstrap.js itself now keeps that file, like a script tag does. Both warnings name the configured bootstrap file. (lib/src/cleanup.dart, lib/src/generator.dart)

  • Generator: the version was written into index.html unescaped, so a supplied --version containing " or < could break out of the attribute or element around {{sw_version}}. It is now HTML-escaped (&, <, >, ", '). Generated versions are hex digests and come out unchanged. The new stampIndexHtmlVersion() does the substitution, and applyIndexHtmlVersion() uses it. (lib/src/cleanup.dart)

  • Generator: an invalid integer was always reported as the CLI flag, even when it came from sw.yaml or the environment. Integer and boolean errors now name their source: --max-progress="lots", SW_MIN_PROGRESS="ten" (environment), or max-progress="lots" (in sw.yaml). (lib/src/config.dart)

  • Generator: some versions collided with the worker's cache names ({prefix}-{version}, {prefix}-temp-{version}, {prefix}-manifest):

    • manifest made the content cache the manifest cache.
    • A version starting with temp- looked like the install cache of another version, which can be deleted as one.
    • A version ending in -manifest looked like another app's manifest marker under the new cache-ownership rule, so that content cache would never be cleaned up.

    All three now exit with status 64 and an explanation. (lib/src/config.dart)

  • CI: the publish workflow published without the leak check: dart pub publish --dry-run, which shows what reaches pub.dev, ran only in the checkout workflow. deploy.yml now runs it before publishing. The checkout workflow's paths filters missed files that change the package or its tests, so edits to them skipped CI; they now cover .pubignore, dart_test.yaml, package-lock.json, packages/sw/package.json, packages/sw/*.ts, packages/sw/tsconfig.json, packages/sw/e2e/** and example/**. (.github/workflows/deploy.yml, .github/workflows/checkout.yml)

  • Docs: the nginx and Apache examples served .mjs without a JavaScript MIME type, which the wasm build's module loader rejects (strict MIME check); both now map it to text/javascript. The README's install snippets pin ^0.2.0 instead of the old 0.1.6-dev.

Changed #

  • Generator: a command-line usage error (unknown option, missing or disallowed value) exits with status 64 (EX_USAGE) and prints Error: with a --help hint, instead of status 1 with a stack trace. A broken input directory prints Error: and exits 1 without a stack trace.
  • Generator: a Flutter build without engineRevision in its buildConfig used to fail with an error. The bootstrap and the worker already handle a missing revision, so the generator now continues with a warning. Every deploy will take the slow update path (the page waits for the new worker to install and take over before the app starts), and CanvasKit loads from the local canvaskit/ directory, never the CDN. The summary prints Engine: (unknown). (lib/src/generator.dart)
  • Generator: configuration errors are now thrown from GeneratorConfig.parse as FormatException instead of calling exit(64). The CLI still exits with status 64, now with the --help hint. The new GeneratorConfig.validate() checks output names and the version for configurations built in code. (lib/src/config.dart)
  • Generator: corrected the comment on the default Required patterns. Pre-caching index.html puts the shell in the progress-counted set and answers a failed navigation. It does not make the app start offline, because bootstrap.js is never cached. (lib/src/categorizer.dart)

Tests #

  • Vitest: keys under a percent-encoded scope; the version round trip through sw.js?v=; no reload when the page is already on the new worker; activate with a failing cleanup, a waiting worker and an unparsable pending URL; fetch with an unusable CacheStorage; settle with blocked storage, foreign replies, a throwing postMessage and bounded waits; the window.Bootstrap API, applyUpdate, engine detection, the bootstrap entry point. Line coverage of packages/sw/src is now 99%, except sw/index.ts, which only runs once the Dart injector has filled in its config.

  • Dart: the CLI in a child process (exit codes 0, 1 and 64, env vs CLI vs YAML), every flag from YAML, script tags that do and do not load flutter_bootstrap.js, the generator's failure modes, skwasm keep-set, injection round trip of quotes, </script>, $& and U+2028.

  • Vitest: activate keeps the temp cache of a worker installing beside it and drops an abandoned one; keeps the swapped content cache when navigation preload fails; on a failed swap drops only its own caches; cleanupOldCaches keeps pending versions' temp caches and does not claim a longer prefix. Each fails without the fix.

  • Playwright: engine-update.spec.ts deploys the example twice over a local host, with a marker in main.dart.js and that file's size and MD5 updated in the worker's manifest, since the worker refuses a body the manifest does not describe. When the engine changed, the first load after the second deploy runs the new build's code; it ran the old build's without the fix. On the same engine it boots with the old build at once and reaches the new one on a later load.

  • Vitest: settleUpdateAtBootstrap boots at once on the same engine; waits for the install and hands over on a different engine, on a worker that does not report its engine, and on one that does not answer; stays on the current worker when the install fails or runs out of time; reloads once when the handover is lost and not again; skips a second handover when one already failed. registerServiceWorker no longer waits for a worker that cannot activate on a controlled page; the pipeline stops when the page reloads; getVersion reports the engine revision.

  • Dart: injectSWConfig carries the engine revision only when the build has one.

  • Vitest: getResourceKey decodes percent-escapes, keeps an escaped / and a malformed escape as sent; a file with a space in its name is served from the cache; precache fails a Core entry answered with HTML but still precaches index.html; the lazy cache skips an HTML fallback; the foreign-controller recovery reloads when unregister() never settles; activateWaitingSW resolves false when the controller never changes; a first frame dispatched while the app loader is still running dismisses the widget. Each fails without its fix.

  • Dart: YAML sets keep-maps, no-cleanup and comments, and the CLI wins over YAML in both directions; cleanup keeps flutter_bootstrap.js while index.html loads it and removes it once it loads bootstrap.js; bootstrap.js embeds flutter.js without its source-map comment.

  • Vitest: loadCanvasKit returns the local path without any fetch when useLocalCanvasKit is set; the pipeline passes useLocalCanvasKit to it, and false when the config omits it. All three fail without the fix.

  • Dart: extractFlutterBuildInfo reads useLocalCanvasKit and defaults it to false; injectBootstrapConfig emits it only when true; the integration build checks that bootstrap.js carries whatever the example's flutter_bootstrap.js recorded, so it holds for builds with and without --no-web-resources-cdn.

  • Dart: generate() over a synthetic canvaskit build keeps both files of the standard and Chromium variants and prunes a file no variant uses; it fails without the keep-set fix.

  • Playwright: the suite passes against the example built both with and without --no-web-resources-cdn. With the local build and the keep-set unfixed, "page loads without errors" and the wedged-queue test fail on the missing chromium/canvaskit.js.

  • For #30, each fix above has a test that fails without it, among them: a body short of the manifest size or longer; the same wrong length twice, stored only when re-encoded; a second copy short of its own Content-Length; a mismatch logged when cache.put rejects with a generic error; Range pass-through; 5xx/429 retry and Retry-After; orphaned temp caches kept for installing, waiting and active workers; the CDN fallback reload, and none for a missing Flutter loader; a reset that keeps another prefix's caches; the CLI exit codes and warnings; streamed MD5 equal to the old digest.

  • Vitest: a Core refill and a shell navigation answer before their stalled body is stored, and the background write gives up after the stall timeout; lazyCacheResponse fails a stalled body. All three fail without the fix (the first two hang).

  • Vitest: precache fails a body served whole at another length (a CDN ignoring ?v=), the same short length twice uncompressed, a longer uncompressed body, two empty 200s, and a 204. It still stores a re-encoded body that repeats a short or longer length, and fails a re-encoded body that changes length or comes back empty. The lazy cache refuses a body whose declared length differs from the manifest and an empty or null body; guardBody checks against the manifest whatever Content-Length says. Tests that encoded the old "declared length wins" and "same length twice is the host" rules were changed to the new rule. Each fails without the fix.

  • Vitest: ownCacheNames claims this prefix's three shapes and older workers' caches but nothing under a longer in-use prefix. cleanupOldCaches, cleanupOrphanedTempCaches, activate and the reset button leave app-cache-admin's caches, its in-flight temp cache included, alone. Install opens the manifest cache before its temp cache; a failed swap keeps the emptied manifest cache; a kept temp-… version keeps its content cache. Each fails without the fix.

  • Vitest: activate keeps every temp cache when an installing or waiting worker has no readable version, and keeps the temp cache of a worker that started installing between the registration read and the cache listing. Both fail without the fix.

  • Vitest: the pipeline's CDN fallback through the real classifier: a CDN engine .wasm that cannot be fetched reloads once; an error naming a CDN file reloads; main.dart.js failing (a script error event), main.dart.mjs failing, and an Import #N mismatch on a healthy CDN show the error without a fallback; offline and an unreachable origin do not reload; a local build makes no probe. isCdnEngineFailure reads a wrapped error's cause, probes with a no-store Range request, and treats a refused connection as unreachable. The no-fallback cases (main.dart.js, main.dart.mjs, mismatch, offline, unreachable origin) and the .wasm probe check fail without the fix.

  • Vitest: settleUpdateAtBootstrap waits for the claim of a worker activated by another tab instead of reloading, and reloads once when it never comes; clears the reload guard on the same engine; warns once when engineRevision is empty; calls its keep-alive at the start of the wait and at least every 10 s, and stops when the wait ends; the pipeline turns it into an "Installing update" progress beat. applyUpdate() reloads when the waiting worker activates without a controllerchange, answers false at once for a redundant worker, and leaves no listener behind; the bootstrap handover clears its timer on success and removes its listener on timeout; the activation wait removes its listener both ways. All fail without the fix.

  • Dart: the output-name, YAML, stamping, glob, inline-loader, escaping, error-source, version and engineRevision items above have tests that fail on the code before the fix. They cover:

    • Output names with /, \, .., ., absolute and drive paths, empty names and duplicates, from the CLI, YAML, the environment and generate(). Nothing is created under js/, and index.html stays byte-identical.
    • YAML lists for all six glob options; mappings, nested lists, empty items, and lists for single-value options rejected; version: 1.10, 0x1F, 1e3 and 010.png kept verbatim; quoted and block scalars.
    • A run that fails on a missing flutter.js leaves index.html byte-identical, and a repeat derives the same version as a fresh build.
    • Invalid globs for every glob option, from the CLI, YAML and the environment.
    • The inlined-loader warning, a bare _flutter.loader.load() call, a script that injects flutter_bootstrap.js, a commented-out loader, and an unrelated inline script.
    • HTML escaping in text and both attribute quote styles, through both stampIndexHtmlVersion and generate(). The shell's manifest hash still matches the bytes shipped.
    • Integer and boolean errors naming the environment variable and the YAML key and file.
    • Versions manifest, temp-… and …-manifest rejected; manifest-2, v-temp-1 and v1manifest accepted.
    • The missing-engineRevision warning, and no warning when the revision is present.

    The CLI cases run in a child process and check for exit status 64, no stack trace, and no file written.

  • Dart: the file-system-error CLI test now uses an output name that is taken by a directory. The old main.dart.js/sw.js is rejected as a usage error now.

  • Playwright: every browser test now runs on Chromium, Firefox and WebKit, in CI too, against a host that records requests, injects faults and really goes down: origin faults, fetch routing and storage purges. Fixed sleeps are gone. Assertions that could not fail were replaced: a failed deploy now waits for the new worker to meet the fault, a Range request is checked with the file already cached, a refill is compared with the whole precache list, and Firefox's refused navigation is pinned by its error instead of a blanket expected failure. docs/testing.md describes the levels and the known engine differences.

  • Vitest: the refill retries a 5xx or 429 by hash, then takes one plain attempt; a lazy write refused before reading releases its copy; a page reading its copy before the write starts still gets the file stored.

  • CI: npm run lint works (it had no ESLint config) and runs in the TypeScript job, over src and e2e; npm run check also type-checks e2e.

  • Totals: Vitest 539, Dart 238 unit and 14 integration, Playwright 35 on each of 3 engines (one skipped on WebKit) against the regenerated example; tsc, ESLint and dart analyze are clean.

0.2.0 — 2026-09-16 #

Fixed #

  • Bootstrap: the pipeline could wait on navigator.serviceWorker.register() forever, leaving the app stuck at 2% Registering service worker — through reloads, through restarts, with no error and no way out. Service worker jobs are serialised per scope, so an install that never settles blocks every later register(), unregister() and getRegistrations() on the origin until the browser kills the install minutes later. The whole service-worker step is now bounded by SW_BOOTSTRAP_TIMEOUT_MS (10s) and the app boots uncached when it runs out; the abandoned registration is left running, so the worker still installs in the background once the browser frees the queue. The deadline covers the pre-registration cleanup too, which goes through the same queue. (packages/sw/src/bootstrap/sw-registration.ts, packages/sw/src/shared/utils.ts)
  • Service Worker: a pre-cached response body that stalled mid-stream hung install indefinitely — the mechanism that wedges the queue above. fetchWithRetry bounds the headers only: its abort timer is cleared as soon as they arrive, after which cache.put reads a multi-megabyte body (main.dart.js is routinely ~10 MB) with no deadline at all. Bodies are now wrapped in an idle watchdog (BODY_STALL_TIMEOUT_MS, 30s) that cancels a stream which has stopped producing bytes. Measured against idle time, not total duration, so a slow-but-alive connection still finishes however long it takes; a genuinely dead stream fails one entry, and the install is retried on the next page load instead of blocking the origin. (packages/sw/src/sw/cache-manager.ts, packages/sw/src/shared/utils.ts)
  • Bootstrap: the loading widget's reset button hung in exactly the situation it exists for. It awaited unregister() before reloading, and unregister() is one of the calls a wedged job queue never settles — so the button spun forever on the stalled screen the user clicked it to escape. Cleanup is now bounded by RESET_TIMEOUT_MS (3s) and the reload is unconditional. (packages/sw/src/bootstrap/loading-widget.ts)

Changed #

  • Bootstrap: the reset button no longer clears localStorage/sessionStorage. On Flutter web shared_preferences is localStorage, so clearing it signs the user out and discards local app state — not something a reload button should do, and unrelated to a stuck cache. It still drops every cache, and it now clears only the one-shot foreign-controller guard key rather than all of session storage. (packages/sw/src/bootstrap/loading-widget.ts)
  • Bootstrap: the reset button unregisters only the service worker this bootstrap registered, matched on path. Unregistering everything also took out workers at unrelated scopes — firebase-messaging-sw.js and its push subscription, for instance — which reloadIfForeignController has always been careful to spare. LoadingWidget takes the SW filename for this; constructed without one, it falls back to the previous behaviour. (packages/sw/src/bootstrap/loading-widget.ts, packages/sw/src/bootstrap/pipeline.ts)

Tests #

  • Vitest: registerServiceWorker returns null and lets the pipeline continue when register() never settles, and when the pre-registration cleanup never settles. Both hang without the fix.
  • Vitest: a Core entry whose body stalls fails the install instead of hanging it — asserted through a cache that actually consumes the body, since the shared mock only clones it.
  • Vitest: the reset action reloads despite an unregister() that never settles, clears caches, spares unrelated registrations, leaves application storage alone, and re-arms the foreign-controller guard.
  • Vitest: withTimeout resolution, fallback and rejection propagation; guardBodyStall pass-through rules, an intact slow stream, and a stalled one.
  • Playwright: with the scope's job queue deliberately wedged by a worker whose install never settles, the app still reaches its first frame.

0.1.6-dev — 2026-09-02 #

Fixed #

  • Progress counter: the loading overlay could print a count greater than its own total (Loaded 5 of 4 resources). The numerator and the denominator were computed from two different sets: resourcesCount covered the pre-cached set (Core + Required), while the client counted every resource the SW reported — including Optional files served lazily by the fetch handler, which is unbounded. Progress messages now carry counted, marking membership of the set resourcesCount describes, and the bootstrap only adds counted resources to the numerator. (packages/sw/src/sw/progress.ts, packages/sw/src/bootstrap/pipeline.ts)

  • Progress counter: a page can be talked to by two workers at once — an old controller still serving fetches while a new build pre-caches in the background — and their manifests need not agree on a total. Messages now carry swVersion, and the bootstrap ignores any worker other than the one it was built against, so the denominator cannot change mid-load. (packages/sw/src/sw/progress.ts, packages/sw/src/bootstrap/pipeline.ts)

  • App shell: index.html was categorised ignore, so it never reached the manifest. The fetch handler's manifest['index.html'] lookups were consequently always empty: the shell was neither pre-cached nor reported as progress, and an offline navigation had nothing to fall back to on a cold profile. It is now required — pre-cached on install, counted, and stored under one canonical index.html cache key that both the precache and the navigation handler use. (lib/src/categorizer.dart, packages/sw/src/sw/fetch-handler.ts)

  • App shell: navigations to SPA deep links (/chat/42) were dropped by the fetch handler. The manifest lookup ran first and returned early for any route without an entry of its own, so the request.mode === 'navigate' branch below it was unreachable for exactly the routes that need it. The navigation check now runs first. (packages/sw/src/sw/fetch-handler.ts)

  • App shell: every same-origin navigation wrote its response into the app-shell cache slot. A page the host serves outside the SPA rewrite — Firebase Hosting's /__/auth/handler and /__/auth/iframe when authDomain is the app's own domain, a static legal page, a download — replaced the shell with its own HTML, after which any navigation that falls back to cache (offline, origin 5xx, a deep link the origin 404s) served that page instead of the app. Only / and /index.html may refresh the shell now, __/* is passed straight to the network (RESERVED_PATH_PREFIXES),, and a response that followed a redirect is stored only as a rebuilt copy with the flag dropped — browsers refuse to replay a redirected response for a navigation. (packages/sw/src/sw/fetch-handler.ts, packages/sw/src/shared/constants.ts)

  • App shell: a failed cache write discarded a good page. cache.put sat inside the same try as the fetch, so quota pressure — routine for a wasm-sized app — turned a 200 from the origin into the stale cached copy, or into the literal 503 Offline page on a profile with nothing cached yet. Cache writes and cache reads are now each contained, and nothing after a successful fetch can reject the response handed to respondWith. (packages/sw/src/sw/fetch-handler.ts)

  • Service Worker: progress.report is best-effort. Its callers sit on the path that produces a respondWith response, so a failure to reach clients could surface as a failed navigation or a failed main.dart.wasm. (packages/sw/src/sw/progress.ts)

  • Generator: making the shell a manifest entry exposed an ordering problem that was harmless while it was ignore — cleanup substitutes {{sw_version}} / {{flutter_service_worker_version}} into index.html after the manifest is hashed, so the recorded hash and size would have described a file the origin never serves. The generator now substitutes and re-hashes the entry itself. The version is still derived from the pre-substitution manifest, so it stays deterministic; note that the derived value does change relative to 0.1.5, because the shell is now part of the manifest it is derived from. (lib/src/generator.dart, lib/src/cleanup.dart)

  • Bootstrap: a bootstrap.js and an sw.js from different builds (an HTTP-cached bootstrap without Cache-Control: no-cache) froze the counter silently, since no message ever passes the swVersion check. The mismatch is now reported — once, at teardown, and only when every message was foreign, so an ordinary update load (where the outgoing controller talks alongside the installing worker) stays quiet. (packages/sw/src/bootstrap/pipeline.ts)

  • Bootstrap: reloadIfForeignController resolved the SW filename against location.href instead of the document base URL that navigator.serviceWorker.register actually uses. On any deep link it expected /chat/sw.js, judged the perfectly good /sw.js controller foreign, unregistered it and reloaded the page — once per tab session, on every deep link. (packages/sw/src/bootstrap/sw-registration.ts)

  • Service Worker: resource keys are now relative to the worker's registration.scope. Keyed by absolute pathname, every manifest lookup missed under a non-root <base href> — and, worse, RESERVED_PATH_PREFIXES stopped matching, so an app served from /app/ routed Firebase Auth's /app/__/auth/* navigations through the app-shell branch. swapCaches used the same normalisation and so could evict the shell it had just pre-cached. (packages/sw/src/shared/utils.ts, packages/sw/src/sw/cache-manager.ts)

  • Service Worker: a same-origin navigation that the origin redirects is no longer answered with the app shell. A navigation carries redirect mode manual, so a 3xx arrives as an opaque redirect (status 0, ok false); it is now passed back untouched, which is what lets the browser follow it. (packages/sw/src/sw/fetch-handler.ts)

  • Service Worker: the install-time pre-cache stores a replayable copy of the shell. It had no redirect guard at all — and on a cold profile it is the only writer of the shell — so a host that redirects index.html?v=… left a copy the browser refuses to serve for any later navigation. (packages/sw/src/sw/cache-manager.ts)

  • Service Worker: notifyIndex('updated') is sent only when the shell was actually written, instead of announcing a refresh that quota pressure had just discarded. (packages/sw/src/sw/fetch-handler.ts)

  • Service Worker: the pre-cache progress callback runs outside the block that attributes failures, so a throwing progress report can no longer be recorded as a failed resource — or, for a Core entry, fail the whole install over telemetry. (packages/sw/src/sw/cache-manager.ts)

  • Generator: --no-cleanup leaves index.html alone again, including its version placeholders. Substituting under that flag both broke its contract and made the derived version depend on a file the same run had rewritten, so re-running the documented in-place dev loop shipped a new version for byte-identical content. (lib/src/generator.dart)

Changed #

  • Service Worker: cacheFirst degrades to a plain network fetch when CacheStorage is unusable (evicted, blocked by a privacy mode) instead of failing the resource outright.
  • Protocol: SWProgressMessage gains swVersion and counted. resourcesSize now describes the counted set rather than every cacheable resource, so it agrees with resourcesCount; consumers reading it as "total bytes on disk" should switch to summing the manifest. See docs/service-worker.md for the two rules a client must follow.
  • Service Worker: the startup banner reports counted: N (was precache: N) and its size is the total cacheable bytes, matching resources: N beside it.
  • Service Worker: every sw-progress message is emitted through one reporter (createProgressReporter) instead of each handler assembling its own; the pre-cache and the counted set are now driven by the same COUNTED_CATEGORIES list and cannot drift apart.

Tests #

  • Playwright: cold, warm and five-consecutive-cold loads assert that the numerator never leaves the counted set, reading the SW messages directly rather than the overlay text (which stops updating when the app takes over). On 0.1.5 the cold load counts 9 resources against a total of 6.
  • Playwright: the app shell is pre-cached, answers an offline navigation, and answers a route the origin 404s.
  • Playwright: visiting a same-origin page outside the SPA leaves the cached shell intact, and a deep link still gets the app afterwards. Both fail on the first cut of this fix.
  • Vitest: host-reserved navigations are passed through; the shell is refreshed only from a request for the shell; a redirected response is not stored; a page the origin served is still returned when the cache write fails; precache and the fetch handler agree on the shell cache key.
  • Vitest: progress.ts set membership and message shape; pipeline counter behaviour for foreign versions, uncounted resources and a fixed denominator.
  • Vitest: an app served from a subpath keeps host-reserved paths reserved, treats its scope root as the shell request, and serves deep routes from the pre-cached shell.
  • Vitest: a redirected shell is stored replayably by both writers; an opaque redirect is passed back rather than answered with the shell.
  • Vitest: the counter clamp is reached — two builds reporting under one pinned --version — and the foreign-version report fires only when every message was foreign.
  • Dart: generate() over a synthetic build directory pins the shell entry against the bytes on disk, version stability across in-place re-runs, and that the version still moves for any changed resource including the shell.
  • Playwright: the counter specs wait for the worker to go quiet instead of sleeping on fixed timers, and the five-load spec installs its recorder once.

0.1.5 — 2026-04-22 #

Changed #

  • Example: simplified the platform-specific update-check wiring with a conditional-import entrypoint and clarified the example update API contract for the user-approved refresh flow. (example/lib/src/update/platform/update_check.dart, example/lib/src/update/platform/update_check_js.dart, example/lib/src/update/platform/update_check_vm.dart, example/lib/src/update/update_check_api.dart)

0.1.4 — 2026-04-22 #

Fixed #

  • Bootstrap: WebAssembly.instantiate(): Import #N "X": module is not an object or function failures on first load after a deploy. When an old SW kept controlling the page while a new SW installed in the background, any file missing from the old SW's manifest fell through to the network (fresh) while cached files stayed stale — so Flutter would load a fresh main.dart.mjs against a stale main.dart.wasm and the import schemas would disagree. Bootstrap now force-activates a pre-existing waiting worker at registration time via {type:'skipWaiting'} + controllerchange, so subsequent fetch(main.dart.wasm) / import(main.dart.mjs) go through the new SW with a coherent cache. Bounded by SW_REGISTRATION_TIMEOUT_MS; falls back to the old waitForActivation path on timeout. (packages/sw/src/bootstrap/sw-registration.ts)
  • Bootstrap: pages controlled by a foreign SW at a different script path (e.g., an old flutter_service_worker.js left from a pre-migration deploy) can serve a similarly incoherent mix of files. Bootstrap now detects this pre-registration and performs a one-shot location.reload() after unregistering the offending registration. A sessionStorage guard prevents reload loops if the handoff doesn't take. (packages/sw/src/bootstrap/sw-registration.ts, packages/sw/src/bootstrap/pipeline.ts)

Changed #

  • Bootstrap: foreign-controller cleanup is surgical — only the registration whose active worker equals the current navigator.serviceWorker.controller is unregistered. Unrelated registrations at other scopes (typically firebase-messaging-sw.js for push notifications) are left intact so their subscriptions survive the recovery. (packages/sw/src/bootstrap/sw-registration.ts)

Scope note #

  • The pre-existing-waiting auto-activation is intentionally bootstrap-only: once the app is running, updates continue through the existing sw-update-available → applyUpdate user-approval flow, so running sessions are never yanked out from under the user.

0.1.3 — 2026-04-20 #

Fixed #

  • Bootstrap: Bootstrap.onUpdateAvailable handlers were silently dropped on flutter-first-frame because BootstrapAPI.dispose() cleared the updateHandlers Set alongside the (correctly load-phase-scoped) progress subscribers. Update handlers are now retained for the lifetime of the page, so apps reliably receive the "new SW installed" signal after the loading widget disappears. (packages/sw/src/bootstrap/api.ts)
  • Bootstrap: the sw-update-available DOM bridge listener installed by runPipeline was registered with { once: true }, so a long-lived tab encountering a second deploy never notified handlers. The listener is now permanent for the page lifetime; wireUpdateDetection already dispatches at most once per SW install. (packages/sw/src/bootstrap/pipeline.ts)

Changed #

  • Bootstrap: BootstrapAPI.notifyUpdateAvailable now routes async-handler rejections to console.error instead of leaving an "Uncaught (in promise)" warning that masks the real error. (packages/sw/src/bootstrap/api.ts)

0.1.2 — 2026-04-20 #

Fixed #

  • Bootstrap: production deploys on hosts with SPA rewrites (Firebase Hosting, Netlify with index.html fallback, etc.) crashed at _flutter.loader not available after loading flutter.js because the server returned index.html for the bare flutter.js fetch. The bootstrap now inlines Flutter's flutter.js IIFE into bootstrap.js at generation time, so no runtime fetch of flutter.js is performed and the loader is available before the pipeline starts.

Changed #

  • Cleanup: version.json is no longer deleted — it carries Flutter's app version metadata and may be read by the app or external tooling at runtime.
  • Cleanup: flutter.js is now removed from the deployed output (its loader is inlined into bootstrap.js).
  • Docs: README "CI step" snippet no longer recommends rm -f build/web/flutter.js manually — the generator handles it.

0.1.1 — 2026-04-20 #

Added #

  • Docs: "Local Development" section in README.md covering the monorepo layout, TypeScript ↔ Dart build pipeline, and commands for running the generator against example/build/web/.

0.1.0 — 2026-04-20 #

Complete rewrite replacing Flutter's default bootstrap with a professional two-artifact system.

Fixed (post-audit hardening) #

  • Generator: crash on short or empty engineRevision now surfaces a clear error before artifact generation.
  • CLI precedence: --flag with an ArgParser default no longer shadows YAML / env values (wasParsed gate). Glob options (--core, --required, …) now honour SW_CORE, SW_REQUIRED, SW_OPTIONAL, SW_IGNORE, SW_GLOB, SW_EXCLUDE_GLOB environment variables that previously did nothing.
  • CLI: invalid --min-progress / --max-progress values now fail with exit code 64 instead of silently defaulting to 0/90.
  • Cleanup: canvaskit pruning uses consistent URL-style paths, fixing a Windows case where \-separated paths never matched the keep-set.
  • SW notifyClients: a single dead client no longer aborts iteration — every other client still receives the progress update.
  • SW cacheFirst: non-OK responses (4xx/5xx) now emit an error progress event so the bootstrap UI can surface the failure instead of hanging on loading. Fallback 503s carry Content-Type: text/plain.
  • SW swapCaches: reordered to copy-then-evict-then-persist-manifest, and eviction now excludes paths that were just re-precached from temp (no more accidental deletion of the fresh bytes).
  • SW message-handler: accepts both "skipWaiting" strings and {type: "skipWaiting"|"getVersion", requestId?} objects; getVersion replies echo requestId for correlation.
  • Loading widget: dispose adds a 600ms safety teardown, so the widget and its stylesheet don't leak when transitionend doesn't fire (reduced-motion, background tabs).
  • CanvasKit loader: detectWebGLVersion releases its temporary canvas + GL context via WEBGL_lose_context instead of relying on GC.

Added #

  • Deterministic version: when --version / SW_VERSION / YAML is absent, the generator derives a stable 12-char sha256 over the manifest contents. Re-running against an unchanged build now yields the same SW version.
  • Dart UI defaults → bootstrap: --logo, --title, --theme, --color, --min-progress, --max-progress flags are baked into bootstrap.js as BuildConfig.uiDefaults. data-config still overrides at runtime.
  • Precache concurrency cap (PRECACHE_CONCURRENCY = 6) so large manifests don't stampede the origin during install.
  • Manifest size warning: generator emits a stderr warning when sw.js exceeds 10 MB.
  • Update prompt API: window.Bootstrap.onUpdateAvailable(handler) and window.Bootstrap.applyUpdate(reload=true) let apps prompt for and apply a waiting SW upgrade. sw-registration.ts exports activateWaitingSW(registration) for lower-level use.
  • CI: new e2e GitHub Actions job runs flutter build web + dart run sw:generate + Playwright on each PR; SW_E2E_BROWSERS=all opts into the Chromium/Firefox/WebKit matrix.
  • Tests: test/config_test.dart, test/files_test.dart, and new injector cases covering uiDefaults. Removed the empty test/unit_test.dart placeholder.

Original 0.1.0 feature set #

Breaking Changes #

  • CLI arguments updated: new options added, some defaults changed
  • Generated output now produces two files (sw.js + bootstrap.js) instead of one
  • Requires <script defer data-sw-bootstrap src="bootstrap.js"> in index.html
  • Old inline JS/CSS loading UI replaced by the built-in loading widget

Added #

  • Bootstrap pipeline — 6-stage initialization replacing flutter_bootstrap.js
    • Stages: Init → SW Registration → CanvasKit → Assets → Dart Entry → Dart Init
  • Loading widget — Responsive circular progress with SVG ring, stall detection, error display, dark/light/auto theme
  • CanvasKit CDN loading — Automatic engineRevision extraction, Google CDN with local fallback
  • Resource categorization — Core, Required, Optional, Ignore with glob-based overrides
  • Global API — window.Bootstrap.dispose(), .progress, .subscribe(cb) for Dart integration
  • YAML config — sw.yaml as alternative to CLI args (priority: CLI > YAML > env > defaults)
  • Exponential backoff — 3 retry attempts with 1s/2s/4s delays and jitter
  • Cache busting — Hash-based ?v={hash} query params on all cached resources
  • Atomic cache updates — Temp cache during install, swapped on activate
  • Console logging — Styled version banner with engine revision, SW version, renderer info
  • Stall detection — "Reset Cache" button after 30s without progress
  • Auto-cleanup — Removes flutter_bootstrap.js, flutter_service_worker.js, version.json, .js.map, .js.symbols
  • TypeScript source — SW and Bootstrap written in TypeScript, compiled via Vite to minified IIFE

Changed #

  • Monorepo structure: packages/sw/ (TypeScript) + root (Dart CLI)
  • Service Worker rewritten in TypeScript with modular architecture
  • Cache naming: {prefix}-{version} for content, {prefix}-manifest for manifest storage
  • bootstrap.js, index.html, sw.js are never cached by the SW

Removed #

  • Inline JS/CSS string templates in Dart (replaced by compiled TypeScript)
  • downloadOffline command (simplified caching model)
  • Navigation preload (replaced by simpler network-first for index.html)
  • Comment stripping (Vite handles minification)

0.0.7 #

  • Simplify service worker by removing retry logic and navigation preload.
  • Replace Promise.race timeout wrappers with modern AbortController-based fetchWithTimeout.
  • Remove unused constants (MEDIA_EXT, NETWORK_ONLY, RETRY_DELAY).
  • Remove INSTALL_TIMEOUT, ACTIVATE_TIMEOUT wrappers from install/activate events.
  • Streamline activate event handler by removing redundant Promise.race nesting.

0.0.6 #

  • Add timeout protection for install (30s) and activate (30s) events.
  • Add fetch timeout (10s) and retry logic (2 retries with 500ms delay).
  • Add navigation preload support for online-first strategy.
  • Clean up all stale caches with matching prefix on activation.
  • Ensure self.clients.claim() is always called, even on error/timeout.
  • Emit sw-version.txt alongside sw.js for CI version injection.

0.0.5 #

  • Update index.html example to include more features.

0.0.4 #

  • Improved service worker generation.

0.0.3 #

  • Service worker generation now based on the flutter's flutter_service_worker.js.

0.0.2 #

  • Proof of concept for service worker generation

0.0.1 #

  • Initial release with basic functionality
20
likes
0
points
5.11k
downloads

Publisher

verified publisherplugfox.dev

Weekly Downloads

A command-line tool to generate service worker files for web applications. It simplifies the process of creating service workers.

Repository (GitHub)
View/report issues

Topics

#service-worker #generator #cli #web #flutter

License

unknown (license)

Dependencies

args, crypto, glob, path, yaml

More

Packages that depend on sw