use-event-source

Reactive Server-Sent Events stream with typed, per-event decoding.

Minimal setup

Use a Vue 3.5+ project with Vue SFC compilation configured (see Vite+ integration).

vp install @vizejs/composable

Import the entry directly. Call lifecycle-bound utilities inside <script setup> so cleanup follows the component scope; consult the runtime contract for this entry's SSR and hydration behavior.

import { useEventSource } from "@vizejs/composable/use-event-source";

Try it

Follow server-sent events

Connect to a text/event-stream endpoint and show its connection state.

Open the interactive example

What to observe: Connect opens the stream; build lines arrive one per second until Build finished. Disconnect closes it.

The docs have no server, so host supplies a class that replays a build log; drop it in your app. Pass events and parse for named events, and autoReconnect to retry with backoff.

Compare the initial and interacted states

Copy the example

Save this complete SFC in your Vue project. Its public imports and source are the same ones executed in the preview.

<script setup lang="ts">
import { useEventSource } from "@vizejs/composable/use-event-source";

// The docs have no server, so this class replays a build log. In your app, drop `host`
// and point the URL at an endpoint that streams `text/event-stream`.
class ReplayedBuildLog extends EventTarget {
  readyState = 0;

  constructor(_url: string) {
    super();
    queueMicrotask(() => {
      this.readyState = 1;
      this.dispatchEvent(new Event("open"));
    });
    ["Compiling 42 files", "Type checking", "Build finished"].forEach((line, index) => {
      setTimeout(
        () => {
          if (this.readyState === 1)
            this.dispatchEvent(new MessageEvent("message", { data: line }));
        },
        (index + 1) * 1000,
      );
    });
  }

  close() {
    this.readyState = 2;
  }
}

const { status, data, open, close } = useEventSource("/api/build-events", {
  host: ReplayedBuildLog,
  immediate: false,
  autoReconnect: false,
});
</script>

<template>
  <div class="composable-example">
    <p>Follow server-sent build events and show the connection state.</p>
    <div class="example-actions">
      <button type="button" :disabled="status !== 'closed'" @click="() => open()">Connect</button>
      <button type="button" :disabled="status === 'closed'" @click="() => close()">
        Disconnect
      </button>
    </div>
    <output aria-live="polite">Status: {{ status }}{{ data ? ` · ${data}` : "" }}</output>
  </div>
</template>

Runtime contract

API

useEventSource

Reactive Server-Sent Events stream with typed, per-event decoding. Every subscribed event is decoded by its parser (raw text by default) and exposed as a discriminated message, plus data/event/lastEventId shortcuts and typed on() handlers. Transient drops use the browser's native reconnection; autoReconnect additionally reopens streams the browser closed for good. The stream and timers are released when the owning reactive scope stops (the caller owns close() outside a scope). Server rendering never connects and reports "closed".

function useEventSource<Events extends EventSourceEventMap = { message: string }>( url: MaybeRefOrGetter<string | URL | null | undefined>, ...[options]: unknown extends EventSourceParseRequirement<Events> ? [options?: UseEventSourceOptions<Events>] : [options: UseEventSourceOptions<Events> & EventSourceParseRequirement<Events>] ): EventSourceControls<Events>

const feed = useEventSource<{ price: number; notice: string }>("/stream", {
  events: ["price", "notice"],
  parse: { price: (raw) => Number(raw) },
});
feed.on("price", (price) => chart.push(price));

Types

EventSourceLike

Minimal EventSource instance used by useEventSource.

EventSourceReconnectOptions

Options for reconnecting streams the browser gave up on.

UseEventSourceOptions

Options for useEventSource.

EventSourceControls

Reactive state and controls returned by useEventSource.