SuSiE

3.0.0 verified Sat Apr 25 auth: no javascript

Server-Sent Events plugin for hapi.js, allowing event streaming via h.event() with support for individual event objects and readable streams. Current stable version: 3.0.0. Works with Node >=8.9.0. Key differentiator: tight hapi integration, auto-stringification of objects, and automatic handling of reconnect via a built-in 'end' event. Ideal for real-time updates like notifications or live feeds.

Common errors

error Error: h.event is not a function ↓

cause susie plugin not registered before route handler or incorrect registration.

fix

Ensure await server.register(require('susie')); is called before defining routes.

error TypeError: Cannot destructure property 'susie' of ... ↓

cause Using named import syntax with require or import on susie.

fix

Use const susie = require('susie'); and pass it directly to server.register.

Warnings

gotcha Calling h.event(null) sends a final event named 'end' before closing the response. The client must listen for this event and close the EventSource to prevent automatic reconnect. ↓

fix On the client, listen for the 'end' event and call source.close().

gotcha Object mode streams: When passing a stream in objectMode, each chunk is JSON-stringified. Ensure client parses the data field as JSON if needed. ↓

fix On the client, use JSON.parse(event.data) if the data originated from an object.

breaking v3 drops support for hapi v16 and earlier; requires @hapi/hapi v17+ (Node >=8.9.0). ↓

fix Upgrade to @hapi/hapi v17+ and use async/await for server registration.

deprecated Using require('susie') returns a plugin object; the old require('susie').plugin pattern is deprecated but still works. ↓

fix Use require('susie') directly in server.register().

Install

npm install susie

yarn add susie

pnpm add susie

Imports

default

wrong

const { susie } = require('susie');

correct

const susie = require('susie');
await server.register(susie);

Requires CommonJS, as susie is a hapi plugin. No default export for ESM.

h.event()

wrong

import { event } from 'susie';

correct

// Decorated on toolkit after registration
handler: function (request, h) {
    return h.event({ data: 'hello' });
}

h.event() is not a standalone import; it's added to the hapi response toolkit after registering the plugin.

plugin registration

wrong

server.register({ register: susie, options: {} });

correct

await server.register({ plugin: require('susie'), options: {} });

Use the standard hapi plugin pattern. As of hapi v17+, registration must be awaited.

Quickstart

Registers the susie plugin and creates an SSE endpoint that sends 5 events with 1-second intervals, then closes the connection with an 'end' event.

const Hapi = require('@hapi/hapi');
const susie = require('susie');

const start = async () => {
    const server = Hapi.server({ port: 3000 });
    await server.register(susie);

    server.route({
        method: 'GET',
        path: '/events',
        handler: (request, h) => {
            const response = h.event({ id: 1, data: 'hello' });
            let count = 1;
            const interval = setInterval(() => {
                count++;
                h.event({ id: count, data: `message ${count}` });
                if (count >= 5) {
                    clearInterval(interval);
                    h.event(null); // sends 'end' event and closes
                }
            }, 1000);
            return response;
        }
    });

    await server.start();
    console.log('Server running on', server.info.uri);
};

start();