Usage

Example

In order to subscribe to an SSE endpoint, you need to call useEventSource. After you have it, you can add listeners to it. Here's a simple example:

import { useEventSource, useEventSourceListener } from "@react-nano/use-event-source";

function MyComponent() {
    const [messages, addMessages] = useReducer(messageReducer, []);
    
    const [eventSource, eventSourceStatus] = useEventSource("api/events", true);
    useEventSourceListener(eventSource, ['update'], evt => {
        addMessages(JSON.parse(evt.data));
    }, [addMessages]);

    return (
        <div>
            {eventSourceStatus === "open" ? null : <BusyIndicator />}
            {messages.map((msg) => <div>{msg.text}</div>)}
        </div>
    );
}

useEventSource

This describes the entire API of the useEventSource hook:

// Create an EventSource
function useEventSource(
    // The url to fetch from
    url: string,
    // Send credentials or not
    withCredentials?: boolean,
    // Optionally override the EventSource class (for example with a polyfill)
    ESClass: EventSourceConstructor = EventSource
) => [
    // The generated EventSource.. on first call, it will be null.
    EventSource | null,
    // The status of the connection can be used to display a busy indicator, error indicator, etc.
    EventSourceStatus
];

type EventSourceStatus = "init" | "open" | "closed" | "error";

useEventSourceListener

This describes the entire API of the useEventSourceListener hook:

// Add a listener to the EventSource
function useEventSourceListener(
    // The EventSource from the above hook
    source: EventSource | null,
    // The event types to add the listener to
    types: string[],
    // A listener callback (use e.type to get the event type)
    listener: (e: EventSourceEvent) => void,
    // If one of the dependencies changes, the listener will be re-added to the event types.
    dependencies: any[] = []
) => void;