Render wrapped pages with a single renderPage

[dajinchu]

Wrapped pages used to run renderPage twice: once in preHandler just to read the route's config, then again with Rails' HTML. Now Rails is requested inside the render, and a wrapped page renders once, which cuts its server CPU by about 30%. It renders a second time only in one case, below.

This branch also carries two earlier commits:

• 0b548f9 (Install a single vike and fix hardNavigate return type) is the same commit as in Fix versioning #98. Please merge Fix versioning #98 first; I'll rebase.
• 552183c adds the server benchmarks in tests/bench used for the numbers below.

How it works

• bifrost-fastify passes a per-request loader in pageContextInit, and the wrapped renderer's new +onCreatePageContext calls it. The loader requests Rails through reply-from and holds the response instead of sending it.
• If Rails' page can be wrapped, the render continues with it. Otherwise (a redirect, non-HTML, no layout, or a page without <head>/<body>), Rails' response is sent as-is after renderPage returns, as before.
• Rails is requested at most once per request, and buildPageContextInit still re-runs after beforeWrappedRender (run buildPageContextInit again when rendering wrapped pages #71).
• If Rails errors or drops the connection, Bifrost still responds with an error. A client disconnect also releases the wait, since reply-from never calls back if an HTTP/2 client disconnects first.

App +onCreatePageContext hooks

Vike runs +onCreatePageContext hooks concurrently, so an app's hook can't see the wrapped page unless it awaits it. Apps keep working without changes:

• Only Bifrost's hook (or the app's hook awaits loadWrappedPage(pageContext)): one render.
• Other hooks, none awaiting loadWrappedPage: Bifrost renders the page a second time, so those hooks see it. Its hook throws render(url, abortReason) and onBeforeRoute adds the page before any hook runs. Keeping abortReason keeps routes reached by throw render(url, { proxy: "wrapped" }) (like Alignable's renderWrapped) from re-running the page that threw it. Rails is still requested once.

loadWrappedPage is exported from @alignable/bifrost, and the README recommends it. In the bench, the second render adds about 0.5 ms of CPU per wrapped page (roughly 20%).

For Alignable: wrapped pages work after the bump as-is. To get the single render, add this to frontend/renderer/+onCreatePageContext.shared.ts:

if (pageContext.config.proxyMode === "wrapped" && !(await loadWrappedPage(pageContext))) return;

Performance

npm run bench -- -c 1,10, base (552183c) and this branch measured back to back. The bench pages have only Bifrost's hook:

Scenario	CPU ms/req (c=10)	req/s (c=10)	p50 at c=1
wrapped	3.62 → 2.49 (−31%)	296 → 436 (+47%)	4.87 → 4.00 ms
wrapped client nav	1.07 → 1.07	983 → 1010	1.30 → 1.20 ms
passthru	1.09 → 1.11	964 → 977	1.36 → 1.24 ms
native	5.71 → 5.39	188 → 199	6.88 → 6.54 ms

Passthru and client navigation still run one renderPage to read the route's config; that's a follow-up.

README

Rewritten to be concise: what Bifrost is, how requests flow, and integration steps (Vike config, Fastify server, the Rails side, wrapped and passthru routes, navigation). It includes the loadWrappedPage performance note.

Testing

• http.spec.ts covers each path. It uses dedicated test routes with an app-level +onCreatePageContext, and checks the number of renders (via pageContextsAborted) and that the backend was requested exactly once:
  • only Bifrost's hook: one render;
  • an app hook that awaits loadWrappedPage: one render;
  • an app hook that doesn't: two renders, and the hook sees the page;
  • a page that threw render(url, { proxy: "wrapped" }): exactly two aborts.
• The fake backend dropping the connection gets a 5xx instead of hanging.
• Each of the new tests fails when the behavior it guards is broken (memoization, error settlement, abortReason, the loadWrappedPage mark).
• e2e: 315 passed, twice. The full parallel suite has intermittent timing failures locally, on the base commit too. They pass when repeated in isolation.

Release

Release both packages together. bifrost-fastify pins @alignable/bifrost exactly and relies on the new hook.

🤖 Generated with Claude Code

[reinabo]

looks good overall