Streaming long operations in NextJS - Step-by-Step Execution

Concept Flow - Streaming long operations

User requests page

↓

Server starts processing

↓

Begin streaming response

↓

Send chunks of data as ready

↓

Client receives and renders chunks

↓

Streaming completes

↓

Full page rendered

The server processes a long task and streams parts of the response to the client as they become ready, allowing the client to render progressively.

Execution Sample

NextJS

export default async function Page() {
  const stream = new ReadableStream({
    async start(controller) {
      controller.enqueue('Loading chunk 1...\n');
      await new Promise(r => setTimeout(r, 1000));
      controller.enqueue('Loading chunk 2...\n');
      controller.close();
    }
  });
  return new Response(stream);
}

This Next.js server component streams two chunks of text with a delay, simulating a long operation streamed to the client.

Execution Table

Step	Action	Stream State	Data Sent	Client Render
1	User requests page	Not started
2	Server starts ReadableStream	Open
3	Enqueue 'Loading chunk 1...\n'	Open	Loading chunk 1...\n	Renders 'Loading chunk 1...'
4	Wait 1 second	Open	Loading chunk 1...\n	Shows first chunk
5	Enqueue 'Loading chunk 2...\n'	Open	Loading chunk 1...\nLoading chunk 2...\n	Renders second chunk appended
6	Close stream	Closed	Loading chunk 1...\nLoading chunk 2...\n	Full content rendered
7	Response complete	Closed	All data sent	Page fully loaded

💡 Stream closes after sending all chunks, ending the response.

Variable Tracker

Variable	Start	After Step 3	After Step 5	Final
stream state	Not started	Open	Open	Closed
data sent	""	"Loading chunk 1...\n"	"Loading chunk 1...\nLoading chunk 2...\n"	"Loading chunk 1...\nLoading chunk 2...\n"
client render	""	"Loading chunk 1...\n"	"Loading chunk 1...\nLoading chunk 2...\n"	"Loading chunk 1...\nLoading chunk 2...\n"

Key Moments - 2 Insights

Why does the client see 'Loading chunk 1...' before the entire operation finishes?

Because the server streams data in chunks (see Step 3 and Step 5 in execution_table), the client renders each chunk as it arrives instead of waiting for all data.

What happens if the stream is not closed after sending chunks?

The client will keep waiting for more data and the page will not finish loading (see Step 6 where closing the stream signals completion).

Visual Quiz - 3 Questions

Look at the execution_table, what is the stream state after Step 5?

A Closed

B Open

C Not started

D Errored

💡 Hint

Check the 'Stream State' column at Step 5 in the execution_table.

At which step does the client first render any content?

A Step 3

B Step 2

C Step 4

D Step 6

💡 Hint

Look at the 'Client Render' column in execution_table to see when content appears.

If the delay between chunks is increased, how does the execution_table change?

A Data sent is reduced

B Stream closes earlier

C Step 4's wait time increases, delaying Step 5 and client render

D Client renders all at once immediately

💡 Hint

Consider the wait in Step 4 and its effect on subsequent steps in execution_table.

Concept Snapshot

Streaming long operations in Next.js:
- Use ReadableStream in server components
- Enqueue data chunks progressively
- Close stream to signal end
- Client renders chunks as they arrive
- Enables faster perceived loading for long tasks

Full Transcript

This visual trace shows how Next.js streams long operations by sending data in chunks from the server to the client. The server creates a ReadableStream and enqueues parts of the response with delays. The client renders each chunk as it arrives, improving user experience by showing progress early. The stream closes when all data is sent, completing the page load.

Practice

1. What is the main benefit of using streaming in Next.js for long operations?

easy

A. Users see data progressively, reducing perceived wait time.

B. It automatically caches all data on the server.

C. It compresses data to reduce bandwidth usage.

D. It prevents any errors during data fetching.

Solution

1. Step 1: Understand streaming purpose

   Streaming sends data in chunks so users can see progress during long operations.

2. Step 2: Identify user experience impact

   This reduces the perceived wait time by showing partial results early.

3. Final Answer:

   Users see data progressively, reducing perceived wait time. -> Option A

4. Quick Check:

   Streaming improves user experience = A [OK]

Hint: Streaming shows partial data early to users [OK]

Common Mistakes:

• Thinking streaming caches data automatically
• Confusing streaming with data compression
• Assuming streaming prevents all errors

2. Which syntax correctly creates a streaming response in a Next.js API route?

easy

A. const stream = new ReadableStream({ start(controller) { controller.enqueue('data'); controller.close(); } }); return new Response(stream);

