fix(router): blockSSR routeLoader

Author: wmertens

.changeset/lazy-route-loaders.md

@@ -1,5 +1,5 @@
 ---
-'@qwik.dev/router': major
+'@qwik.dev/router': minor
 ---
 
-FEAT: route loaders now do not block SSR start, and they can no longer redirect or error the response. Instead, use request handlers like `onGet`. Consider each route loader as a separate request that does not impact the page.
+route loaders gain a `blockSSR` option (default `true`); set `blockSSR: false` to run a loader in the background without blocking SSR

e2e/qwik-e2e/apps/qwikrouter-test/src/routes/(common)/loaders/[id]/index.tsx

@@ -3,7 +3,6 @@ import {
   type DocumentHead,
   Form,
   Link,
-  type RequestHandler,
   routeAction$,
   routeLoader$,
   z,
@@ -13,20 +12,20 @@ import { delay } from '../../actions/login';
 
 export const useDateLoader = routeLoader$(() => new Date('2021-01-01T00:00:00.000Z'));
 
-// Route control flow (redirect/json) lives in middleware, which runs eagerly before render.
-// Loaders are data-only and run lazily, so they must not drive redirects.
-export const onRequest: RequestHandler = ({ params, redirect, json }) => {
+// Note: a loader cannot read action state via `resolveValue(useForm)`. After an action
+// submission, the client invalidates loaders and refetches them as standalone GET
+// requests, which carry no action context — so `resolveValue(actionQrl)` returns
+// undefined. Read action state directly from the action signal (e.g. in the head, or
+// from `useForm.value` in components), not via a loader.
+export const useDependencyLoader = routeLoader$(async ({ params, redirect, json }) => {
+  await delay(100);
   if (params.id === 'redirect') {
     throw redirect(302, '/qwikrouter-test/');
   } else if (params.id === 'redirect-welcome') {
     throw redirect(302, '/qwikrouter-test/loaders/welcome/');
   } else if (params.id === 'json') {
     throw json(200, { nu: 42 });
   }
-};
-
-export const useDependencyLoader = routeLoader$(async ({ params }) => {
-  await delay(100);
   return {
     nu: 42,
     name: params.id,

e2e/qwik-e2e/apps/qwikrouter-test/src/routes/(common)/loaders/loader-error/index.tsx

@@ -6,7 +6,6 @@ const useError = routeLoader$(async function ({ error }): Promise<string> {
 });
 
 export default component$(() => {
-  // Lazy data-only loader: it fails, but nothing reads its value, so SSR is unaffected.
   useError();
-  return <div id="loader-error-rendered">rendered</div>;
+  return <></>;
 });

e2e/qwik-e2e/apps/qwikrouter-test/src/routes/(common)/loaders/loader-error/uncaught-server/index.tsx

@@ -11,7 +11,6 @@ const useCatchServerErrorInLoader = routeLoader$(async () => {
 });
 
 export default component$(() => {
-  // Lazy data-only loader: it fails, but nothing reads its value, so SSR is unaffected.
   useCatchServerErrorInLoader();
-  return <div id="uncaught-server-rendered">rendered</div>;
+  return <></>;
 });

e2e/qwik-e2e/apps/qwikrouter-test/src/routes/(common)/loaders/non-blocking/index.tsx

@@ -0,0 +1,15 @@
+import { component$ } from '@qwik.dev/core';
+import { routeLoader$ } from '@qwik.dev/router';
+
+// blockSSR:false runs in the background and must not block or error the initial SSR response.
+export const useBackgroundError = routeLoader$(
+  async ({ error }): Promise<string> => {
+    throw error(401, 'background-loader-error');
+  },
+  { blockSSR: false }
+);
+
+export default component$(() => {
+  useBackgroundError();
+  return <div id="non-blocking-rendered">rendered</div>;
+});

e2e/qwik-e2e/apps/qwikrouter-test/src/routes/returned-control-flow/loader-error/index.tsx

@@ -0,0 +1,10 @@
+import { component$ } from '@qwik.dev/core';
+import { routeLoader$ } from '@qwik.dev/router';
+
+// Returns the error signal instead of throwing it.
+export const useErrorLoader = routeLoader$(({ error }) => error(401, 'returned-loader-error'));
+
+export default component$(() => {
+  useErrorLoader();
+  return <h1 id="returned-control-flow-loader-error">Should not render</h1>;
+});

e2e/qwik-e2e/apps/qwikrouter-test/src/routes/returned-control-flow/loader-redirect/index.tsx

@@ -0,0 +1,12 @@
+import { component$ } from '@qwik.dev/core';
+import { routeLoader$ } from '@qwik.dev/router';
+
+// Returns the redirect signal instead of throwing it.
+export const useRedirectLoader = routeLoader$(({ redirect }) =>
+  redirect(302, '/qwikrouter-test/returned-control-flow/target/')
+);
+
+export default component$(() => {
+  useRedirectLoader();
+  return <h1 id="returned-control-flow-loader-redirect">Should not render</h1>;
+});

e2e/qwik-e2e/tests/qwikrouter/loaders.e2e.ts

@@ -177,20 +177,33 @@ test.describe('loaders', () => {
       await expect(page.locator('#prop-unwrapped')).toHaveText('test');
     });
 
-    test('a failing loader does not affect SSR when its value is not read', async ({ page }) => {
+    test('should modify ServerError in middleware', async ({ page }) => {
       const response = await page.goto('/qwikrouter-test/loaders/loader-error');
+      const contentType = await response?.headerValue('Content-Type');
+      const status = response?.status();
 
-      expect(response?.status()).toEqual(200);
-      await expect(page.locator('#loader-error-rendered')).toBeVisible();
+      expect(status).toEqual(401);
+      expect(contentType).toEqual('text/html; charset=utf-8');
+      const body = page.locator('body');
+      await expect(body).toContainText('loader-error-caught');
     });
 
-    test('a loader awaiting a failing server$ does not affect SSR when unread', async ({
-      page,
-    }) => {
+    test('should return html with uncaught ServerErrors thrown in loaders', async ({ page }) => {
       const response = await page.goto('/qwikrouter-test/loaders/loader-error/uncaught-server');
+      const contentType = await response?.headerValue('Content-Type');
+      const status = response?.status();
+
+      expect(status).toEqual(401);
+      expect(contentType).toEqual('text/html; charset=utf-8');
+      const body = page.locator('body');
+      await expect(body).toContainText('server-error-data');
+    });
+
+    test('a blockSSR:false loader does not block or error SSR when unread', async ({ page }) => {
+      const response = await page.goto('/qwikrouter-test/loaders/non-blocking/');
 
       expect(response?.status()).toEqual(200);
-      await expect(page.locator('#uncaught-server-rendered')).toBeVisible();
+      await expect(page.locator('#non-blocking-rendered')).toBeVisible();
     });
 
     test('should not serialize loaders by default and serialize with serializationStrategy: always', async ({

e2e/qwik-e2e/tests/qwikrouter/returned-control-flow.e2e.ts

@@ -3,14 +3,23 @@ import { expect, test } from '@playwright/test';
 const base = '/qwikrouter-test/returned-control-flow';
 
 // Returning ev.redirect()/ev.error() must behave the same as throwing them.
-// Route loaders are data-only and lazy, so route control flow belongs in request
-// handlers/actions (eager), not loaders — hence no loader cases here.
 test.describe('returned control-flow signals', () => {
+  test('loader returning redirect redirects', async ({ page }) => {
+    await page.goto(`${base}/loader-redirect/`);
+    await expect(page.locator('#returned-control-flow-target')).toBeVisible();
+  });
+
   test('request handler returning redirect redirects', async ({ page }) => {
     await page.goto(`${base}/handler-redirect/`);
     await expect(page.locator('#returned-control-flow-target')).toBeVisible();
   });
 
+  test('loader returning error renders the error response', async ({ page }) => {
+    const response = await page.goto(`${base}/loader-error/`);
+    expect(response?.status()).toEqual(401);
+    await expect(page.locator('body')).toContainText('returned-loader-error');
+  });
+
   test('action returning error responds with the error status', async ({ page }) => {
     await page.goto(`${base}/action-error/`);
     // Submit via the real form so the request carries a valid Origin (passes CSRF).

packages/docs/src/routes/docs/(qwikrouter)/route-loader/index.mdx

@@ -55,6 +55,7 @@ A few properties of route loaders:
 - **Keyed by route, not by call site.** Two visits to the same URL share one logical "result" per "route + url params + search params" set, not one per `useProductDetails()` call.
 - **Result is an `AsyncSignal`.** Components read `.value`, watch `.loading`, and check `.error`. Reading `.value` while the signal is in error state re-throws the error.
 - **Each loader has its own JSON endpoint.** The client fetches `q-loader-{id}.{hash}.json` for navigation, polling, and post-action invalidation. Browser HTTP cache, ETags, and the `expires` option all apply.
+- **Blocks SSR by default.** The server awaits the loader before rendering the page, so a `throw redirect()` or `throw error()` controls the response. Opt out with `blockSSR: false` to run it in the background — see [Background loaders](#background-loaders-blockssr).
 
 This means a `routeLoader$()` should be a **pure function of the URL**: same `params` and `search` → same response. Mixing in any other input (action state, request bodies, one-shot tokens) makes the cached responses inconsistent — see [Loaders cannot read action state](#loaders-cannot-read-action-state).
 
@@ -97,7 +98,7 @@ Loaders signal failure two ways:
 - **`throw requestEvent.error(status, data)`** — throw a `ServerError` directly. `signal.error` is `ServerError {status, data}`. Reading `signal.value` re-throws the error, so you should branch on `signal.error` first. This is the recommended way to signal failure from a loader.
 - **`return requestEvent.fail(status, data)`** — returns an inline failure. `signal.value.failed` is `true` and `signal.value` contains the rest of the data.
 
-In both cases, the HTTP response status is set to `status`, and the result is not cacheable.
+In both cases the result is not cacheable. For a blocking loader (the default) the HTTP response status is also set to `status`; a `blockSSR: false` loader is isolated from the page response — see [Background loaders](#background-loaders-blockssr).
 
 ## Multiple `routeLoader$`s
 
@@ -256,6 +257,23 @@ export default () => ({
 
 When using lazy-loaded data, branch on `.loading` to show a placeholder until it arrives — see [Reading the result in a component](#reading-the-result-in-a-component).
 
+## Background loaders (`blockSSR`)
+
+By default a loader **blocks SSR**: the server awaits it before rendering, so a `throw redirect()` or `throw error()` short-circuits the HTTP response. When several loaders block, the first one — in route order — to redirect or error wins.
+
+Set `blockSSR: false` to run a loader in the background instead. The server starts it but does not wait: rendering begins immediately, and reading `.value` suspends only that read until the loader resolves. This starts SSR sooner, and is the recommended setting, unless you need to control the request from the loader.
+
+```tsx title="src/routes/product/[productId]/index.tsx"
+export const useRecommendations = routeLoader$(
+  async ({ params }) => fetchRecommendations(params.productId),
+  { blockSSR: false }
+);
+```
+
+A background loader is treated as a **separate request**: it cannot redirect or error the page response. If it calls `redirect()` or `error()`, that control flow is captured on its own signal (surfacing when `.value` is read) and never changes the page's status or headers. Keep route guards that must redirect or set a status in a [request handler](/docs/middleware) such as `onRequest`, or in a blocking loader.
+
+Note: when the client fetches a background loader for SPA navigation, there is no difference between a blocking and non-blocking loader — the SPA fetch is always async, and the page is already rendered. Errors are not surfaced directly, but redirects are followed automatically.
+
 ## Accessing `RequestEvent`
 
 The loader function receives the same [`RequestEvent`](/docs/middleware#requestevent) as middleware. Use it to read params, headers, cookies, the URL, and so on.
@@ -341,6 +359,7 @@ export default component$(() => {
 | `poll`                  | `false`      | Auto-refetch when expired, but only while components are reading the loader.                          |
 | `allowStale`            | `true`       | Show stale data while refetching. `false` blocks readers until fresh data arrives.                    |
 | `serializationStrategy` | `'never'`    | `'never'` / `'always'` / `'auto'` — embed loader data in the SSR HTML?                                |
+| `blockSSR`              | `true`       | Await the loader before SSR (can redirect/error the response). `false` runs it in the background.     |
 | `eTag`                  | —            | `true` (auto-hash), string, or `(ev) => string \| null`. Returns 304 on match.                       |
 | `search`                | `[]` *       | Allowlist of search params the loader depends on. *(default `[]` when `strictLoaders` is enabled)*    |
 | `validation`            | —            | Array of [`DataValidator`](/docs/(qwikrouter)/validator/index.mdx)s applied before the loader runs.   |