Stream

evlog ships a stream primitive so any local consumer can subscribe to wide events without re-implementing a drain. There are two layers, building on each other:

• In-process bus: createStreamDrain(), the canonical pub/sub. Sync listeners, async iterators, ring-buffered replay.
• Network bridge: startStreamServer(), an opt-in HTTP mini-server that exposes the in-process bus over Server-Sent Events for browsers, CLIs, or external devtools.

In-process bus

createStreamDrain() is just a drain. Register it on the evlog drain hook and subscribe to events as they're emitted: no HTTP, no serialization, no extra hops.

import { createStreamDrain } from 'evlog/stream'

const stream = createStreamDrain({ buffer: 200 })

nitroApp.hooks.hook('evlog:drain', stream.drain)

const off = stream.subscribe((event) => {
  if (event.level === 'error') notify(event)
})
off()

for (const past of stream.recent()) {
  bootstrap(past)
}
for await (const event of stream.events()) {
  bootstrap(event)
}

Options

stream.drain(events) accepts either a single event or a batch. stream.recent() returns a snapshot of the buffered events (oldest first, most recent last) for ad-hoc inspection or to seed a UI panel.

Network bridge: stream server

startStreamServer() boots a tiny node:http server in the same process as your app, on its own ephemeral port, and exposes the in-process bus over Server-Sent Events. Any consumer (browser tab, CLI, Tauri/Electron devtool) can subscribe, and your application API is untouched.

What boots up

When you opt in, evlog calls startStreamServer() and:

1. Picks an ephemeral free port (or the one you specify)
2. Spins a tiny node:http server on 127.0.0.1 (or your host)
3. Writes the discovered URL to .evlog/stream.url
4. Prints a one-line banner in the server console
5. Hooks the in-process stream drain into the evlog pipeline
6. Exposes GET / for the SSE stream and GET /info for handshake metadata

On shutdown (SIGINT / SIGTERM / process exit) the server cleans up listeners and removes the URL file.

Per-framework opt-in

export default defineNuxtConfig({
  modules: ['evlog/nuxt'],
  evlog: {
    stream: true,
    // or: stream: { port: 4444, token: process.env.EVLOG_STREAM_TOKEN }
  },
})

import { defineStreamedInstrumentation } from 'evlog/next/stream'

export const { register } = defineStreamedInstrumentation({
  stream: true,
})

import { startStreamServer } from 'evlog/stream'

if (process.env.NODE_ENV !== 'production' && process.env.EVLOG_STREAM === '1') {
  const { drain } = await startStreamServer()
  // Plug `drain` into the evlog drain hook for your framework
}

The Hono / Express / Fastify integrations don't need a "feature PR", because startStreamServer() is orthogonal to your framework. You boot it once and connect its drain to the evlog pipeline like any other drain.

Discovery

The mini-server runs on a random port, so any consumer must discover it.

http://127.0.0.1:53942

Read directly from disk:

import { readFile } from 'node:fs/promises'

const url = (await readFile('.evlog/stream.url', 'utf-8')).trim()

Or, for same-origin browser tabs in a Nuxt app, hit the discovery route:

const { url } = await fetch('/api/_evlog/stream-info').then(r => r.json())

Wire format

Every SSE message has the shape { evlog: '1', type, data }:

const { url } = await fetch('/api/_evlog/stream-info').then(r => r.json())
const es = new EventSource(url)

es.onmessage = (msg) => {
  const { type, data } = JSON.parse(msg.data)
  if (type === 'event') events.push(data)
}

Auth + CORS

Going further

• FS reader: replay or tail historic NDJSON files (cross-process, survives restarts)
• Consumer recipes: build a minimal devtool, pipe to curl + jq, replay history then go live