B. const stream = new StreamReader(); stream.push('data'); return stream;

C. const stream = new WritableStream(); stream.write('data'); return stream;

D. const stream = new ReadableStream(); stream.send('data'); return stream;

Solution

1. Step 1: Recall correct ReadableStream usage

   ReadableStream requires a start method with a controller to enqueue data and close the stream.

2. Step 2: Match syntax with Next.js streaming pattern

   const stream = new ReadableStream({ start(controller) { controller.enqueue('data'); controller.close(); } }); return new Response(stream); uses controller.enqueue and controller.close correctly and returns a Response wrapping the stream.

3. Final Answer:

   const stream = new ReadableStream({ start(controller) { controller.enqueue('data'); controller.close(); } }); return new Response(stream); -> Option A

4. Quick Check:

   ReadableStream with controller.enqueue = B [OK]

Hint: Use ReadableStream with start(controller) and enqueue [OK]

Common Mistakes:

• Using WritableStream instead of ReadableStream
• Calling non-existent methods like send() or push()
• Not closing the stream after enqueue

3. Given this Next.js API route code, what will the client receive?

export async function GET() {
  const stream = new ReadableStream({
    async start(controller) {
      controller.enqueue(new TextEncoder().encode('Hello '));
      await new Promise(r => setTimeout(r, 1000));
      controller.enqueue(new TextEncoder().encode('World!'));
      controller.close();
    }
  });
  return new Response(stream);
}

medium

A. Only "Hello " is received; stream never closes.

B. "Hello World!" received in two chunks with 1 second delay between.

C. "Hello World!" received all at once after 1 second delay.

D. Syntax error due to missing await in controller.enqueue.

Solution

1. Step 1: Analyze streaming behavior

   The stream first sends "Hello " immediately, then waits 1 second before sending "World!".

2. Step 2: Understand client reception

   The client receives data in two chunks with a delay, then the stream closes properly.

3. Final Answer:

   "Hello World!" received in two chunks with 1 second delay between. -> Option B

4. Quick Check:

   Streaming sends chunks with delay = C [OK]

Hint: Streaming sends chunks as they enqueue, not all at once [OK]

Common Mistakes:

• Assuming all data arrives after delay
• Thinking stream never closes
• Confusing async enqueue with syntax error

4. What is wrong with this Next.js streaming code snippet?

export async function GET() {
  const stream = new ReadableStream({
    start(controller) {
      controller.enqueue('Data chunk');
      // Missing controller.close()
    }
  });
  return new Response(stream);
}

medium

A. ReadableStream cannot be used in Next.js API routes.

B. controller.enqueue must be async function.

C. The stream never closes, causing the client to wait indefinitely.

D. Response must be wrapped in JSON.stringify.

Solution

1. Step 1: Check stream lifecycle

   The code enqueues data but does not call controller.close(), so the stream stays open.

2. Step 2: Understand client impact

   The client waits forever for the stream to end, causing a hang or timeout.

3. Final Answer:

   The stream never closes, causing the client to wait indefinitely. -> Option C

4. Quick Check:

   Missing controller.close() = stream hangs [OK]

Hint: Always call controller.close() after enqueueing all data [OK]

Common Mistakes:

• Forgetting to close the stream
• Thinking enqueue must be async
• Misunderstanding Response usage

5. You want to stream a large list of items from a Next.js API route, sending each item as JSON chunk. Which approach correctly streams the data without blocking the client?

hard

A. Send each item with separate fetch requests instead of streaming.

B. Convert entire list to JSON string, enqueue once, then close the stream.

C. Use WritableStream to write each JSON chunk and return it directly.

D. Use ReadableStream with async start(controller), loop over items, enqueue JSON strings, and close after all.

Solution

1. Step 1: Understand streaming large data

   Streaming each item as JSON chunk progressively sends data without waiting for all items.

2. Step 2: Identify correct streaming pattern

   Using ReadableStream with async start allows looping over items, enqueueing each chunk, then closing the stream.

3. Step 3: Evaluate other options

   A requires multiple requests (inefficient); B sends all data at once (no streaming benefit); C uses wrong WritableStream type.

4. Final Answer:

   Use ReadableStream with async start(controller), loop over items, enqueue JSON strings, and close after all. -> Option D

5. Quick Check:

   Stream chunks in loop with ReadableStream = D [OK]

Hint: Stream each item chunk inside async start, then close stream [OK]

Common Mistakes:

• Sending all data at once, losing streaming benefit
• Using WritableStream instead of ReadableStream
• Making multiple fetch calls instead of streaming