HTML Streaming

Types of HTML Streaming

• In-order streaming

  • HTML arrives in the exact order of document structure.

• Out-of-order streaming

  • HTML fragments arrive as data becomes ready, even if out of sequence.
  • Requires minimal JavaScript client-side to rearrange HTML in correct order.

Perceived Performance (User Experience)

• Users see content immediately, improving engagement.
• Reduces perceived loading times significantly by showing progressive content.

Real Performance (Network & Rendering)

• Faster Time to First Byte (TTFB) Content starts arriving sooner, browsers begin parsing immediately.
• Earlier Asset Downloads CSS, fonts, and JavaScript can begin downloading before the entire page HTML completes.
• Improved Time to Interactive (TTI) Users can start interacting with visible components faster.

Reduced Server Load

• Incremental streaming reduces memory usage.
• Lower latency and increased throughput.

<await>

Wait for a promise to render a section of the template

Syntax example:

<await|user|=getUser()>
  <img src=user.avatar>
  ${user.name}
</await>

await|user|=getUser()
  img src=user.avatar
  -- ${user.name}

• Marko will flush as much HTML content as possible up to an <await>
• Upon resolution of getUser(), the remaining HTML will be flushed

<try>

Manage asynchronous boundaries, handle loading states, and gracefully catch errors within streaming (and non-streaming) HTML.

Basic syntax:

<try>

  <@placeholder>Loading...</@placeholder>

  <@catch|err|>
    Error: ${err.message}
  </@catch>
  <await|user|=getUser()>
    ${user.name}
  </await>
</try>

try

  @placeholder -- Loading...

  @catch|err| -- Error: ${err.message}
  await|user|=getUser() -- ${user.name}

Avoiding Layout Shift (CLS)

Out-of-order streaming involves temporary placeholders being replaced with real content once it is ready. If not handled properly, this can cause content the user is reading or interacting with to shift, leading to a poor user experience.

• Use placeholders that reserve the correct amount of space.
• Utilize loading indicators/skeleton screens that accurately represent the content.
• Fallback to in-order streaming where it makes sense or content size cannot be determined

Avoiding Buffering

Even though streaming has been supported on the web for decades and more tools are utilizing it, you may still find that some default configurations of third parties may assume a buffered response. Here are some known culprits that may buffer your server’s output HTTP streams:

proxy_http_version 1.1; # 1.0 by default
proxy_buffering off; # on by default

<network:http.buffer-response-v2>off</network:http.buffer-response-v2>

import http from "http";
import zlib from "zlib";

import MarkoTemplate from "./something.marko";

http
  .createServer(function (request, response) {
    response.writeHead(200, { "content-type": "text/html;charset=utf-8" });
    const templateStream = MarkoTemplate.stream({});
    const gzipStream = zlib.createGzip({
      flush: zlib.constants.Z_PARTIAL_FLUSH,
    });
    templateStream.pipe(outputStream).pipe(response);
  })
  .listen(80);