Working with Server-Sent Events

Oct 29, 2026

HTTP , Web Development , React , Server-Sent Events , SSE , Typescript

What Is Server-Sent Events?

Displaying the progress of long-running operations is a common requirement in modern web applications. While polling can be used to display intermediate progress updates, it generates repeated requests and may not reflect changes immediately.

Server-Sent Events (SSE) is a simple yet powerful alternative that allows the server to stream updates to the client over a single HTTP connection.

In this article, we’ll explore how SSE works by building a deployment pipeline simulation using Next.js. We’ll cover two ways of implementing SSE in the frontend and compare their differences.

See the live demo.
See the source code.

SSE vs Other Approaches

SSE is just one way to deliver updates from a server to a client. Other approaches, such as polling and WebSockets, offer different trade-offs depending on the use case.

Feature	Polling	SSE	WebSockets
Connection	A new HTTP request for each poll	Persistent HTTP connection	Persistent connection
How it works	Client periodically requests updates	Server pushes events to the client	Supports messages in both directions
Communication protocol	HTTP	HTTP	WebSocket protocol
Implementation complexity	Low	Low to moderate	Moderate to high
Best suited for	Periodically refreshed data	One-way server-to-client updates	Bidirectional, real time communication
Example use cases	Refreshing a dashboard every 30 seconds	Deployment progress, notifications, live logs	Chat, multiplayer games, collaborative editing

The main advantage of SSE is its simplicity. When an application primarily needs to receive updates from the server, SSE provides a straightforward solution without requiring the additional complexity of a bidirectional communication protocol like WebSockets.

How SSE Works

Establishing the connection

SSE uses an HTTP connection to stream events from the server to the client. The client sends a request to an endpoint, and the server responds with a Content-Type: text/event-stream header to indicate that the response contains a stream of events.

Once the connection is established, the server can keep it open and send events as they become available, without requiring a new request for each one.

The SSE message format

SSE uses a simple stream of text data. Each event consists of one or more fields, with a blank line marking the end of the message. Lines beginning with a colon are comments.

The client reads the response stream and processes each event according to the SSE format. The way this happens depends on the API used to consume the stream.

An SSE message looks like this:

1
event: progress
2
id: 42
3
data: {"progress":60}
4
retry: 3000
5

Let’s break it down:

event: Optional. Specifies the event type. If omitted, it defaults to message.
data: Contains the event payload.
id: Optional. Assigns an identifier to the event. It can be used to track the last received event and sending it when reconnecting, allowing the server to resume the stream or replay missed events.
retry: Optional. Specifies the reconnection delay, in milliseconds, for clients that support automatic reconnection.
Blank line: Marks the end of an event and signals that it can be dispatched to the client.

Note: the server can periodically send comment lines, such as : keep-alive, to help prevent some intermediaries from closing an idle connection due to timeouts. These comments are ignored by the client and do not trigger application events.

Note: SSE does not require the payload to be JSON, however, it’s common to use it when the application needs to transmit structured data.

Closing the connection

An SSE stream stays open until it is closed by the client or server, or interrupted by a network failure. Each side should handle these situations appropriately.

Implementing the SSE endpoint

To see how SSE works in practice, let’s implement an endpoint using a Next.js Route Handler.

The endpoint will simulate a pipeline progressing through several stages, sending updates to the client as each stage completes. Instead of returning a single JSON response, it will stream a sequence of Server-Sent Events over an HTTP connection.

1
const PIPELINE = [
2
  'Cloning',
3
  'Installing dependencies',
4
  'Linting',
5
  'Testing',
6
  'Building',
7
  'Deploying',
8
] as const
9

10
type Status = 'pending' | 'running' | 'completed' | 'failed' | 'skipped'
11

12
type Step = { name: (typeof PIPELINE)[number]; status: Status }
13

14
type Snapshot = Step[]
15

16
type Outcome = 'success' | 'error'
17

18
// Defines the index of the Step that will fail.
19
const FAIL_STEP_INDEX = PIPELINE.indexOf('Testing')
20

21
// Waits for a step to complete.
22
const waitForStep = () =>
23
  new Promise<void>((resolve) => {
24
    setTimeout(resolve, 1800)
25
  })
