ngx-mat-sw-update v0.2.0

ngx-mat-sw-update

ngx-mat-sw-update is a small Angular library that helps you to quickly setup a notification for the user,
when there's a new update for your website available. Please read more on Service Workers here.

Mocked Demo

Installation

ng add @angular/pwa  
npm install ngx-mat-sw-update  

Currently ngx-mat-sw-update offers two ready to use notification variants (use one of them or implement your own):

You can test out all included variations on janmalch.github.io/ngx-mat-sw-update.

English SnackBar notification & check once on startup

@NgModule({  
  imports: [  
    ServiceWorkerModule.register('ngsw-worker.js', {enabled: environment.production}),  
    MatSnackBarModule
  ], 
  providers: [
    { provide: MatSwUpdate, useClass: MsuSnackBarEn }
  ]
})  
export class AppModule {  
  constructor(matUpdates: MatSwUpdate) {  
    matUpdates.checkForUpdate();  
  }  
}  

English Dialog notification & check in interval

@NgModule({  
  imports: [  
    ServiceWorkerModule.register('ngsw-worker.js', {enabled: environment.production}),  
    MsuDialogModule.forRoot(MsuPaddedImageDialogComponent,
      'https://firebase.google.com/images/homepage/grow_2x.png',
      { disableClose: true }
    )
  ], 
  providers: [
    { provide: MatSwUpdate, useClass: MsuDialogEn }
  ]
})  
export class AppModule {  
  constructor(matUpdates: MatSwUpdate) {  
    interval(15 * 60 * 1000).subscribe(() => matUpdates.checkForUpdate());  
  }  
}  

Please consult the docs, when to check for updates.

mat-sw-update directive

imports: [  
  ServiceWorkerModule.register('ngsw-worker.js', {enabled: environment.production}),  
  MsuDirectiveModule,
  // ...

You can use the mat-sw-update directive, to easily show update information in your templates.

Usage:

<ng-container *mat-sw-update="let available$; let ctrl = controller">
  <button (click)="ctrl.checkForUpdate()">Check for Update</button>
  <button (click)="ctrl.forceNotification()">
    {{ !!(available$ | async) ? 'Update available' : 'No update available' }}
  </button>
</ng-container>

ctrl.forceNotification will only show the notification, if an update is available.

The directive provides the following context:

interface MsuDirectiveContext {
  $implicit: Observable<UpdateAvailableEvent>; // emits the update event when an update is available. Won't emit if no update is available.
  controller: {
    runOnAction: (response?: boolean) => void;
    forceNotification: () => void;
    checkForUpdate: () => void;
  };
}

If you call runOnAction without arguments it defaults to true.

Change behaviour

ngx-mat-sw-update aims to be quickly ready to use but also offer the possibility to adjust to your needs.

To achieve this the library has an abstract MatSwUpdate at its core. It offers a simple API to change individual parts of the update process.
The flow is as follows:

With the separate doShow method you can decide, based on the update data, if you want to show a notification (for example if it's a crucial update). If you always want to show the notification just return true.

To show different messages based on the update data, you have to write a custom implementation of MsuSnackBar or MsuDialog. See i18n and the appData section on the angular.io page.

Using custom implementations

To use a custom implementation simply provide it in your core module, like above.

@NgModule({  
  imports: [  
    ServiceWorkerModule.register('ngsw-worker.js', {enabled: environment.production}),
    MatSnackBarModule
  ],
  providers: [
    {
      provide: MatSwUpdate,
      useClass: MyCustomMsu
    }
  ]
})  
export class AppModule {  
  constructor(matUpdates: MatSwUpdate) { // this can stay the same 
    matUpdates.checkForUpdate();  
  }  
}  

You have to inject certain dependencies in the base class. Example for MsuSnackBar:

export class MyCustomMsu extends MsuSnackBar {
  constructor(updates: SwUpdate,
              snackBar: MatSnackBar) {
    super(updates, snackBar);
  }
  // ...

Test notification

Usually you can't properly test Service Worker updates with ng serve or ng serve --prod. To check if your notification looks fine, you can provide the included SwUpdateMock class for SwUpdate. Every time you call checkForUpdate on MatSwUpdate an update will be found, thus triggering the flow. This will also work in dev mode!

providers: [
  { provide: SwUpdate, useClass: SwUpdateMock },
  // ...
]

i18n

As there are many different ways to realize i18n in your app, the library does not to enforce any particular way so that you don't end up with multiple strategies. Currently only an english version exists: MsuSnackBarEn and MsuDialogEn.

To use custom translations and messages, you have to create your own subclass of MsuSnackBar, MsuDialog or MatSwUpdate. Both MsuSnackBar and MsuDialog have an abstract method to change the text.

MsuSnackBar

getTranslation(data: UpdateAvailableEvent): { description: string, reloadBtn: string } → return an object with the snackbar text and the text for the reload button

MsuDialog

getDialogInput(data: UpdateAvailableEvent): DialogInput → return an object with the title, message, reload button and cancel button label

Class Overview

Here's an overview over all contained classes and at what point which methods are implemented.

:heavy_check_mark: = method is implemented

:x: = method is abstract