Package Exports

@stardyn/angular-updater
@stardyn/angular-updater/package.json

Readme

@stardyn/angular-updater

Lightweight, configurable version tracking and update notification service for Angular applications with Service Worker support. Provides automatic version checking and user-friendly update prompts.

Features

Service Worker Integration: Seamless integration with Angular Service Worker
Automatic Version Checking: Configurable interval-based version checking
User-Friendly Update Prompts: Customizable dialog for update notifications
Performance Focused: Zero overhead when Service Worker is disabled
Singleton Pattern: Prevents multiple instances and ensures efficient resource usage
Rich Logging: Debug mode with detailed logging for development
Theme Support: Customizable UI themes for update dialogs
Production Ready: Automatically optimized for production environments

Installation

npm install @stardyn/angular-updater

Prerequisites

This package requires Angular Service Worker to be configured in your application:

ng add @angular/pwa

Quick Start

1. App Module Configuration

import { NgModule } from '@angular/core';
import { BrowserModule } from '@angular/platform-browser';
import { ServiceWorkerModule } from '@angular/service-worker';
import { provideXconVersionTracker } from '@stardyn/angular-updater';
import { ActionTheme } from '@xcon-platform/core-ui-actions';

import { AppComponent } from './app.component';
import { environment } from '../environments/environment';

@NgModule({
  declarations: [AppComponent],
  imports: [
    BrowserModule,
    ServiceWorkerModule.register('ngsw-worker.js', {
      enabled: environment.production,
      registrationStrategy: 'registerWhenStable:30000'
    })
  ],
  providers: [
    provideXconVersionTracker({
      checkInterval: 300, // Check every 5 minutes
      debugMode: !environment.production,
      theme: ActionTheme.DARK
    })
  ],
  bootstrap: [AppComponent]
})
export class AppModule { }

2. Standalone Application Configuration

// main.ts
import { bootstrapApplication } from '@angular/platform-browser';
import { provideServiceWorker } from '@angular/service-worker';
import { provideXconVersionTracker } from '@stardyn/angular-updater';
import { ActionTheme } from '@xcon-platform/core-ui-actions';

import { AppComponent } from './app/app.component';
import { environment } from './environments/environment';

bootstrapApplication(AppComponent, {
  providers: [
    provideServiceWorker('ngsw-worker.js', {
      enabled: environment.production,
      registrationStrategy: 'registerWhenStable:30000'
    }),
    provideXconVersionTracker({
      checkInterval: 180, // Check every 3 minutes
      debugMode: !environment.production,
      theme: ActionTheme.LIGHT
    })
  ]
});

3. Manual Service Usage

import { Component, OnInit } from '@angular/core';
import { XconVersionTrackerService } from '@stardyn/angular-updater';

@Component({
  selector: 'app-root',
  template: `
    <h1>{{ title }}</h1>
    <button (click)="checkForUpdates()">Check for Updates</button>
  `
})
export class AppComponent implements OnInit {
  title = 'My App with Version Tracking';

  constructor(private versionTracker: XconVersionTrackerService) {}

  ngOnInit() {
    // Service is automatically initialized via APP_INITIALIZER
    console.log('Version tracker is ready');
  }

  checkForUpdates() {
    // Manual configuration if needed
    this.versionTracker.configure({
      checkInterval: 60,
      debugMode: true,
      theme: ActionTheme.DARK
    });
  }
}

API Reference

XconVersionTrackerConfig

interface XconVersionTrackerConfig {
  debugMode?: boolean;     // Enable/disable debug logging (default: false)
  checkInterval?: number;  // Version check interval in seconds (default: 60)
  theme: ActionTheme;     // UI theme for update dialogs (required)
}

XconVersionTrackerService

Configuration

// Configure the service
versionTracker.configure(config: XconVersionTrackerConfig): void

Initialization

The service is automatically initialized when provided via provideXconVersionTracker(). Manual initialization is not required.

// Automatic initialization via APP_INITIALIZER
versionTracker.initialize(): void

Provider Function

// Provide the version tracker service with configuration
provideXconVersionTracker(config: XconVersionTrackerConfig): (Provider | EnvironmentProviders)[]

Utility Functions

// Reset singleton instance (useful for testing)
resetVersionTrackerInstance(): void

Configuration Examples

Development Configuration

provideXconVersionTracker({
  checkInterval: 30, // Check every 30 seconds for quick testing
  debugMode: true,   // Enable detailed logging
  theme: ActionTheme.LIGHT
})

Production Configuration

provideXconVersionTracker({
  checkInterval: 600, // Check every 10 minutes
  debugMode: false,   // Disable logging for performance
  theme: ActionTheme.DARK
})

Environment-Based Configuration

// environments/environment.ts
export const environment = {
  production: false,
  versionTracker: {
    checkInterval: 60,
    debugMode: true,
    theme: ActionTheme.LIGHT
  }
};

// app.module.ts or main.ts
provideXconVersionTracker(environment.versionTracker)

Update Flow

Version Detection: Service Worker detects a new version is available
Download: New version is downloaded in the background
Ready Notification: User is prompted with an update dialog
User Choice: User can accept or decline the update
Update Application: If accepted, page reloads with the new version

Debug Output Examples

When debug mode is enabled, console outputs appear in this format:

[XconVersionTracker] XconVersionTracker service initialized
[XconVersionTracker] XconVersionTracker configured {checkInterval: 60, debugMode: true, theme: "light"}
[XconVersionTracker] Version Tracker Initializing
[XconVersionTracker] New application version found, beginning download: abc123def
[XconVersionTracker] New app version ready: xyz789ghi

Dependencies

Peer Dependencies

@angular/core >= 16.0.0
@angular/common >= 16.0.0
@angular/service-worker >= 16.0.0
rxjs >= 7.0.0

Internal Dependencies

@stardyn/angular-console - Console logging service
@stardyn/angular-core-ui-actions - UI action dialogs and themes

Performance

Service Worker Disabled: Zero overhead - service returns early
Singleton Pattern: Only one instance created regardless of provider calls
Zone Optimization: Version checking runs outside Angular zone
Memory Efficient: Minimal memory footprint with proper cleanup

TypeScript Support

Full TypeScript support with intellisense and type safety:

import { XconVersionTrackerConfig, ActionTheme } from '@stardyn/angular-updater';

const config: XconVersionTrackerConfig = {
  checkInterval: 300,
  debugMode: false,
  theme: ActionTheme.DARK
};

Troubleshooting

Service Worker Not Working

Ensure Angular Service Worker is properly configured:

ng add @angular/pwa

Update Dialog Not Appearing

Check if Service Worker is enabled in your environment
Verify debug mode is enabled to see console logs
Ensure the app is served over HTTPS (required for Service Workers)

Multiple Instance Warning

The service uses a singleton pattern. If you see multiple initialization messages, ensure you're only calling provideXconVersionTracker() once in your application.

License

MIT License - see LICENSE file for details.

Repository

https://github.com/stardyn/angular-updater