26

27
// Formats a Pipeline Snapshot as a named SSE event.
28
// SSE fields are separated by newlines, and a blank line ends each event.
29
const encodeRunEvent = (snapshot: Snapshot) =>
30
  `event: run\ndata: ${JSON.stringify(snapshot)}\n\n`
31

32
// Creates a Snapshot of the Pipeline.
33
const getPipelineSnapshot = (completedCount: number): Snapshot =>
34
  PIPELINE.map((name, index) => {
35
    if (index < completedCount) {
36
      return { name, status: 'completed' }
37
    }
38

39
    if (index === completedCount) {
40
      return { name, status: 'running' }
41
    }
42

43
    return { name, status: 'pending' }
44
  })
45

46
// Creates the error Terminal Snapshot.
47
const getErrorTerminalSnapshot = (): Snapshot =>
48
  PIPELINE.map((name, index) => {
49
    if (index < FAIL_STEP_INDEX) {
50
      return { name, status: 'completed' }
51
    }
52
    if (index === FAIL_STEP_INDEX) {
53
      return { name, status: 'failed' }
54
    }
55
    return { name, status: 'skipped' }
56
  })
57

58
// Next.js Route Handler that streams Snapshots as SSE.
59
export function GET(request: Request): Response {
60
  // Extracts the outcome parameter from the request URL.
61
  const outcomeParam = new URL(request.url).searchParams.get('outcome')
62
  if (outcomeParam !== 'success' && outcomeParam !== 'error') {
63
    return new Response(null, { status: 400 })
64
  }
65
  const outcome: Outcome = outcomeParam
66

67
  // Converts strings into bytes, which the response stream requires.
68
  const encoder = new TextEncoder()
69

70
  // Creates a stream that produces data incrementally.
71
  const stream = new ReadableStream({
72
    async start(controller) {
73
      // Serializes a Snapshot and adds it to the response stream.
74
      const enqueue = (snapshot: Snapshot) => {
75
        controller.enqueue(encoder.encode(encodeRunEvent(snapshot)))
76
      }
77

78
      // Resolves when the client disconnects. Raced against the Step delay
79
      // so the stream can close without waiting out the timeout.
80
      const handleAbort = new Promise<void>((resolve) => {
81
        // Already disconnected, resolve immediately.
82
        if (request.signal.aborted) {
83
          resolve()
84
          return
85
        }
86
        request.signal.addEventListener('abort', () => resolve(), {
87
          once: true,
88
        })
89
      })
90

91
      // Determines the index of the last running Step based on the
92
      // Outcome.
93
      const lastRunningIndex =
94
        outcome === 'error' ? FAIL_STEP_INDEX : PIPELINE.length - 1
95

96
      // Send the first Snapshot of the Run, then a Snapshot after each
97
      // Step transition. The last loop iteration still has a running Step.
98
      // The Terminal Snapshot is sent after the loop.
99
      for (
100
        let completedCount = 0;
101
        completedCount <= lastRunningIndex;
102
        completedCount++
103
      ) {
104
        // Sends a Snapshot of the Pipeline.
105
        enqueue(getPipelineSnapshot(completedCount))
106

107
        // Waits before the next Snapshot, but aborts if the request
108
        // is aborted.
109
        await Promise.race([waitForStep(), handleAbort])
110
        if (request.signal.aborted) {
111
          controller.close()
112
          return
113
        }
114
      }
115

116
      // Sends the Terminal Snapshot.
117
      enqueue(
118
        outcome === 'error'
119
          ? getErrorTerminalSnapshot()
120
          : getPipelineSnapshot(PIPELINE.length),
121
      )
122

123
      // Signals that no more events will be sent.
124
      controller.close()
125
    },
126
  })
127

128
  // Returns the stream with headers identifying it as an SSE response.
129
  // The Content-Type header identifies the response as an SSE stream.
130
  // The Cache-Control header discourages caching and intermediary
131
  // transformations that could interfere with streaming.
132
  return new Response(stream, {
133
    headers: {
134
      'Content-Type': 'text/event-stream; charset=utf-8',
135
      'Cache-Control': 'no-cache, no-transform',
136
    },
137
  })
138
}

