offline

Getting started

Install#

npm i @dmytromykhailiuk/offline @dmytromykhailiuk/network-connection

Quick start#

Three pieces: a config file next to your project, one script in the build pipeline, a few lines at app startup.

1. Describe the offline layer in offline.json:

{
  "name": "Client",
  "buildPath": "/dist",
  "themeColor": "#1c1c1c",
  "icons": [
    { "src": "icons/icon-192x192.png", "sizes": "192x192", "type": "image/png" }
  ],
  "criticalAssets": ["**.js", "**.css", "**.svg", "/images/logo.png"],
  "lazyLoadAssets": ["/images/*.jpg"],
  "dataGroups": [
    { "name": "translations", "urls": ["/translations/"], "maxSize": 1 }
  ]
}

2. Run the CLI after every build:

{
  "scripts": {
    "postbuild": "offline-postbuild"
  }
}

3. Wire the runtime at startup — here with a blocking screen while the connection is down and the app is not yet ready to work offline:

import { NetworkConnection } from "@dmytromykhailiuk/network-connection";
import { OfflineTracker } from "@dmytromykhailiuk/offline";

await NetworkConnection.init("/health.txt");

OfflineTracker.init({ disabled: import.meta.env.DEV });
OfflineTracker.registerServiceWorker();

const networkUnsubscribeFn = NetworkConnection.subscribe((isOnline) => {
  if (!isOnline && !OfflineTracker.isOfflineReady && !NetworkBlockingScreen.isVisible()) {
    NetworkBlockingScreen.show();
  }

  if (isOnline && NetworkBlockingScreen.isVisible()) {
    NetworkBlockingScreen.hide();
  }
});

OfflineTracker.whenOfflineReady().then(() => networkUnsubscribeFn());

How it works#

1. The CLI walks the build directory, matches files against the criticalAssets / lazyLoadAssets patterns and writes the resulting pathnames — prefixed with deploymentPath — into critical-assets.json and into the generated worker. It also stamps build-timestamp.txt and injects the bootstrap script into index.html.
2. The worker serves SPA routes network-first from a dedicated index cache, assets cache-first, and dataGroups URLs cache-first into named caches. It also understands a diagnostic header: a request carrying X-Cache-Only: true is answered from the cache or failed — never sent to the network.
3. The tracker asks the worker "which of these are cached yet?" — in one message for a long list, asset by asset with that header otherwise. Whatever is missing gets fetched (which makes the worker cache it), re-checked on an interval, paused while offline, resumed on reconnect — until everything critical is confirmed. Lazy assets do the same in the background.

Build time

offline.json#

Lives wherever you point --config at (default: the directory you run the CLI from). Every path is resolved relative to the config file's directory — a leading / is a convention, not a filesystem root.

Every field#

dataGroups#

Named runtime caches for data the build does not contain — themes, fonts, translations, models. A request belongs to a group — and is served cache-first from data-group-<name> — when its pathname starts with any of the group's urls prefixes or matches any of its patterns.

"dataGroups": [
  { "name": "translations", "urls": ["/translations/"], "maxSize": 1 },
  { "name": "images", "patterns": ["**.webp", "**.avif"] },
  { "name": "themes", "urls": ["/themes/"], "patterns": ["**/skins/**.css"] }
]

The generated manifest#

Every run generates manifest.webmanifest in the build directory — built from the flat fields above (name, shortName, themeColor, backgroundColor, display, icons) — and adds <link rel="manifest"> to the injected head block, making the app installable with zero extra steps. camelCase config keys map to the spec's snake_case on output.

// offline.json (manifest-related fields)
{
  "name": "Client",
  "deploymentPath": "/client",
  "buildPath": "/dist",
  "themeColor": "#1c1c1c",
  "icons": [
    {
      "src": "core-assets/icons/icon-192x192.png",
      "sizes": "192x192",
      "type": "image/png",
      "purpose": "maskable any"
    },
    {
      "src": "core-assets/icons/icon-512x512.png",
      "sizes": "512x512",
      "type": "image/png",
      "purpose": "maskable any"
    }
  ]
}

// → dist/manifest.webmanifest
{
  "name": "Client",
  "short_name": "Client",
  "theme_color": "#1c1c1c",
  "background_color": "#ffffff",
  "display": "standalone",
  "scope": "/client/",
  "start_url": "/client/",
  "icons": [ ... ]
}

The CLI#

offline-postbuild                # reads ./offline.json
offline-postbuild --config ./config/offline.json

Inside buildPath, in order:

