Network Guard

@devath/network-guard helps Angular applications detect when a user leaves a trusted (for example in-office or VPN) network. It validates connectivity against an internal endpoint and surfaces a warning banner whenever requests start failing or the browser reports that it is offline.

Key features

• Lightweight service that listens for online/offline, connection, and visibility changes.
• Configurable validation endpoint, retry strategy, and polling cadence.
• Standalone warning banner component with retry and dismiss actions.
• Strongly typed state stream so you can build your own UX if you prefer.

Installation

npm install @devath/network-guard

The package is published as an Angular library targeting Angular 18.

Quick start

1. Provide a configuration that points to an endpoint only reachable from the trusted network (a simple /ping route works).

import { provideNetworkGuardConfig } from '@devath/network-guard';

bootstrapApplication(AppComponent, {
  providers: [
    provideNetworkGuardConfig({
      validationUrl: 'https://intranet.example.com/ping',
      timeoutMs: 3000,
      retryAttempts: 2,
    }),
  ],
});

2. Drop the banner component somewhere near the root of your application shell.

<network-guard-banner
  title="You left the secure network"
  message="Reconnect to the corporate VPN to keep working securely."
  [showRetry]="true"
></network-guard-banner>

The banner becomes visible when the service labels the connection as untrusted. Users can retry the validation or dismiss the alert locally until the connection becomes trusted again.

Service API

The NetworkGuardService exposes two main entry points:

• state$ (alias stateChanges): observable stream of NetworkGuardState values.
• checkNow(trigger?: NetworkGuardTrigger): manually force a validation cycle, e.g. when the user taps a "Retry" button.

NetworkGuardState includes the current status ("unknown" | "checking" | "trusted" | "untrusted"), whether the browser is online, the trigger that caused the latest check, timestamps, and an optional failure payload.

Configuration

Provide NETWORK_GUARD_CONFIG with the options you need:

| Option | Description | Default | | --- | --- | --- | | validationUrl | URL that is only reachable on the trusted network. | /network-guard/ping | | method | HTTP method for the validation call. | "HEAD" | | timeoutMs | Abort the request after this many milliseconds. | 4000 | | retryAttempts | Additional attempts after the initial request. | 1 | | retryDelayMs | Delay between retries (ms). | 750 | | pollIntervalMs | Optional recurring validation interval. | Disabled | | checkOnStart | Run a validation immediately on service creation. | true | | warnOnOffline | Treat browser offline events as untrusted. | true | | listenForConnectionChanges | Subscribe to navigator.connection changes when available. | true | | listenForVisibilityChange | Re-check when the tab becomes visible. | true | | fetch | Custom fetch implementation (useful for testing). | Browser fetch | | requestInit | Additional options merged into the fetch request. | {} |

Custom UI

Prefer to show a custom warning banner or integrate with an existing notification center? Inject the service and subscribe to state$:

@Component({
  selector: 'app-shell',
  templateUrl: './shell.component.html',
})
export class ShellComponent {
  readonly networkState$ = inject(NetworkGuardService).state$;
}

<div *ngIf="(networkState$ | async)?.status === 'untrusted'" class="warning">
  Your connection is no longer trusted. Please reconnect.
</div>

Building & publishing

ng build network-guard
cd dist/network-guard
npm publish --access public

Run ng test network-guard to execute the unit tests.