📦 offline-page-kit

Minimal, framework-agnostic Service Worker generator that prevents blank screens during network failure.

🟡 Professional npm Description

offline-page-kit is a lightweight, zero-dependency Service Worker toolkit that provides deterministic offline fallback behavior for modern web applications.

It guarantees that when network connectivity fails, users see a controlled offline experience instead of browser error pages or blank screens.

Designed for production-grade stability across:

• Next.js
• Vite
• React
• Vue
• Static sites
• Any public-folder architecture

No Workbox.
No complex runtime caching layers.
No unpredictable asset behavior.

Just reliable navigation fallback.

🟣 Demo

• Online page load
• DevTools → Offline mode
• Refresh → Offline page appears

🚀 Quick Start

1️⃣ Install

npm install offline-page-kit

2️⃣ Generate Service Worker

npx offline-page-kit init --outDir public

This generates:

public/
 ├── sw.js
 ├── offline.html
 └── offline.svg

3️⃣ Register in Client

import { registerOfflineKit } from "offline-page-kit";

registerOfflineKit({ debug: true });

Done ✅

🧠 Architecture

Browser
   ↓
Service Worker
   ↓
Fetch Navigation Request
   ├─ Network OK  → return live page
   └─ Network FAIL → return cached offline.html

Only navigation requests are intercepted.

No API mutation.
No asset rewriting.
No hidden caching layers.

🔄 Lifecycle

Install → Activate → Control → Fetch

Install

• Caches offline page + fallback image
• Uses Promise.allSettled() to avoid failure

Activate

• Immediately claims clients

Fetch

• Applies network-first
• Falls back to offline page

🧩 Framework Examples

Next.js (App Router)

// #/app/page.tsx
"use client";

import { useEffect } from "react";
import { registerOfflineKit } from "offline-page-kit";

export default function Home() {
  useEffect(() => {
    registerOfflineKit(
      {
        swUrl: "/sw.js",
        scope: "/",
        debug: true
      }
    );
  }, []);
  return (
    <main className="flex min-h-screen flex-col items-center justify-between p-24">
      <h1 className="text-4xl font-bold">You are Online.</h1>
    </main>
  );
}

Vite / React

import { registerOfflineKit } from "offline-page-kit";

registerOfflineKit();

⚙ Windows PowerShell (VSCode)

npx offline-page-kit init `
  --outDir public `
  --offlinePage /offline.html `
  --offlineImage /offline.svg `
  --cacheName my-app-cache-v1

🔹⚙ Windows CMD

npx offline-page-kit init ^
  --outDir public ^
  --offlinePage /offline.html ^
  --offlineImage /offline.svg ^
  --cacheName my-app-cache-v1

⚙ Linux/macOS (Bash/Zsh)

npx offline-page-kit init \
  --outDir public \
  --offlinePage /offline.html \
  --offlineImage /offline.svg \
  --cacheName my-app-cache-v1

| Option | Default | Description | |--------|---------|------------| | outDir | public | Static folder | | offlinePage | /offline.html | Navigation fallback | | offlineImage | /offline.svg | Fallback asset | | cacheName | offline-page-kit | Cache namespace |

🔐 Security

• Requires HTTPS (or localhost)
• Does not cache authenticated APIs
• Does not alter CORS behavior
• Per-origin scoped

⚡ Performance

• Zero runtime dependencies
• Minimal memory usage
• No background sync
• No bundle overhead

🧪 Testing

1. Load site
2. Reload once
3. DevTools → Application → Service Workers
4. Enable Offline
5. Refresh

Offline page should render.

🏢 Production Notes

• Always deploy over HTTPS
• Version cache when updating logic
• Avoid multiple SWs in same scope

🧭 Roadmap

• Asset caching layer
• API strategy module
• Auto public folder scan
• Cache version hashing
• Metrics integration
• Advanced fallback strategies

📜 License

MIT