feat(router): blockSSR by wmertens · Pull Request #8793 · QwikDev/qwik

wmertens · 2026-07-02T23:09:30Z

Routeloaders block SSR by default and can be opted-out.

changeset-bot · 2026-07-02T23:09:34Z

🦋 Changeset detected

Latest commit: d57a664

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 5 packages

Name	Type
@qwik.dev/router	Minor
eslint-plugin-qwik	Minor
@qwik.dev/core	Minor
create-qwik	Minor
@qwik.dev/react	Minor

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

Copilot

Pull request overview

Adds a new blockSSR option to Qwik Router route loaders so SSR can either await loaders by default (allowing redirect/error to short-circuit) or opt out and run loaders in the background without affecting the page response.

Changes:

Introduces LoaderOptions.blockSSR (default true) and propagates it through loader internals.
Updates loader execution to detach response controls for blockSSR: false loaders and adds middleware/unit/e2e/docs coverage.
Adds a changeset announcing the new router feature.

Reviewed changes

Copilot reviewed 9 out of 9 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
packages/qwik/src/core/shared/serdes/serialize.ts	Adds a TODO comment related to async serialization behavior.
packages/qwik-router/src/runtime/src/types.ts	Adds `blockSSR` to loader options and internal loader shape.
packages/qwik-router/src/runtime/src/route-loaders.ts	Implements response-detaching for background loaders and threads `blockSSR` into server capture.
packages/qwik-router/src/middleware/request-handler/resolve-request-handlers.unit.ts	Adds unit tests covering blocking vs background loader SSR behavior.
packages/qwik-router/src/middleware/request-handler/resolve-request-handlers-core.ts	Changes loader middleware to start loaders and await only blocking loaders before SSR.
packages/docs/src/routes/docs/(qwikrouter)/route-loader/index.mdx	Documents default SSR-blocking behavior and the new “background loaders” option.
e2e/qwik-e2e/tests/qwikrouter/loaders.e2e.ts	Adds an e2e regression test ensuring unread background loaders don’t fail SSR.
e2e/qwik-e2e/apps/qwikrouter-test/src/routes/(common)/loaders/non-blocking/index.tsx	Adds an e2e fixture route that throws from a background loader without reading `.value`.
.changeset/lazy-route-loaders.md	Declares a minor release for `@qwik.dev/router` to ship `blockSSR`.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

maiieul · 2026-07-03T12:29:02Z

Comparing the two shapes for deferred/streamed loader data — a defer-marked loader (its own request) vs a bare Promise field returned inside a loader's value (rides the parent's request). They're not substitutes; each has real exclusives that follow from which side of the request boundary the streamed unit sits on.

Capability comparison

Capability	`defer` loaders	bare-promise fields
Per-unit HTTP caching (cacheKey / eTag / CDN, cross-route cache entry)	✓ per loader	✓ per loader (just split it out) · ✗ per field
Independent revalidation after an action	✓ per loader	✓ per loader · ✗ per field
Typed `.error` (`ServerError` envelope, prod redaction, closest-`ErrorBoundary` routing) per streamed unit	✓ per loader	✓ per loader · ✗ per field
Static knowability (build-time envelope enforcement, pre-head await set known without executing, typed `RequestEvent` with no `status`/`redirect`)	✓ exclusive	✗ discovered only after the loader body runs; runtime guard only
Ships on existing machinery (whole-signal OOOS streaming)	✓	✗ (needs a pending-promise wire protocol — the serializer currently await-flattens nested promises)
Co-location (streamed work closes over critical data, no `resolveValue` / embedded re-run)	✗	✓ exclusive
Declarations needed for critical + streamed	≥ 2 loaders	1 loader
Streamed units share one request / one middleware run (SPA nav)	✗ one request per deferred loader	✓ fields ride the parent's request
Dynamic deferral (await the fast path / stream the slow path per request)	✗ (bot/SEO case is better a framework knob)	✓ (niche)
Dynamic cardinality (N streamed units, N known only at runtime)	✗ inexpressible	✓ exclusive

The one thing only bare promises can express: dynamic cardinality

A search page: fast ID query, slow per-item hydration, and you want each result to pop in individually as its own fetch settles.

// bare-promise fields — one streamed unit PER ITEM, count known only at runtime
export const useSearch = routeLoader$(async (ev) => {
  const ids = await searchIds(ev.query.get('q'));         // fast, critical, envelope-capable
  return { ids, items: ids.map((id) => fetchItem(id)) };  // N bare promises, N = runtime
});

// render: each card reveals as ITS OWN promise settles
{data.value.ids.map((id, i) => (
  <Await key={id} promise={data.value.items[i]} fallback={<SkeletonCard />}>
    {(item) => <ProductCard item={item} />}
  </Await>
))}

Why defer loaders can't match it:

// Attempt 1 — one deferred loader with Promise.all: loses per-item streaming
export const useItems = routeLoader$(async (ev) => {
  const ids = await ev.resolveValue(useSearchIds);
  return Promise.all(ids.map(fetchItem));  // signal resolves when the SLOWEST item does
}, { defer: true });                        // → the whole grid pops at once, no per-item pop-in

// Attempt 2 — one loader per item: impossible
// loaders are static module-level exports; you can't declare useItem_0 … useItem_N
// when N depends on the request. One loader = one signal; there is no per-instance
// parameterization of a routeLoader$.

