remix-sse

Server Side Events (SSE) for Remix, made easy.

Features

• ✅ Zero-dependencies
• ✅ Small bundle
• ✅ Context for re-using event source connections across remix application
• ✅ supports multiple event types from a single emitter
• ✅ 100% typescript
• ✅ (experimental) Typed deserialization

Planned

• 👷 Topic support - pass a topic string to useSubscribe and only listen to events that match the topic
• 👷 Emitter type support - ensures the messages you are sending are in a format your hooks are expecting

Installation

npm i remix-sse

Documentation

See examples directory.

Quick Start

See basic example for more detail.

1. Setup your event source route, here it is called /routes/emitter.tsx for simplicity

Note: This MUST be a resource route, you cannot return a component from this route.

import { EventStream } from 'remix-sse'
export const loader: LoaderFunction = ({ request }) => {

  // Return the EventStream from your route loader
  return new EventStream(request, (send) => {
    // In the init function, setup your SSE Event source
    // This can be any asynchronous data source, that will send
    // events to the client periodically

    // Here we will just use a `setInterval`

    const interval = setInterval(() => {
      // You can send events to the client via the `send` function
      send('greeting', JSON.stringify({ hello: 'world'}))
    }, 1000)


    return () => {
      // Return a cleanup function
      clearInterval(interval)
    };
  });
};

Note: the first argument passed to the send function is the EventKey, this can be anything you want - but you will need to reference it again via useSubscribe.

1. Wrap your root.tsx with RemixSseProvider.

import { RemixSseProvider} from 'remix-sse/dist/client'


<RemixSseProvider>
  <Outlet />
</RemixSseProvider>

Note: v4 has temporarily broken the flat file structure we used to have ie. remix-sse/dist/client instead of remix-sse/client

1. Call the useEventSource to setup an EventSource in your browser

import { useEventSource } from 'remix-sse/dist/client'
useEventSource('/emitter');

1. Call useSubscribe from anywhere in your tree to begin listening to events emitted from the event source

// This value is a react state object, and will change everytime
// an event is emitted

// By default this is a string[]
const greeting = useSubscribe('/emitter', 'greeting')

// But you can return only the latest event as follows
const latestGreeting = useSubscribe('/emitter', 'greeting', {
  returnLatestOnly: true
})

// Or you can type the return by deserializing the event data
const typedGreeting = useSubscribe('/emitter', 'greeting', {
  returnLatestOnly: true,
  deserialize: (raw) => JSON.parse(raw) as Greeting
})

Deserialize

By default the data returned from useSubscribe is a string[]

You can pass a deserialize function to de-deserialize each event as it comes in.

Note: this feature is experimental and is subject to change.

See deserialize for more details.

useSubscribe options

Experimental options

These are currently being tested, and are subject to change at any point.

.