@muzzamil7770/app-update-agent

Detects app version changes, prompts users to update, clears cache, unregisters service workers, and reloads — with a pluggable UI and full Angular support.

npm i @muzzamil7770/app-update-agent

---

Preview

Update Prompt

The dialog shown to the user when a new version is detected.

---

Video Demo

Watch the full update flow — version detection → prompt → cache clear → reload.

💡 If the video doesn't play inline, click here to watch the demo

---

How It Works

Full Update Flow

flowchart TD
    A([App Starts]) --> B[startMonitoring called]
    B --> C{devMode?}
    C -- Yes, no override --> Z([Monitoring Disabled])
    C -- No / forceInDevMode --> D[Poll /version.json every 60s]
    D --> E{Network Request\nGET /version.json?t=timestamp}
    E -- Fetch fails --> F[Retry up to 3x\nwith 2s delay]
    F -- All retries fail --> D
    E -- Success --> G{Version changed?}
    G -- No change --> D
    G -- Yes --> H[onUpdateDetected hook fired]
    H --> I[Show Update Prompt UI]
    I -- User dismisses --> D
    I -- User confirms --> J[Show Progress UI]
    J --> K[Clear all browser caches]
    K --> L[Unregister Service Workers]
    L --> M[onReload hook fired]
    M --> N([window.location.reload])

Loading

---

Build & Publish Pipeline

flowchart LR
    A([git push to main]) --> B[GitHub Actions triggered]
    B --> C[npm ci — install deps]
    C --> D[npm version patch\nauto bump 1.0.0 → 1.0.1]
    D --> E[git push version bump\nback to main with skip-ci tag]
    E --> F[npm run build\ntsc compiles to dist/]
    F --> G[npm publish --access public]
    G --> H[GitHub Release created]
    H --> I([New version live on npm 🎉])

Loading

---

Network Version Check Internals

sequenceDiagram
    participant App
    participant UpdateEngine
    participant Network as /version.json
    participant UI

    App->>UpdateEngine: startMonitoring()
    loop Every pollInterval (60s)
        UpdateEngine->>Network: GET /version.json?t={timestamp}
        alt fetch succeeds
            Network-->>UpdateEngine: { version: "1.0.5" }
            UpdateEngine->>UpdateEngine: compare with stored version
            alt version changed
                UpdateEngine->>UI: showUpdatePrompt(meta)
                UI-->>UpdateEngine: user confirmed
                UpdateEngine->>UI: showProgress(...)
                UpdateEngine->>App: clearCache + unregisterSW
                UpdateEngine->>App: reload()
            end
        else fetch fails
            UpdateEngine->>UpdateEngine: retry (up to 3x, 2s apart)
        end
    end

Loading

---

Installation

npm i @muzzamil7770/app-update-agent

With SweetAlert2 UI (default):

npm i @muzzamil7770/app-update-agent sweetalert2

---

Quick Start (Angular)

// app.component.ts
import { AppUpdateService } from '@muzzamil7770/app-update-agent';

constructor(private appUpdate: AppUpdateService) {}

ngOnInit() {
  this.appUpdate.startMonitoring();
}

Zero config needed — defaults match the original behaviour exactly.

---

Configuration

Configure once globally before startMonitoring() (e.g. in main.ts):

import { AppUpdateService } from '@muzzamil7770/app-update-agent';

AppUpdateService.configure({
  versionUrl:       '/version.json',  // default
  pollInterval:     60_000,           // ms, default
  ui:               'sweetalert',     // 'sweetalert' | 'custom' | 'none'
  devMode:          false,            // set true in dev builds
  forceInDevMode:   false,            // override devMode guard for testing
  retryAttempts:    3,                // fetch retries on failure
  retryDelay:       2000,             // ms between retries
  onUpdateDetected: (meta) => console.log('Update detected:', meta),
  onReload:         ()     => console.log('Reloading…'),
});

---

Dev Mode Testing

When devMode: true, monitoring is disabled unless:

• URL contains ?appUpdateTest=1
• localStorage.app_update_test === '1'

// Browser console
window.simulateAppUpdate();

// Programmatic
await this.appUpdate.manualCheck();

---

Custom UI

import { AbstractUpdateUI, VersionMeta } from '@muzzamil7770/app-update-agent';

class MyToastUI extends AbstractUpdateUI {
  showUpdatePrompt(meta: VersionMeta, onConfirm: () => void, onDismiss: (meta: VersionMeta) => void) {
    // show your toast/modal
  }
  showProgress(label: string, pct: number) { /* open progress modal */ }
  updateProgress(label: string, pct: number) { /* update progress bar */ }
}

AppUpdateService.setUI(new MyToastUI());

Set ui: 'none' to suppress all UI and handle onUpdateDetected yourself.

---

Framework-Agnostic Core

import { UpdateEngine, SwalUpdateUI } from '@muzzamil7770/app-update-agent';

const engine = new UpdateEngine(
  { versionUrl: '/version.json', pollInterval: 30_000 },
  new SwalUpdateUI(),
);

engine.start();
engine.stop();
await engine.manualCheck();

---

API Reference

AppUpdateService (Angular)

Method	Description
static configure(config)	Set global config before first use
static setUI(ui)	Inject a custom UI implementation
startMonitoring()	Begin polling + visibility listener
manualCheck()	Trigger an immediate version check

UpdateEngine (Core)

Method	Description
start()	Begin polling
stop()	Stop polling and clear interval
manualCheck()	Trigger an immediate version check

UpdateAgentConfig

Option	Type	Default	Description
versionUrl	string	'/version.json'	URL to fetch version from
pollInterval	number	60000	Polling interval in ms
ui	'sweetalert' | 'custom' | 'none'	'sweetalert'	UI mode
devMode	boolean	false	Disable monitoring in dev
forceInDevMode	boolean	false	Override devMode guard
retryAttempts	number	3	Fetch retry count
retryDelay	number	2000	Ms between retries
onUpdateDetected	(meta) => void	—	Hook fired on version change
onReload	() => void	—	Hook fired before reload

---

Links

• 📦 npm: https://www.npmjs.com/package/@muzzamil7770/app-update-agent
• 🐙 GitHub: https://github.com/muzzamil7770/app-update-agent
• 🐛 Issues: https://github.com/muzzamil7770/app-update-agent/issues