1. build-timestamp.txt — the build's Date.now(), the new-version detector;
2. collects assets by the config patterns (its own outputs are excluded, so re-runs never precache a stale worker);
3. critical-assets.json — the deployment-prefixed critical list;
4. manifest.webmanifest — the web app manifest, with scope/start_url derived from deploymentPath;
5. sw-min.js — the worker, generated from the template with your config baked in and minified in memory (no intermediate sw.js ever touches the disk);
6. injects the bootstrap script and the manifest <link> as the first thing inside <head> of the built index.

The service worker#

The generated sw-min.js routes every fetch by four rules, first match wins:

The bootstrap script#

Injected by the CLI as the first script in <head>, in plain pre-ES2015 JS, so it runs before any bundle on any browser. Four jobs:

1. Publish the build config. window.__OFFLINE_CONFIG__ = { deploymentPath } — the convention that lets registerServiceWorker() work with no arguments, at any moment, in any order.
2. Fix the worker scope. A visit to /app (no trailing slash) is redirected to /app/ — a worker registered at /app/sw-min.js does not control the slashless URL.
3. Recover from chunk errors. A ChunkLoadError means a lazy chunk was requested that is neither cached nor reachable — the page reloads once, as soon as the connection returns.
4. Detect new builds. build-timestamp.txt is fetched cache-bypassing and compared with the remembered one; a mismatch clears every cache so the worker re-caches the new version.

Runtime

OfflineTracker#

A class used purely through its static members — the constructor is private and throws. There is exactly one offline state per app, and the type system (plus a runtime guard) makes an accidental second one impossible.

class OfflineTracker {
  static init(options?: OfflineTrackerOptions): void;
  static reInit(options?: OfflineTrackerReInitOptions): void;
  static registerServiceWorker(): void;
  static get status(): OfflineStatus;
  static get isOfflineReady(): boolean;
  static get wasOfflineReadyLastSession(): boolean;
  static subscribe(listener: (isOfflineReady: boolean) => void): OfflineTrackerUnsubscribe;
  static whenOfflineReady(): Promise<void>;
  static stabilizeCaching(): Promise<void>;
  static destroy(): void;
}

init(options?)#

Synchronous, returns nothing — it kicks the whole process off and the async work runs in the background. The first call verifies the NetworkConnection precondition (throws synchronously when missing), wires the controllerchange re-track and the reconnect auto-stabilization, fetches critical-assets.json through a client-side cache-first bucket (@dmytromykhailiuk/cache-request, bucket offline-critical-assets): the cached copy is served when present — no network round-trip per session — and a miss goes to the network, HTTP-cache-bypassing, caching the ok response. The bucket is invalidated by the bootstrap's new-build cache wipe, so a fresh build means a fresh list. With no cached copy the fetch is retried until an ok response arrives (the CLI always generates the file, so a 404/5xx is transient deploy state; offline stretches are waited out via NetworkConnection.continueWhenOnline()) — and starts tracking: once a worker controls the page, ask it what is cached (one offline:cache-diff message, or an X-Cache-Only request per asset), fetch what's missing (the worker caches it), re-check on retryDelay, park while offline, resume on reconnect. Critical assets gate readiness directly; additionalLazyLoadAssets load in the background and flip isOfflineReady when done.

Callable once — the configuration it resolves is final, and a second call throws. Restart tracking with reInit(); reconfigure via destroy() + init().

reInit(options?)#

// The flow-manager table arrived and brought its own assets:
OfflineTracker.reInit({
  additionalCriticalAssets: table.additionalAssetsToLoad,
  additionalLazyLoadAssets: table.additionalLazyLoadAssets,
});

Restart tracking with more assets — the only two options it takes are additionalCriticalAssets and additionalLazyLoadAssets; the configuration (hooks, delays, disabled) belongs to init() and cannot change here. Synchronous, returns nothing, callable any number of times. Throws before init(); a no-op while initialized with disabled: true.

• Merging: the passed lists join the deduplicated union of everything given to init() and earlier reInit() calls — a later caller can never drop what an earlier one declared critical. The union always sits on top of critical-assets.json, which is not refetched.
• Superseding: the previous cycle stops silently; readiness resets and is re-verified from scratch.
• controllerchange: a new worker taking over re-runs tracking with the accumulated union automatically — a new worker means a new, empty cache.

registerServiceWorker()#

