Angular Server-Sent Events Client

Common errors

• Error: NG0201: No provider for SseClient!

  cause 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.

  cause 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'.

  cause 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; /* ... */ }`.

Warnings

• breaking Major 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.
• gotcha When `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.
• gotcha If `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`.
• gotcha SSE 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.

Install

• npm install ngx-sse-client npm
• yarn add ngx-sse-client yarn
• pnpm add ngx-sse-client pnpm

Imports

• SseClient
  wrong:

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

  correct:

  import { SseClient } from '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
  wrong:

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

  correct:

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

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

Quickstart

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.');
      }
    });
  }
}