There are three key parts to this implementation:

Formatting the events: The encodeRunEvent function converts a pipeline snapshot into an SSE event. The event field identifies the event type as run, while the data field contains the pipeline state serialized as JSON. The blank line at the end is important: it marks the end of the event, allowing the client to recognize when a complete message has arrived.
Streaming the updates: The ReadableStream lets the server produce data incrementally. Each call to controller.enqueue() adds another update to the stream, which the client can consume as data arrives. In this simulation, the server sends an initial snapshot and then sends another every 1.8 seconds. Each snapshot represents the entire pipeline state, including completed, running, and pending stages.
Ending the stream: After sending the final snapshot, in which every stage is completed, the server calls controller.close() to signal that no more data will be produced. Notice that the final event and the closing of the stream serve different purposes: the event communicates the pipeline’s final state, while closing the stream signals the end of the response.

Consuming SSE in the frontend

With the backend in place, let’s connect the frontend to the stream and use the events to update the UI. We’ll cover two different approaches to consume the SSE stream: the native EventSource API and the Fetch API.

Using EventSource

EventSource is the browser’s built-in API for consuming SSE. It opens a persistent HTTP connection and dispatches incoming events to registered listeners.

1
'use client'
2

3
import { useEffect, useRef, useState } from 'react'
4

5
const PIPELINE = [
6
  'Cloning',
7
  'Installing dependencies',
8
  'Linting',
9
  'Testing',
10
  'Building',
11
  'Deploying',
12
] as const
13

14
type Status = 'pending' | 'running' | 'completed' | 'failed' | 'skipped'
15

16
type Step = { name: (typeof PIPELINE)[number]; status: Status }
17

18
type Snapshot = Step[]
19

20
// Used to determine the outcome of a Run.
21
type Outcome = 'success' | 'error'
22

23
// Idle Snapshot: Every Step is pending.
24
const IDLE_SNAPSHOT: Snapshot = PIPELINE.map((name) => ({
25
  name,
26
  status: 'pending',
27
}))
28

29
// A Run is Terminal once all Steps have one of these statuses.
30
const TERMINAL_STATUSES: Status[] = ['completed', 'failed', 'skipped']
31
const isTerminalSnapshot = (snapshot: Snapshot) =>
32
  snapshot.length > 0 &&
33
  snapshot.every((step) => TERMINAL_STATUSES.includes(step.status))
34

