fix(router): lazy routeloaders

Author: wmertens

.changeset/lazy-route-loaders.md

@@ -0,0 +1,5 @@
+---
+'@qwik.dev/router': major
+---
+
+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.

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

@@ -3,6 +3,7 @@ import {
   type DocumentHead,
   Form,
   Link,
+  type RequestHandler,
   routeAction$,
   routeLoader$,
   z,
@@ -12,20 +13,20 @@ import { delay } from '../../actions/login';
 
 export const useDateLoader = routeLoader$(() => new Date('2021-01-01T00:00:00.000Z'));
 
-// 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);
+// 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 }) => {
   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,6 +6,7 @@ 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 <></>;
+  return <div id="loader-error-rendered">rendered</div>;
 });

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

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

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

@@ -177,26 +177,20 @@ test.describe('loaders', () => {
       await expect(page.locator('#prop-unwrapped')).toHaveText('test');
     });
 
-    test('should modify ServerError in middleware', async ({ page }) => {
+    test('a failing loader does not affect SSR when its value is not read', async ({ page }) => {
       const response = await page.goto('/qwikrouter-test/loaders/loader-error');
-      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('loader-error-caught');
+      expect(response?.status()).toEqual(200);
+      await expect(page.locator('#loader-error-rendered')).toBeVisible();
     });
 
-    test('should return html with uncaught ServerErrors thrown in loaders', async ({ page }) => {
+    test('a loader awaiting a failing server$ does not affect SSR when unread', 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');
+      expect(response?.status()).toEqual(200);
+      await expect(page.locator('#uncaught-server-rendered')).toBeVisible();
     });
 
     test('should not serialize loaders by default and serialize with serializationStrategy: always', async ({

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

@@ -3,23 +3,14 @@ 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).

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

@@ -310,23 +310,22 @@ function createResolveRequestHandlers() {
   }
 
   function loadersMiddleware(routeLoaders: LoaderInternal[], route: LoadedRoute): RequestHandler {
-    return async (requestEvent: RequestEvent) => {
+    return (requestEvent: RequestEvent) => {
       const requestEv = requestEvent as RequestEventInternal;
       if (requestEv.headersSent) {
         requestEv.exit();
         return;
       }
-      if (routeLoaders.length > 0) {
-        setLoaderData(requestEv, routeLoaders, route);
+      if (routeLoaders.length === 0) {
+        return;
+      }
+      setLoaderData(requestEv, routeLoaders, route);
 
-        // Run loaders directly and store raw values.
-        // Errors/redirects propagate so middleware can catch them (e.g. plugin@errors).
-        const loaderValues = getRouteLoaderValues(requestEv);
-        await Promise.all(
-          routeLoaders.map(async (loader) => {
-            loaderValues[loader.__id] = await loadRouteLoader(loader, requestEv);
-          })
-        );
+      // Start every loader concurrently but don't await them: render only blocks on — and only
+      // fails from — loaders whose .value it reads. Swallowing rejections keeps an unread failing
+      // loader from crashing the request; the error resurfaces if .value is read during render.
+      for (const loader of routeLoaders) {
+        loadRouteLoader(loader, requestEv).catch(() => {});
       }
     };
   }

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

@@ -369,6 +369,92 @@ describe('resolve-request-handler', () => {
     });
   });
 
+  describe('lazy loaders middleware', () => {
+    function makeLoader(
+      id: string,
+      impl: (...args: any[]) => unknown,
+      strategy: 'never' | 'always' = 'never'
+    ) {
+      const loader: any = () => {};
+      loader.__brand = 'server_loader';
+      loader.__id = id;
+      loader.__qrl = { call: (_thisArg: unknown, ev: unknown) => impl(ev), getHash: () => id };
+      loader.__validators = undefined;
+      loader.__serializationStrategy = strategy;
+      loader.__search = undefined;
+      return loader;
+    }
+
+    function pageRouteWithLoader(loader: unknown): LoadedRoute {
+      return {
+        $routeName$: '/',
+        $params$: {},
+        $mods$: [{ useData: loader }, { default: () => null }] as any,
+        $errorLoader$: vi.fn(async () => ({ default: () => null })),
+      };
+    }
+
+    function runPage(route: LoadedRoute, renderHandler: any) {
+      globalThis.__NO_TRAILING_SLASH__ = false;
+      const handlers = resolveRequestHandlers(undefined, route, 'GET', true, renderHandler);
+      const requestEv = createRequestEvent(
+        createMockServerRequestEvent('http://localhost:3000/'),
+        route,
+        handlers,
+        '/',
+        vi.fn()
+      );
+      return requestEv;
+    }
+
+    it('starts loaders during the request even when render never reads them', async () => {
+      const impl = vi.fn(() => 'value');
+      const route = pageRouteWithLoader(makeLoader('l1', impl));
+      const renderHandler = vi.fn((requestEv: { exit: () => void }) => {
+        requestEv.exit();
+      });
+      const requestEv = runPage(route, renderHandler);
+
+      await requestEv.next();
+
+      expect(impl).toHaveBeenCalledTimes(1);
+      expect(renderHandler).toHaveBeenCalledOnce();
+    });
+
+    it('does not await loaders before render', async () => {
+      let release!: () => void;
+      const gate = new Promise<string>((resolve) => (release = () => resolve('late')));
+      const route = pageRouteWithLoader(makeLoader('l1', () => gate));
+      const renderHandler = vi.fn((requestEv: { exit: () => void }) => {
+        requestEv.exit();
+      });
+      const requestEv = runPage(route, renderHandler);
+
+      // Resolves without awaiting the still-pending loader; eager middleware would hang here.
+      await requestEv.next();
+
+      expect(renderHandler).toHaveBeenCalledOnce();
+      release();
+    });
+
+    it('does not let an unread failing loader affect the response', async () => {
+      const route = pageRouteWithLoader(
+        makeLoader('l1', () => {
+          throw new ServerError(401, 'boom');
+        })
+      );
+      const renderHandler = vi.fn((requestEv: { exit: () => void }) => {
+        requestEv.exit();
+      });
+      const requestEv = runPage(route, renderHandler);
+
+      await expect(requestEv.next()).resolves.toBeUndefined();
+
+      expect(renderHandler).toHaveBeenCalledOnce();
+      expect(requestEv.status()).toBe(200);
+    });
+  });
+
   describe('action result resolution', () => {
     it('always returns undefined for actions, even when one was submitted', async () => {
       // Loaders must be a pure function of the URL — see route-loader docs and the