streaming-ssr

name	streaming-ssr
description	Add streaming SSR to a merjs page. Use when the user wants shell-first rendering, skeleton placeholders, or parallel data fetching that resolves inline.
argument-hint	[page-name]
disable-model-invocation	true

Add Streaming SSR to a merjs page

Scaffold or upgrade app/$ARGUMENTS.zig to use renderStream — shell-first streaming with skeleton placeholders that resolve as data arrives.

How it works

1. renderStream is called instead of render when the route is hit
2. stream.write(html) flushes bytes to the browser immediately (chunked transfer encoding)
3. stream.placeholder(id, skeleton_html) writes a shimmer skeleton + <div id="P:id"> into the live DOM
4. mer.fetchAll() fetches multiple URLs in parallel (threads on dev server, two-phase WASM bridge on Cloudflare Workers)
5. stream.resolve(id, real_html) injects a hidden div + inline <script> that swaps the skeleton with real content
6. stream.flush() ends the response

On Cloudflare Workers, mer.fetchAll() uses a two-phase JS bridge:

• Phase 1: WASM dry-run collects URLs (collect_fetch_urls)
• Phase 2: JS fetches all in parallel via Workers native fetch()
• Phase 3: results injected into WASM cache, full render proceeds

Steps

1. Create or update app/$ARGUMENTS.zig:

const std = @import("std");
const mer = @import("mer");

pub const meta: mer.Meta = .{
    .title = "PAGE_TITLE",
    .description = "PAGE_DESCRIPTION",
    .extra_head = "<style>" ++ page_css ++ "</style>",
};

// Fallback for non-streaming clients (required)
pub fn render(req: mer.Request) mer.Response {
    _ = req;
    return mer.html("<p>Requires streaming.</p>");
}

pub fn renderStream(req: mer.Request, stream: *mer.StreamWriter) void {
    const alloc = req.allocator;

    // Shell hits browser immediately — before any fetch
    stream.write(
        \\<div class="page">
        \\  <h1>PAGE_TITLE</h1>
    );

    // Skeleton placeholders — visible in DOM while fetching
    stream.placeholder("section-a",
        \\<div class="skeleton">Loading...</div>
    );

    // Fetch multiple URLs in parallel
    const results = mer.fetchAll(alloc, &.{
        .{ .url = "https://api.example.com/data-a" },
        .{ .url = "https://api.example.com/data-b" },
    });
    defer for (results) |r| if (r) |ok| ok.deinit(alloc);

    // Resolve skeleton → real content inline
    if (results[0]) |res| {
        stream.resolve("section-a", buildCard(alloc, res.body));
    } else {
        stream.resolve("section-a", "<p>Failed to load.</p>");
    }

    stream.write("</div>");
    stream.flush();
}

fn buildCard(alloc: std.mem.Allocator, body: []u8) []const u8 {
    _ = body;
    return std.fmt.allocPrint(alloc, "<div class=\"card\">data</div>", .{}) catch "error";
}

const page_css =
    \\.page { max-width: 640px; margin: 0 auto; }
    \\.card { background: var(--bg2); border-radius: 10px; padding: 20px; }
    \\.skeleton { background: var(--bg3); border-radius: 10px; padding: 20px; height: 80px;
    \\  position: relative; overflow: hidden; }
    \\.skeleton::after { content:''; position:absolute; inset:0;
    \\  background:linear-gradient(90deg,transparent,rgba(255,255,255,0.25),transparent);
    \\  animation:shimmer 1.5s infinite; }
    \\@keyframes shimmer { 0%{transform:translateX(-100%)} 100%{transform:translateX(100%)} }
;

2. Run zig build codegen to register the route
3. Run zig build serve and visit the route — watch skeletons resolve

Key rules

• MUST export both render (fallback) and renderStream
• MUST export pub const meta: mer.Meta
• stream.placeholder(id, skeleton) must come BEFORE mer.fetchAll
• stream.resolve(id, html) must come AFTER results are ready
• stream.flush() must be called at the end
• mer.fetchAll returns []?mer.FetchResult — always handle the null case
• Always defer deinit on results to free memory
• The id passed to placeholder and resolve must match exactly

Live example

• Page: app/stream-demo.zig
• URL: https://merlionjs.com/stream-demo
• GitHub: https://github.com/justrach/merjs/blob/main/app/stream-demo.zig

See also

• src/mer.zig — StreamWriter, fetchAll, placeholder, resolve
• src/ssr.zig — streaming engine
• src/router.zig — dispatchStream / dispatchBuffered
• src/worker.zig — two-phase fetch exports (collect_fetch_urls, provide_fetch_result)
• PRIMITIVES.md — full API reference