35
// SseEventSource component
36
const SseEventSource = () => {
37
  const [steps, setSteps] = useState<Snapshot>(IDLE_SNAPSHOT)
38
  const [inProgress, setInProgress] = useState(false)
39

40
  // Keep the instance so we can close() it on unmount, when the current
41
  // Run becomes Terminal, and on error.
42
  const eventSourceRef = useRef<EventSource | null>(null)
43

44
  // Event listeners close over the render that created them, so
45
  // `inProgress` state would be stale inside onerror. The ref is the
46
  // live "a current Run" flag those listeners can read.
47
  const inProgressRef = useRef(false)
48

49
  // Close the EventSource and mark that there is no current Run. Used
50
  // when the current Run becomes Terminal and on error.
51
  const stopRun = () => {
52
    eventSourceRef.current?.close()
53
    eventSourceRef.current = null
54
    inProgressRef.current = false
55
    setInProgress(false)
56
  }
57

58
  // On unmount, close the EventSource so the browser drops the SSE
59
  // connection.
60
  useEffect(() => {
61
    return () => {
62
      eventSourceRef.current?.close()
63
    }
64
  }, [])
65

66
  // Start a new Run. This function is called when the user clicks the
67
  // Simulate Success or Simulate Error button.
68
  const startRun = (outcome: Outcome) => {
69
    // Guard against a second click.
70
    if (inProgressRef.current) {
71
      return
72
    }
73

74
    inProgressRef.current = true
75
    setInProgress(true)
76

77
    // Start the SSE connection by creating an EventSource.
78
    const eventSource = new EventSource(`/api/run?outcome=${outcome}`)
79
    eventSourceRef.current = eventSource
80

81
    // Named events: the server sends `event: run`, so we listen for "run".
82
    eventSource.addEventListener('run', (event: MessageEvent<string>) => {
83
      const snapshot = JSON.parse(event.data) as Snapshot
84
      setSteps(snapshot)
85

86
      if (!isTerminalSnapshot(snapshot)) {
87
        return
88
      }
89

90
      // EventSource reconnects automatically when the server closes the
91
      // stream. We saw a Terminal Snapshot, so close it ourselves instead
92
      // of letting it retry GET /api/run.
93
      stopRun()
94

95
      if (outcome === 'error') {
96
        console.log('Testing failed.')
97
      } else {
98
        console.log('Every Step completed.')
99
      }
100
    })
101

102
    eventSource.onerror = () => {
103
      stopRun()
104

105
      // onerror fires for real network drops *and* after we close() a
106
      // Terminal Run. Use the ref to tell those apart: if we already
107
      // marked the Run Terminal, ignore this.
108
      if (!inProgressRef.current) {
109
        return
110
      }
111

112
      // If there was still a current Run, the connection died mid-Run.
113
      // Return to Idle.
114
      setSteps(IDLE_SNAPSHOT)
115

116
      console.log('Connection lost. Please try again.')
117
    }
118
  }
119

120
  return (
121
    <div className="flex flex-col items-start gap-4">
122
      <button
123
        type="button"
124
        disabled={inProgress}
125
        onClick={() => startRun('success')}
126
      >
127
        Simulate success
128
      </button>
129
      <button
130
        type="button"
131
        disabled={inProgress}
132
        onClick={() => startRun('error')}
133
      >
134
        Simulate error
135
      </button>
136
      <ol className="space-y-1">
137
        {steps.map((step) => (
138
          <li key={step.name} className="flex items-center gap-3 py-1.5">
139
            <span className="text-base">{step.name}</span> -{' '}
140
            <span className="text-base">{step.status}</span>
141
          </li>
142
        ))}
143
      </ol>
144
    </div>
145
  )
146
}
147

148
export { SseEventSource }

Although EventSource provides a convenient way to consume SSE, it has some limitations:

GET requests only: You can’t use EventSource to send a POST request or include a request body.
Limited request configuration: You can’t set arbitrary request headers, such as an Authorization header. Cross-origin requests can use credentials through the withCredentials option, but this doesn’t allow arbitrary header configuration.

Using the Fetch API

The fetch API provides an alternative way to consume SSE when you need more control over the HTTP request. Unlike EventSource, it supports custom headers, different HTTP methods, request bodies, and cancellation through an AbortController.

However, fetch exposes the response body as a readable byte stream rather than dispatching SSE events automatically. The client must read the stream incrementally, parse the SSE message format, and handle connection errors and cancellation itself.

Here is an example of how to use the Fetch API to consume SSE:

1
'use client'
2

3
import { useEffect, useRef, useState } from 'react'
4

5
const PIPELINE = [
6
  'Cloning',
7
  'Installing dependencies',
8
  'Linting',
9
  'Testing',
10
  'Building',
11
  'Deploying',
12
] as const
13

14
type Status = 'pending' | 'running' | 'completed' | 'failed' | 'skipped'
15

16
type Step = { name: (typeof PIPELINE)[number]; status: Status }
17

18
type Snapshot = Step[]
19

20
// Used to determine the outcome of a Run.
21
type Outcome = 'success' | 'error'
22

23
type SseEvent = { event: string; data: string }
24

25
// Idle Snapshot: Every Step is pending.
26
const IDLE_SNAPSHOT: Snapshot = PIPELINE.map((name) => ({
27
  name,
28
  status: 'pending',
29
}))
30

31
// A Run is Terminal once all Steps have one of these statuses.
32
const TERMINAL_STATUSES: Status[] = ['completed', 'failed', 'skipped']
33
const isTerminalSnapshot = (snapshot: Snapshot) =>
34
  snapshot.length > 0 &&
35
  snapshot.every((step) => TERMINAL_STATUSES.includes(step.status))
36

