Registry / http-networking / ngx-sse-client

ngx-sse-client

library21.0.0jsnpmunverified

ngx-sse-client is an Angular library providing a robust client for Server-Sent Events (SSE), designed as an alternative to the native `EventSource` API. Currently at stable version 21.0.0, this package typically releases new major versions in alignment with Angular's own major releases, ensuring compatibility with the latest Angular ecosystem. Its key differentiator lies in leveraging Angular's `HttpClient` for SSE stream requests, which enables seamless integration with `HttpInterceptor` for authentication, logging, and error handling. It also supports flexible HTTP methods (e.g., POST instead of just GET) and exposes event streams as RxJS Observables, aligning with Angular's reactive programming paradigm. This allows for more advanced control and error management compared to traditional `EventSource` implementations, which lack interceptor support and direct Observable integration.

http-networking web-framework

npm install ngx-sse-client

github ↗package ↗

INSTALL

IMPORT

SIG · NGX-SSE-CLIENT

ngx-sse-client

http-networkingjavascriptv21.0.0

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

SseClient

✓ import { SseClient } from 'ngx-sse-client';

✗ const SseClient = require('ngx-sse-client');

This is an Angular service, primarily used with ES Modules and TypeScript. CommonJS `require` is not supported for Angular libraries.

SseOption

✓ import { SseOption } from 'ngx-sse-client';

Interface for configuring the SSE stream. Not directly injected but used for type declarations.

HttpHeaders

✓ import { HttpHeaders } from '@angular/common/http';

✗ import { HttpHeaders } from 'ngx-sse-client';

HttpHeaders is part of Angular's HttpClient module, not `ngx-sse-client` itself. It is commonly used when making SSE requests with custom headers.

Demonstrates injecting the `SseClient` service, subscribing to an SSE stream with custom options (keep-alive, reconnection delay, event response type), including HTTP headers for authorization, and using a POST method. It also shows handling both `MessageEvent` and `ErrorEvent` responses within the subscription.

import { Component, OnInit } from '@angular/core'; import { HttpHeaders } from '@angular/common/http'; import { SseClient } from 'ngx-sse-client'; @Component({ selector: 'app-root', template: `<h1>SSE Stream Example</h1><p>Check console for events.</p>`, }) export class AppComponent implements OnInit { constructor(private sseClient: SseClient) {} ngOnInit(): void { const headers = new HttpHeaders().set('Authorization', `Basic YWRtaW46YWRtaW4=`); // Example of subscribing to an SSE stream with custom options and POST method this.sseClient.stream( '/api/subscribe', // Replace with your SSE endpoint { keepAlive: true, reconnectionDelay: 1_000, responseType: 'event' }, { headers }, 'POST' ).subscribe({ next: (event) => { if (event.type === 'error') { const errorEvent = event as ErrorEvent; console.error('SSE Error Event:', errorEvent.error, errorEvent.message); } else { const messageEvent = event as MessageEvent; console.info(`SSE Message (${messageEvent.type}):`, messageEvent.data); } }, error: (err) => { console.error('SSE Subscription Error:', err); }, complete: () => { console.log('SSE Stream Completed.'); } }); } }

Debug

Known issues

breakingMajor versions of `ngx-sse-client` are tightly coupled with specific Angular versions. Upgrading Angular often requires a corresponding `ngx-sse-client` major version upgrade, which can introduce breaking changes. For example, v21.0.0 requires Angular >=21.0.0.

fix

Always check the `peerDependencies` in `package.json` or the changelog for `ngx-sse-client` to ensure compatibility with your Angular version before upgrading. Upgrade `ngx-sse-client` to the major version that matches your Angular version.

affects: >=17.0.0

gotchaWhen `responseType` is set to `'text'`, the library will only return the message data. No errors will be propagated through the Observable's error channel or returned as `ErrorEvent` types within the stream, effectively suppressing error handling.

fix

For comprehensive error handling, especially during development or for robust applications, use `responseType: 'event'`. This allows you to differentiate between `MessageEvent` and `ErrorEvent` and react to stream errors. Only use `responseType: 'text'` if you are certain your server will not send error events or if you prefer to handle all stream interruptions as completion events.

affects: >=1.0.0

gotchaIf `keepAlive` is set to `true`, the SSE connection will automatically attempt to reconnect if it's closed (e.g., by timeout or completion). To explicitly terminate the stream, you *must* `unsubscribe` from the Observable. Failure to do so will result in continuous reconnection attempts, potentially consuming resources.

fix

Ensure you call `.unsubscribe()` on the `Subscription` object obtained from `sseClient.stream().subscribe()` when the component or service using it is destroyed or no longer needs the stream. For Angular components, this typically means implementing `ngOnDestroy`.

affects: >=1.0.0

gotchaSSE connections can be buffered by intermediate proxies or web servers like Nginx, leading to delayed delivery of events. This can negate the real-time benefits of SSE.

fix

Configure your proxy server (e.g., Nginx) to disable buffering for SSE endpoints. Common Nginx configurations include `proxy_buffering off;` and `proxy_set_header Connection '';` for the SSE location. Also, ensure your application server sends `X-Accel-Buffering: no` header.

affects: >=1.0.0

Errors

Common errors & fixes

Error: NG0201: No provider for SseClient!

The `SseClient` service has not been provided in your Angular application's module or component hierarchy.

fix

Add `SseClient` to the `providers` array in your `AppModule` (or a feature module where it's used) to make it injectable: `providers: [SseClient]`.

Expected 1-2 arguments, but got 4.

This error can occur if you are using an older version of `ngx-sse-client` where the `stream` method had fewer parameters, but your code is written for a newer version that accepts more arguments (e.g., HTTP method and request options).

fix

Ensure your `ngx-sse-client` version is up-to-date (currently v21.0.0 for Angular 21) and that your `stream` method call matches the signature of the installed version. You may need to update the library: `npm install ngx-sse-client@latest`.

Property 'type' does not exist on type 'unknown'.

When `responseType` is `'event'`, the `subscribe` callback receives an `Event` object, which needs to be type-asserted to `MessageEvent` or `ErrorEvent` to access specific properties like `data` or `message`.

fix

Use type guards or type assertions within your subscription callback to correctly infer the type of the event. For example: `if (event.type === 'error') { const errorEvent = event as ErrorEvent; /* ... */ } else { const messageEvent = event as MessageEvent; /* ... */ }`.

Upgrade

Version history

21.0.0latest on npm

Audit

Dependencies

@angular/commonrequiredPeer dependency for Angular-specific features like HttpClient and DI.

@angular/corerequiredPeer dependency for Angular core functionalities, including dependency injection and component lifecycle.

Agent activity

6 hits · last 30 days

node

Resources

githubhttps://github.com/marcospds/ngx-sse-client ↗

packagehttps://www.npmjs.com/package/ngx-sse-client ↗