The unit of deferral for a defer loader is the loader, and loaders are statically declared — so a runtime-determined number of independently-streamed units is inexpressible. A bare promise's unit is a value, and values are dynamic (the serializer already walks values recursively, so promises inside arrays are natural for it).

pkg-pr-new · 2026-07-03T13:22:53Z

Open in StackBlitz

@qwik.dev/core

npm i https://pkg.pr.new/QwikDev/qwik/@qwik.dev/core@8793

@qwik.dev/router

npm i https://pkg.pr.new/QwikDev/qwik/@qwik.dev/router@8793

eslint-plugin-qwik

npm i https://pkg.pr.new/QwikDev/qwik/eslint-plugin-qwik@8793

create-qwik

npm i https://pkg.pr.new/QwikDev/qwik/create-qwik@8793

@qwik.dev/optimizer

npm i https://pkg.pr.new/QwikDev/qwik/@qwik.dev/optimizer@8793

@qwik.dev/devtools

npm i https://pkg.pr.new/QwikDev/qwik/@qwik.dev/devtools@8793

commit: d57a664

github-actions · 2026-07-03T13:30:50Z

built with Refined Cloudflare Pages Action

⚡ Cloudflare Pages Deployment

Name	Status	Preview	Last Commit
qwik-docs	✅ Ready (View Log)	Visit Preview	`d57a664`

Varixo · 2026-07-03T14:10:04Z

+          allBlockSSRLoaders = (
+            allBlockSSRLoaders ? allBlockSSRLoaders.then(() => promise) : promise
+          ) as Promise<void>;


why no Promise.all?

this way, the first error in route order will throw even if there are multiple errors.
Also, the loads all start at the same time so the .then() chaining doesn't cause a waterfall

Varixo · 2026-07-03T14:10:28Z

+'@qwik.dev/router': minor
+---
+
+route loaders gain a `blockSSR` option (default `true`); set `blockSSR: false` to run a loader in the background without blocking SSR


there should be "feat:" prefix

jordanw66 · 2026-07-03T15:05:36Z

In the PR it mentions the recommended setting for loaders is blockSSR: false

Should that be the default instead? Or less radically, could there be a global setting to change the default to false?

Copilot AI review requested due to automatic review settings July 2, 2026 23:09

wmertens requested review from a team as code owners July 2, 2026 23:09

maiieul assigned wmertens Jul 2, 2026

maiieul moved this to Waiting For Review in Qwik Development Jul 2, 2026

maiieul added this to Qwik Development Jul 2, 2026

Copilot started reviewing on behalf of wmertens July 2, 2026 23:09 View session

Copilot AI reviewed Jul 2, 2026

View reviewed changes

Comment thread packages/qwik-router/src/runtime/src/route-loaders.ts

Comment thread packages/qwik-router/src/middleware/request-handler/resolve-request-handlers-core.ts

Comment thread packages/qwik/src/core/shared/serdes/serialize.ts

wmertens force-pushed the action-redirect branch from 285d1c3 to a942054 Compare July 3, 2026 09:00

fix(router): lazy routeloaders

8600b03

wmertens force-pushed the action-redirect branch from a942054 to d6acfbc Compare July 3, 2026 13:19

Varixo reviewed Jul 3, 2026

View reviewed changes

wmertens added 2 commits July 3, 2026 16:58

fix(router): blockSSR routeLoader

dc83625

fix(build): circular types tsc errors

d57a664

wmertens force-pushed the action-redirect branch from d6acfbc to d57a664 Compare July 3, 2026 14:58

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

feat(router): blockSSR#8793

feat(router): blockSSR#8793
wmertens wants to merge 3 commits into
build/v2from
action-redirect

wmertens commented Jul 2, 2026

Uh oh!

changeset-bot Bot commented Jul 2, 2026 •

edited

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

maiieul commented Jul 3, 2026 •

edited

Loading

Uh oh!

pkg-pr-new Bot commented Jul 3, 2026 •

edited

Loading

Uh oh!

github-actions Bot commented Jul 3, 2026 •

edited

Loading

Uh oh!

Varixo Jul 3, 2026

Uh oh!

wmertens Jul 3, 2026

Uh oh!

Varixo Jul 3, 2026

Uh oh!

jordanw66 commented Jul 3, 2026 •

edited

Loading

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

Uh oh!

Conversation

wmertens commented Jul 2, 2026

Uh oh!

changeset-bot Bot commented Jul 2, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🦋 Changeset detected

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

maiieul commented Jul 3, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Capability comparison

The one thing only bare promises can express: dynamic cardinality

Uh oh!

pkg-pr-new Bot commented Jul 3, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions Bot commented Jul 3, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

built with Refined Cloudflare Pages Action

⚡ Cloudflare Pages Deployment

Uh oh!

Varixo Jul 3, 2026

Choose a reason for hiding this comment

Uh oh!

wmertens Jul 3, 2026

Choose a reason for hiding this comment

Uh oh!

Varixo Jul 3, 2026

Choose a reason for hiding this comment

Uh oh!

jordanw66 commented Jul 3, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

changeset-bot Bot commented Jul 2, 2026 •

edited

Loading

maiieul commented Jul 3, 2026 •

edited

Loading

pkg-pr-new Bot commented Jul 3, 2026 •

edited

Loading

github-actions Bot commented Jul 3, 2026 •

edited

Loading

jordanw66 commented Jul 3, 2026 •

edited

Loading