37
// Parses complete SSE events out of a raw fetch buffer. Network chunks
38
// don't line up with events, so leftover text comes back as `rest`.
39
const consumeSseEvents = (
40
  buffer: string,
41
): { events: SseEvent[]; rest: string } => {
42
  // Fetch gives you a raw byte stream — unlike EventSource, it does not
43
  // parse SSE for you. Network chunks do not line up with events: one
44
  // chunk can hold several events, or a single event can be split across
45
  // two chunks. Split on `\n\n`.
46
  const chunks = buffer.split('\n\n')
47

48
  // Trailing fragment to prepend onto the next chunk.
49
  const rest = chunks.pop() ?? ''
50

51
  const events: SseEvent[] = []
52

53
  // Emit every complete event.
54
  for (const chunk of chunks) {
55
    let event = 'message'
56
    const data: string[] = []
57

58
    for (const line of chunk.split('\n')) {
59
      if (line.startsWith('event:')) {
60
        event = line.slice(6).trimStart()
61
        continue
62
      }
63
      if (line.startsWith('data:')) {
64
        data.push(line.slice(5).trimStart())
65
      }
66
    }
67

68
    if (data.length === 0) {
69
      continue
70
    }
71

72
    events.push({ event, data: data.join('\n') })
73
  }
74

75
  return { events, rest }
76
}
77

