vue-sse
    TypeScript icon, indicating that this package has built-in type declarations

    2.5.0 • Public • Published

    VueSSE

    GitHub issues license

    VueSSE enables effortless use of Server-Sent Events by providing a high-level interface to an underlying EventSource.

    Install

    # npm
    npm install --save vue-sse
    
    # OR yarn
    yarn add vue-sse
    // in main.js
    import VueSSE from 'vue-sse';
    
    // using defaults
    Vue.use(VueSSE);
    
    // OR specify custom defaults (described below)
    Vue.use(VueSSE, {
      format: 'json',
      polyfill: true,
      url: '/my-events-server',
      withCredentials: true,
    });

    Quickstart

    this.$sse.create('/my-events-server')
      .on('message', (msg) => console.info('Message:', msg))
      .on('error', (err) => console.error('Failed to parse or lost connection:', err))
      .connect()
      .catch((err) => console.error('Failed make initial connection:', err));

    Usage

    Clients can be created from the Vue object via Vue.$sse.create(...) or from within components via this.$sse.create(...)

    All of the following are valid calls to create a client:

    • this.$sse.create('/your-events-endpoint') to connect to the specified URL without specifying any config
    • this.$sse.create({ url: '/your-events-endpoint', format: 'json' }) will automatically parse incoming messages as JSON
    • this.$sse.create({ url: '/your-events-endpoint', withCredentials: true }) will set CORS on the request

    Once you've created a client, you can add handlers before or after calling connect(), which must be called.

    Configuration

    $sse.create accepts the following config options when installing VueSSE via Vue.use and when calling $sse.create.

    Option Type Description Default
    format "plain" | "json" | (event: MessageEvent) => any Specify pre-processing, if any, to perform on incoming messages. Messages that fail formatting will emit an error. "plain"
    url string The location of the SSE server. ""
    withCredentials boolean Indicates if CORS should be set to include credentials. false
    polyfill boolean Include an EventSource polyfill for older browsers. false
    forcePolyfill boolean Forces the EventSource polyfill to always be used over native. false
    polyfillOptions object Custom options to provide to the EventSource polyfill. Only used if forcePolyfill is true. null

    If $sse.create is called with a string, it must be the URL to the SSE server.

    Methods

    Once you've successfully connected to an events server, a client will be returned with the following methods:

    Name Description
    connect(): Promise Connects to the server. Must be called.
    on(event: string, (data: any) => void): SSEClient Adds an event-specific listener to the event stream. The handler function receives the message as its argument (formatted if a format was specified), and the original underlying Event. For non-event messages, specify "" or "message" as the event.
    once(event: string, (data: any) => void): SSEClient Same as on(...), but only triggered once.
    off(event: string, (data: any => void)): SSEClient Removes the given handler from the event stream. The function must be the same as provided to on/once.
    on('error', (err) => void): SSEClient Allows your application to handle any errors thrown, such as loss of server connection and pre-processing errors.
    disconnect(): void Closes the connection. The client can be re-used by calling connect(). Must be called! (Usually, in the beforeDestroy of your component.)

    Properties

    Name Type Description
    source EventSource Returns the underlying EventSource.

    Cleanup

    Every connection must be disconnected when the component is destroyed. There are two ways to achieve this:

    1. Call disconnect() on the client during beforeDestroy, or
    2. Add the following option to your component to have them automatically closed for you during beforeDestroy:
    export default {
        name: 'my-component',
        data() { /* ... */ },
        // ...
        sse: {
            cleanup: true,
        },
        // ...
    }

    Vue 3

    This plugin works the same in both Vue 2 and 3. The Composition API is not yet supported.

    Example

    An example project is provided at tserkov/vue-sse-example.

    Kitchen Sink

    <template>
      <div>
        <p
          v-for="(message, idx) in messages"
          :key="idx"
        >{{ message }}</p>
      </div>
    </template>
    
    <script>
    // We store the reference to the SSE client out here
    // so we can access it from other methods
    let sseClient;
    
    export default {
      name: 'sse-test',
      data() {
        return {
          messages: [],
        };
      },
      mounted() {
        sseClient = this.$sse.create({
          url: '/your-events-server',
          format: 'json',
          withCredentials: true,
          polyfill: true,
        });
    
        // Catch any errors (ie. lost connections, etc.)
        sseClient.on('error', (e) => {
          console.error('lost connection or failed to parse!', e);
    
          // If this error is due to an unexpected disconnection, EventSource will
          // automatically attempt to reconnect indefinitely. You will _not_ need to
          // re-add your handlers.
        });
    
        // Handle messages without a specific event
        sseClient.on('message', this.handleMessage);
    
        // Handle 'chat' messages
        sseClient.on('chat', this.handleChat);
    
        // Handle once for a ban message
        sseClient.once('ban', this.handleBan);
    
        sseClient.connect()
          .then(sse => {
            console.log('We\'re connected!');
    
            // Unsubscribes from event-less messages after 7 seconds
            setTimeout(() => {
              sseClient.off('message', this.handleMessage);
              console.log('Stopped listening to event-less messages!');
            }, 7000);
    
            // Unsubscribes from chat messages after 14 seconds
            setTimeout(() => {
              sse.off('chat', this.handleChat);
              console.log('Stopped listening to chat messages!');
            }, 14000);
          })
          .catch((err) => {
            // When this error is caught, it means the initial connection to the
            // events server failed.  No automatic attempts to reconnect will be made.
            console.error('Failed to connect to server', err);
          });
      },
      methods: {
        handleBan(banMessage) {
          // Note that we can access properties of message, since our parser is set to JSON
          // and the hypothetical object has a `reason` property.
          this.messages.push(`You've been banned! Reason: ${banMessage.reason}`);
        },
        handleChat(message) {
          // Note that we can access properties of message, since our parser is set to JSON
          // and the hypothetical object has these properties.
          this.messages.push(`${message.user} said: ${message.text}`);
        },
        handleMessage(message, lastEventId) {
          console.warn('Received a message w/o an event!', message, lastEventId);
        },
      },
      beforeDestroy() {
        // Make sure to close the connection with the events server
        // when the component is destroyed, or we'll have ghost connections!
        sseClient.disconnect();
    
        // Alternatively, we could have added the `sse: { cleanup: true }` option to our component,
        // and the SSEManager would have automatically disconnected during beforeDestroy.
      },
    };
    </script>

    Install

    npm i vue-sse

    DownloadsWeekly Downloads

    1,097

    Version

    2.5.0

    License

    MIT

    Unpacked Size

    206 kB

    Total Files

    12

    Last publish

    Collaborators

    • tserkov