Guidance needed for configuring Next.js 15 streaming with Fastly CDN

[adardesign]

Summary

We are adopting Next.js 15 to leverage its server-side streaming capabilities with React Suspense. While streaming works perfectly in our local development environment, we are encountering issues when deploying our application behind Fastly CDN.

The Problem

When a page with Suspense boundaries is requested through Fastly, the response appears to be fully buffered. Instead of the initial shell being sent immediately followed by streamed chunks, the browser only receives the complete HTML document after the slowest data fetch has resolved on the server. This behavior negates the primary user experience benefit of streaming.

Expected Behavior

We expect Fastly to act as a pass-through for the streamed response from the Next.js server. The initial HTML shell should be delivered to the client instantly, and subsequent chunks generated by resolved Suspense boundaries should be sent as they become available, without being buffered by the CDN.

Our Setup

• Next.js Version: 15.x.x (latest)
• Environment: Self-hosted Node.js server
• CDN: Fastly

What We've Tried

1. Enabling Streaming in Fastly VCL: We have configured set beresp.do_stream = true; within vcl_fetch for responses from our Next.js origin.
2. Header Inspection: We have confirmed that the Next.js server is sending Transfer-Encoding: chunked.
3. Disabling Gzip: We have experimented with disabling gzip compression at the CDN layer to rule out buffering related to that, but the issue persists.

Request for Guidance

Could the team provide official documentation or guidance on the recommended configuration for using Next.js streaming with a streaming-capable CDN like Fastly?

Specifically, we are looking for answers to the following:

• Is there a reference Fastly VCL configuration that is known to work correctly with Next.js streaming?
• Are there specific HTTP headers or other response properties that Next.js relies on for streaming which require special handling or pass-through rules at the CDN level?
• Are there any known incompatibilities or required settings we should be aware of?

Any insights or examples would be immensely helpful for us and likely for other users in the community deploying Next.js in similar enterprise environments.

Thank you for your time and for building a great framework.

Additional information

No response

Example

No response

[SametDulger]

Here’s detailed guidance for configuring Next.js 15 streaming with Fastly CDN to ensure streaming responses work correctly without buffering:

Background
Next.js 15 uses React Server Components with streaming SSR, sending an initial HTML shell immediately followed by streamed chunks for Suspense boundaries. For this to reach the client progressively:

The CDN must not buffer the entire response.

Transfer-Encoding must be chunked and passed through.

Compression (gzip, brotli) must be compatible with streaming or disabled.

Key Fastly Configuration Tips

1. Enable Streaming in Fastly VCL
   You’ve done this, but here’s a canonical snippet to ensure streaming is enabled in vcl_fetch:

sub vcl_fetch {
  # Enable streaming for responses from the origin
  if (req.backend.name == your_nextjs_backend) {
    set beresp.do_stream = true;
    # Optional: disable gzip if problematic
    set beresp.do_gzip = false;
  }
}

Make sure beresp.do_stream = true is set before any gzip or content transformations.

2. Pass-Through Required Headers
   Next.js streaming relies on Transfer-Encoding: chunked and may send:

Content-Type: text/html; charset=utf-8

Cache-Control headers

Content-Encoding (if compression is enabled)

Ensure Fastly does not strip or modify these headers improperly.

Add this in vcl_deliver to preserve headers:

sub vcl_deliver {
  if (resp.http.Transfer-Encoding) {
    # Preserve Transfer-Encoding header
    set resp.http.Transfer-Encoding = resp.http.Transfer-Encoding;
  }
}

3. Disable Response Buffering
   Fastly buffers by default, which can interfere with streaming.

To disable buffering explicitly for Next.js responses:

sub vcl_backend_response {
  if (bereq.backend.name == your_nextjs_backend) {
    set beresp.do_stream = true;
    set beresp.do_esi = false;
    # Disable buffering to pass data immediately
    set beresp.do_pass = true;
  }
}

Note: Setting beresp.do_pass disables caching for that response. Use only if acceptable or for specific streaming pages.

4. Compression Considerations
   Compression often conflicts with streaming.

Prefer disabling gzip on Fastly for streaming responses, or

Use Next.js’s built-in compression and let Fastly pass through compressed streams transparently (less common).

If you disable gzip at Fastly, confirm Next.js is not double compressing.

5. Cache-Control and Caching
   If you want to cache streaming responses, Fastly must support caching with streaming, which is complex.

For dynamic streaming SSR pages, consider setting Cache-Control: no-store or private to avoid caching.

For static assets, allow caching as normal.

Known Limitations & Tips
Some older Fastly features or custom VCL snippets might implicitly buffer. Review your entire VCL.

Test streaming behavior with simple streaming endpoints first (e.g., a minimal streaming HTML endpoint).

Use browser devtools to confirm chunks arrive progressively.

Some clients or browsers might also buffer; verify using curl or tools like httpie.

Summary Checklist

beresp.do_stream = true | Enable streaming at backend response stage
Disable gzip at CDN layer | Avoid compression buffering
Preserve Transfer-Encoding | Pass chunked transfer encoding header
Disable Fastly buffering | Use beresp.do_pass = true if buffering issues
Cache-Control no-store/private | Avoid caching streaming dynamic pages

[icyJoseph]

Hi @adardesign I know this LLM response just re-worded some of your already tried methods, but maybe some of the configs are possible?

Is it also possible for you to reach your origin, aka, behind the CDN to make sure that your production server is working correctly?