78
// SseFetch component
79
const SseFetch = () => {
80
  const [steps, setSteps] = useState<Snapshot>(IDLE_SNAPSHOT)
81
  const [inProgress, setInProgress] = useState(false)
82

83
  // Fetch is cancelled with AbortController (EventSource uses close()).
84
  // Keep the controller so we can abort() on unmount, when the current Run
85
  // becomes Terminal, and on error.
86
  const abortControllerRef = useRef<AbortController | null>(null)
87

88
  // Event listeners close over the render that created them, so
89
  // `inProgress`state would be stale inside onerror. The ref is the
90
  // live "a current Run" flag those listeners can read.
91
  const inProgressRef = useRef(false)
92

93
  // Abort the fetch and mark that there is no current Run. Used when the
94
  // current Run becomes Terminal and on error.
95
  const stopRun = () => {
96
    abortControllerRef.current?.abort()
97
    abortControllerRef.current = null
98
    inProgressRef.current = false
99
    setInProgress(false)
100
  }
101

102
  // On unmount, abort the fetch so the browser drops the SSE connection.
103
  useEffect(() => {
104
    return () => {
105
      abortControllerRef.current?.abort()
106
    }
107
  }, [])
108

109
  // Start a new Run. Called when the user clicks Simulate Success or
110
  // Simulate Error.
111
  const startRun = (outcome: Outcome) => {
112
    // Guard against a second click.
113
    if (inProgressRef.current) {
114
      return
115
    }
116

117
    inProgressRef.current = true
118
    setInProgress(true)
119

120
    const abortController = new AbortController()
121
    abortControllerRef.current = abortController
122

123
    // Start the fetch request.
124
    void (async () => {
125
      try {
126
        const response = await fetch(`/api/run?outcome=${outcome}`, {
127
          // Tie this request to the controller so stopRun() / unmount can
128
          // cancel it. Without a signal, the read loop keeps running after
129
          // we consider the Run finished.
130
          signal: abortController.signal,
131
          // An event stream must never be served from cache.
132
          cache: 'no-store',
133
          // Tell the server (and any proxy) we want SSE, not a
134
          // regular JSON response. EventSource sets this header
135
          // automatically.
136
          headers: { Accept: 'text/event-stream' },
137
        })
138

139
        // A non-OK status or a missing body means we never got a stream.
140
        // Throw so the catch path treats it like a dropped connection.
141
        if (!response.ok || !response.body) {
142
          throw new Error('Connection lost. Please try again.')
143
        }
144

145
        // getReader() unlocks the body as chunks of bytes.
146
        const reader = response.body.getReader()
147

148
        // TextDecoder turns those bytes into a string.
149
        const decoder = new TextDecoder()
150

151
        let buffer = ''
152

153
        while (true) {
154
          const { done, value } = await reader.read()
155

156
          // done equals true means the server closed the stream.
157
          // Fetch does not reconnect (EventSource would).
158
          if (done) {
159
            const droppedMidRun = inProgressRef.current
160
            stopRun()
161

162
            // We already called stopRun() after a Terminal Snapshot.
163
            // The stream ending is expected — ignore it.
164
            if (!droppedMidRun) {
165
              return
166
            }
167

168
            // inProgressRef is still true: the connection died mid-Run.
169
            // Return the Pipeline to Idle and tell the user.
170
            setSteps(IDLE_SNAPSHOT)
171
            console.log('Connection lost. Please try again.')
172
            return
173
          }
174

175
          // Append this chunk, peel off every complete event, and keep
176
          // the leftover fragment in `buffer` for the next read.
177
          buffer += decoder.decode(value, { stream: true })
178
          const parsed = consumeSseEvents(buffer)
179
          buffer = parsed.rest
180

181
          for (const event of parsed.events) {
182
            // Named events: the server sends `event: run`. Skip comments,
183
            // heartbeats, and any other event name. EventSource does this
184
            // filter for you via addEventListener('run', ...).
185
            if (event.event !== 'run') {
186
              continue
187
            }
188

189
            const snapshot = JSON.parse(event.data) as Snapshot
190
            setSteps(snapshot)
191

192
            if (!isTerminalSnapshot(snapshot)) {
193
              continue
194
            }
195

196
            // Fetch does not reconnect when the server closes the stream,
197
            // but abort anyway so a late chunk cannot update state after
198
            // the toast.
199
            stopRun()
200

201
            if (outcome === 'error') {
202
              console.log('Testing failed')
203
            } else {
204
              console.log('Every Step completed')
205
            }
206

207
            return
208
          }
209
        }
210
      } catch {
211
        // abort() rejects the fetch with AbortError. That is expected when
212
        // we stop a Terminal Run or unmount. Ignore it. Any other
213
        // rejection during a Run is a dropped connection (network
214
        // error, 5xx, etc.).
215
        if (abortController.signal.aborted) {
216
          return
217
        }
218

219
        const droppedMidRun = inProgressRef.current
220
        stopRun()
221

222
        if (!droppedMidRun) {
223
          return
224
        }
225

226
        setSteps(IDLE_SNAPSHOT)
227
        console.log('Connection lost')
228
      }
229
    })()
230
  }
231

232
  return (
233
    <div className="flex flex-col items-start gap-4">
234
      <button
235
        type="button"
236
        disabled={inProgress}
237
        onClick={() => startRun('success')}
238
      >
239
        Simulate success
240
      </button>
241
      <button
242
        type="button"
243
        disabled={inProgress}
244
        onClick={() => startRun('error')}
245
      >
246
        Simulate error
247
      </button>
248
      <ol className="space-y-1">
249
        {steps.map((step) => (
250
          <li key={step.name} className="flex items-center gap-3 py-1.5">
251
            <span className="text-base">{step.name}</span> -{' '}
252
            <span className="text-base">{step.status}</span>
253
          </li>
254
        ))}
255
      </ol>
256
    </div>
257
  )
258
}
259

260
export { SseFetch }

Choosing the right approach

The right choice depends on your application’s requirements and how much control you need over the connection.

Use EventSource when you need a straightforward way to receive server updates and its built-in behavior meets your requirements.

Choose fetch when you need more control over the request, such as sending authorization headers, using a POST request, or managing cancellation and reconnection yourself.

Feature	EventSource	Fetch
HTTP methods	GET only	Any supported method
Custom request headers	Not supported	Supported
Request body	Not supported	Supported
Receiving events	Automatically parses SSE messages and dispatches events	Requires reading the stream and parsing SSE messages
Automatic reconnection	Built in	Must be implemented manually
Implementation complexity	Low to moderate	Moderate to high

Conclusion

Server-Sent Events provide a simple and efficient way to stream real time data from the server to the client. Whether you use EventSource or fetch, SSE is great for use cases like notifications, progress tracking, and live feeds.

The implementations above show the core concepts of SSE, but production applications need to account for a few additional challenges such as resuming a stream after a reconnection, resending missed events, handling errors appropriately, and other edge cases. To handle these cases reliably, consider using a well maintained SSE library rather than implementing everything from scratch. By understanding these considerations, you can build robust and efficient SSE applications that meet your needs.