Registers origin + deploymentPath + "/sw-min.js" with updateViaCache: "none", the deployment path taken from the CLI-injected window.__OFFLINE_CONFIG__ — the single source of truth. Synchronous, returns nothing — like init(), it kicks the registration off and the browser does the rest in the background. No parameters, independent of init() — call it at any moment, in either order. A silent no-op where service workers do not exist (SSR, dev without the postbuild, unsupported browsers). When NetworkConnection is initialized, the registration survives connection drops via restartIfNotFinishedWhenOnline; a registration that genuinely fails is reported to the console — there is no meaningful recovery the caller could do.

status & isOfflineReady#

OfflineTracker.status;
// { criticalAssetsLoaded: boolean, lazyAssetsLoaded: boolean, allAssetsLoaded: boolean }

OfflineTracker.isOfflineReady; // shortcut for status.allAssetsLoaded

status returns a fresh snapshot object on every read; isOfflineReady is the single boolean the app usually cares about. Both throw before init().

wasOfflineReadyLastSession#

OfflineTracker.init({ disabled: import.meta.env.DEV });

// Paint straight away instead of flashing a spinner on every reload…
splash.hidden = OfflineTracker.wasOfflineReadyLastSession;

// …then correct it the moment the cache has actually answered.
OfflineTracker.subscribe((isReady) => {
  splash.hidden = isReady;
});

Readiness is remembered in localStorage between sessions and read back once at init(), so the UI has something better than "not ready" to paint in the moment before the first cache check answers. Always false when initialized with disabled: true; throws before init(). The injected bootstrap drops it together with the caches on a new build.

subscribe(listener)#

const unsubscribe = OfflineTracker.subscribe((isOfflineReady) => {
  banner.hidden = isOfflineReady;
});
unsubscribe(); // detach; calling it again is a no-op

Fires on every change of isOfflineReady — in both directions (re-initializing against a wiped cache drops readiness first). The listener is not called on subscription: the current value is already available synchronously. A throwing listener is contained and reported; subscribing or unsubscribing from inside a listener is safe; destroy() drops every subscription without a final call.

whenOfflineReady()#

Resolves immediately when ready, otherwise on the next transition to ready. destroy() rejects pending waiters — leaving them hanging would deadlock the code awaiting them.

stabilizeCaching()#

The repair path. Without a controlling, active worker the cache state is untrustworthy — every cache is deleted and the page reloads to start clean. With a healthy worker, the still-missing assets get one load-and-recheck round, flipping readiness if that closed the gap.

It runs automatically after the connection comes back while the app is not ready (gated by shouldStabilize), and it can be called manually at any time. Before the first tracking cycle populates the missing-asset sets it is a deliberate no-op — an empty "missing" set proves nothing.

destroy()#

Undo init(): stop every loop, detach the controllerchange and network listeners, drop subscriptions without a final call, reject pending whenOfflineReady() waiters, reset all state. A no-op when not initialized. Built for tests and HMR teardown — production apps normally never call it.

Recipes#

Auth-protected assets#

OfflineTracker.init({
  modifyRequestHeaders: (headers) => {
    headers.set("Authorization", getToken());
    return headers;
  },
});

The worker forwards the header named by authHeaderPath in offline.json when it fetches on the page's behalf.

Versioned asset paths#

OfflineTracker.init({
  mapAssetUrl: (url) =>
    url
      .replace("{theme}", currentTheme())
      .replace("{lang}", currentLanguage()),
});

Route-scoped stabilization#

OfflineTracker.init({
  shouldStabilize: () =>
    !location.pathname.includes("/upload") &&
    !location.pathname.includes("/completed"),
});

Assets that arrive with data#

// Call reInit() whenever the server tells you what else matters —
// the new assets merge into the tracked union, tracking restarts,
// the list is not refetched.
onTableLoaded((table) => {
  OfflineTracker.reInit({
    additionalCriticalAssets: table.additionalAssetsToLoad ?? [],
    additionalLazyLoadAssets: table.additionalLazyLoadAssets ?? [],
  });
});

TypeScript#

Everything is typed; the package ships ESM + CJS with .d.ts for both. Exported types: OfflineTrackerOptions · OfflineTrackerReInitOptions · OfflineStatus · OfflineTrackerListener · OfflineTrackerUnsubscribe · OfflineGlobalConfig · OfflineConfig · OfflineDataGroup · OfflineManifestDisplay · OfflineManifestIcon.

OfflineConfig / OfflineDataGroup describe offline.json — handy for generating the config from typed build scripts. The window.__OFFLINE_CONFIG__ global is declared on Window, so reading it in app code type-checks out of the box.