WIP

Author: wmertens

.changeset/green-experts-turn.md

@@ -0,0 +1,3 @@
+'@qwik.dev/router': minor
+
+Refactor route loaders to be backed by shared async signals across SSR, client refresh, and action invalidation.

packages/docs/src/routes/api/qwik-router/api.json

@@ -698,7 +698,7 @@
         }
       ],
       "kind": "Interface",
-      "content": "```typescript\nexport interface QwikRouterEnvData \n```\n\n\n<table><thead><tr><th>\n\nProperty\n\n\n</th><th>\n\nModifiers\n\n\n</th><th>\n\nType\n\n\n</th><th>\n\nDescription\n\n\n</th></tr></thead>\n<tbody><tr><td>\n\nev\n\n\n</td><td>\n\n\n</td><td>\n\nRequestEvent\n\n\n</td><td>\n\n\n</td></tr>\n<tr><td>\n\nloadedRoute\n\n\n</td><td>\n\n\n</td><td>\n\nLoadedRoute\n\n\n</td><td>\n\n\n</td></tr>\n<tr><td>\n\nparams\n\n\n</td><td>\n\n\n</td><td>\n\n[PathParams](#pathparams)\n\n\n</td><td>\n\n\n</td></tr>\n<tr><td>\n\nresponse\n\n\n</td><td>\n\n\n</td><td>\n\nEndpointResponse\n\n\n</td><td>\n\n\n</td></tr>\n<tr><td>\n\nrouteName\n\n\n</td><td>\n\n\n</td><td>\n\nstring\n\n\n</td><td>\n\n\n</td></tr>\n</tbody></table>",
+      "content": "```typescript\nexport interface QwikRouterEnvData \n```\n\n\n<table><thead><tr><th>\n\nProperty\n\n\n</th><th>\n\nModifiers\n\n\n</th><th>\n\nType\n\n\n</th><th>\n\nDescription\n\n\n</th></tr></thead>\n<tbody><tr><td>\n\nev\n\n\n</td><td>\n\n\n</td><td>\n\nRequestEvent\n\n\n</td><td>\n\n\n</td></tr>\n<tr><td>\n\nloadedRoute\n\n\n</td><td>\n\n\n</td><td>\n\nLoadedRoute\n\n\n</td><td>\n\n\n</td></tr>\n<tr><td>\n\nloaderState\n\n\n</td><td>\n\n\n</td><td>\n\nRecord&lt;string, import('@qwik.dev/core/internal').AsyncSignal&lt;unknown&gt;&gt;\n\n\n</td><td>\n\n\n</td></tr>\n<tr><td>\n\nparams\n\n\n</td><td>\n\n\n</td><td>\n\n[PathParams](#pathparams)\n\n\n</td><td>\n\n\n</td></tr>\n<tr><td>\n\nresponse\n\n\n</td><td>\n\n\n</td><td>\n\nEndpointResponse\n\n\n</td><td>\n\n\n</td></tr>\n<tr><td>\n\nrouteLoaderCtx\n\n\n</td><td>\n\n\n</td><td>\n\nimport('./route-loaders').RouteLoaderCtx\n\n\n</td><td>\n\n\n</td></tr>\n<tr><td>\n\nrouteName\n\n\n</td><td>\n\n\n</td><td>\n\nstring\n\n\n</td><td>\n\n\n</td></tr>\n</tbody></table>",
       "editUrl": "https://github.com/QwikDev/qwik/tree/main/packages/qwik-router/src/runtime/src/types.ts",
       "mdFile": "router.qwikrouterenvdata.md"
     },
@@ -895,7 +895,7 @@
       ],
       "kind": "Variable",
       "content": "```typescript\nrouteLoader$: LoaderConstructor\n```",
-      "editUrl": "https://github.com/QwikDev/qwik/tree/main/packages/qwik-router/src/runtime/src/server-functions.ts",
+      "editUrl": "https://github.com/QwikDev/qwik/tree/main/packages/qwik-router/src/runtime/src/route-loaders.ts",
       "mdFile": "router.routeloader_.md"
     },
     {

packages/docs/src/routes/api/qwik-router/index.mdx

@@ -1606,6 +1606,19 @@ LoadedRoute
 </td></tr>
 <tr><td>
 
+loaderState
+
+</td><td>
+
+</td><td>
+
+Record&lt;string, import('@qwik.dev/core/internal').AsyncSignal&lt;unknown&gt;&gt;
+
+</td><td>
+
+</td></tr>
+<tr><td>
+
 params
 
 </td><td>
@@ -1632,6 +1645,19 @@ EndpointResponse
 </td></tr>
 <tr><td>
 
+routeLoaderCtx
+
+</td><td>
+
+</td><td>
+
+import('./route-loaders').RouteLoaderCtx
+
+</td><td>
+
+</td></tr>
+<tr><td>
+
 routeName
 
 </td><td>
@@ -2312,7 +2338,7 @@ _(Optional)_ Array of routeLoader$ hashes for this node's loaders
 routeLoader$: LoaderConstructor;
 ```
 
-[Edit this section](https://github.com/QwikDev/qwik/tree/main/packages/qwik-router/src/runtime/src/server-functions.ts)
+[Edit this section](https://github.com/QwikDev/qwik/tree/main/packages/qwik-router/src/runtime/src/route-loaders.ts)
 
 <h2 id="routelocation">RouteLocation</h2>
 

packages/qwik-router/src/buildtime/runtime-generation/generate-routes.ts

@@ -324,6 +324,12 @@ function serializeBuildTrie(
     const routeFiles = node._files
       .filter((f) => f.type === 'route' || f.type === 'layout')
       .map((f) => f.filePath);
+    // Include server plugin files at the root trie node (they apply to all routes)
+    if (node === ctx.routeTrie) {
+      for (const plugin of ctx.serverPlugins) {
+        routeFiles.push(plugin.filePath);
+      }
+    }
     if (routeFiles.length > 0) {
       const nodeLoaderHashes: string[] = [];
       if (loadersByFile) {

packages/qwik-router/src/middleware/request-handler/handlers/action-handler.ts

@@ -1,19 +1,13 @@
-import { _serialize, _UNINITIALIZED, _verifySerializable, isDev } from '@qwik.dev/core/internal';
+import { _serialize, _verifySerializable, isDev } from '@qwik.dev/core/internal';
 import type {
   ActionInternal,
   DataValidator,
   JSONObject,
-  LoaderInternal,
   RequestEvent,
   RequestHandler,
   ValidatorReturn,
 } from '../../../runtime/src/types';
-import {
-  getRequestLoaders,
-  getRequestLoaderSerializationStrategyMap,
-  type RequestEventInternal,
-} from '../request-event-core';
-import { getRouteLoaderPromise } from '../request-loader';
+import { type RequestEventInternal } from '../request-event-core';
 import { IsQAction, QActionId } from '../request-path';
 import type { QRL } from '@qwik.dev/core';
 import type { RequestEventBase } from '../types';
@@ -26,7 +20,7 @@ import type { RequestEventBase } from '../types';
  */
 export function actionHandler(
   routeActions: ActionInternal[],
-  routeLoaders: LoaderInternal[]
+  routeLoaderHashes: string[]
 ): RequestHandler {
   return async (requestEvent: RequestEvent) => {
     const requestEv = requestEvent as RequestEventInternal;
@@ -60,8 +54,6 @@ export function actionHandler(
       return;
     }
 
-    const loaders = getRequestLoaders(requestEv);
-
     // Find the action
     let action: ActionInternal | undefined;
     for (const routeAction of routeActions) {
@@ -89,9 +81,10 @@ export function actionHandler(
       throw new Error(`Expected request data for the action id ${actionId} to be an object`);
     }
 
+    let actionResult: unknown;
     const result = await runValidators(requestEv, action.__validators, data, devMode);
     if (!result.success) {
-      loaders[actionId] = requestEv.fail(result.status ?? 500, result.error);
+      actionResult = requestEv.fail(result.status ?? 500, result.error);
     } else {
       const actionResolved = devMode
         ? await measure(requestEv, action.__qrl.getHash(), () =>
@@ -101,22 +94,15 @@ export function actionHandler(
       if (devMode) {
         verifySerializable(actionResolved, action.__qrl);
       }
-      loaders[actionId] = actionResolved;
-    }
-
-    // Run all route loaders after the action so they can see the action result
-    // via resolveValue() (loaders may depend on action results)
-    const loadersSerializationStrategy = getRequestLoaderSerializationStrategyMap(requestEv);
-    if (routeLoaders.length > 0) {
-      const loaderPromises = routeLoaders.map((loader) =>
-        getRouteLoaderPromise(loader, loaders, loadersSerializationStrategy, requestEv)
-      );
-      await Promise.all(loaderPromises);
+      actionResult = actionResolved;
     }
+    requestEv.sharedMap.set('@actionResult', actionResult);
 
-    // Return action result + all loader results as JSON
-    // The client uses this to update all loader signals after an action
-    const serialized = await _serialize(loaders);
+    const serialized = await _serialize({
+      result: actionResult,
+      // TODO get via `invalidate: [useUser, useEtc]` option
+      loaderHashes: routeLoaderHashes,
+    });
     requestEv.headers.set('Content-Type', 'application/json; charset=utf-8');
     requestEv.send(200, serialized);
   };

packages/qwik-router/src/middleware/request-handler/handlers/loader-handler.ts

@@ -1,47 +1,25 @@
-import { _serialize, _UNINITIALIZED, type ValueOrPromise } from '@qwik.dev/core/internal';
+import { _serialize } from '@qwik.dev/core/internal';
 import type {
   ActionInternal,
   LoaderInternal,
   RequestEvent,
   RequestHandler,
 } from '../../../runtime/src/types';
-import {
-  getRequestLoaders,
-  getRequestLoaderSerializationStrategyMap,
-  type RequestEventInternal,
-} from '../request-event-core';
-import { getRouteLoaderPromise } from '../request-loader';
+import { type RequestEventInternal } from '../request-event-core';
 import { IsQLoader, QLoaderId } from '../request-path';
-
-/**
- * Middleware that executes ALL route loaders (used during SSR page rendering). This is the same as
- * the existing loadersMiddleware but extracted for clarity.
- */
-export function loadersMiddleware(routeLoaders: LoaderInternal[]): RequestHandler {
-  return async (requestEvent: RequestEvent) => {
-    const requestEv = requestEvent as RequestEventInternal;
-    if (requestEv.headersSent) {
-      requestEv.exit();
-      return;
-    }
-    const loaders = getRequestLoaders(requestEv);
-    const loadersSerializationStrategy = getRequestLoaderSerializationStrategyMap(requestEv);
-    if (routeLoaders.length > 0) {
-      const resolvedLoadersPromises = routeLoaders.map((loader) =>
-        getRouteLoaderPromise(loader, loaders, loadersSerializationStrategy, requestEv)
-      );
-      await Promise.all(resolvedLoadersPromises);
-    }
-  };
-}
+import {
+  getRouteLoaderData,
+  resolveRouteLoaderByHash,
+  LOADER_URL_HEADER,
+} from '../../../runtime/src/route-loaders';
 
 /**
  * Handler for individual loader fetch requests (`/path/q-loader-{id}.{hash}.json`). Runs only the
  * requested loader and returns its serialized result as JSON.
  */
 export function loaderHandler(
   routeLoaders: LoaderInternal[],
-  routeActions: ActionInternal[]
+  _routeActions: ActionInternal[]
 ): RequestHandler {
   return async (requestEvent: RequestEvent) => {
     const requestEv = requestEvent as RequestEventInternal;
@@ -55,30 +33,31 @@ export function loaderHandler(
     }
 
     const loaderId = requestEv.sharedMap.get(QLoaderId) as string;
-    const loaders = getRequestLoaders(requestEv);
-    const loadersSerializationStrategy = getRequestLoaderSerializationStrategyMap(requestEv);
-
-    // Find the requested loader
-    let loader: LoaderInternal | undefined;
-    for (const routeLoader of routeLoaders) {
-      if (routeLoader.__id === loaderId) {
-        loader = routeLoader;
-      } else if (!loaders[routeLoader.__id]) {
-        // Other loaders set to _UNINITIALIZED so resolveValue() can trigger them on demand
-        loaders[routeLoader.__id] = _UNINITIALIZED as unknown as ValueOrPromise<unknown>;
-      }
-    }
+    const loader = resolveRouteLoaderByHash(routeLoaders, loaderId);
 
     if (!loader) {
       requestEv.json(404, { error: 'Loader not found' });
       return;
     }
 
-    // Execute the loader
-    await getRouteLoaderPromise(loader, loaders, loadersSerializationStrategy, requestEv);
+    // Use the X-Qwik-Loader-URL header to reconstruct the actual page URL.
+    // The physical request goes to /path/q-loader-{id}.{hash}.json but the loader
+    // function should see the real page URL (with search params, etc.)
+    const loaderUrl = requestEv.request.headers.get(LOADER_URL_HEADER);
+    if (loaderUrl) {
+      try {
+        const pageUrl = new URL(loaderUrl, requestEv.url.origin);
+        // Override URL properties so the loader sees the real page URL
+        requestEv.url.pathname = pageUrl.pathname;
+        requestEv.url.search = pageUrl.search;
+        requestEv.url.hash = pageUrl.hash;
+      } catch {
+        // Invalid URL header — ignore and use the trimmed URL
+      }
+    }
 
-    // Serialize and return just this loader's result
-    const data = await _serialize([loaders[loaderId]]);
+    const result = await getRouteLoaderData(loader.__qrl, loader.__validators, requestEv);
+    const data = await _serialize([result]);
     requestEv.headers.set('Content-Type', 'application/json; charset=utf-8');
 
     // Set cache headers based on loader's expires option

packages/qwik-router/src/middleware/request-handler/middleware.request-handler.api.md

@@ -16,7 +16,6 @@ import type { RenderOptions } from '@qwik.dev/core/server';
 import { RequestEvent as RequestEvent_2 } from '@qwik.dev/router/middleware/request-handler';
 import type { RequestHandler as RequestHandler_2 } from '@qwik.dev/router/middleware/request-handler';
 import type { ResolveSyncValue as ResolveSyncValue_2 } from '@qwik.dev/router/middleware/request-handler';
-import { SerializationStrategy } from '@qwik.dev/core/internal';
 import type { ValueOrPromise } from '@qwik.dev/core';
 
 // @public (undocumented)

packages/qwik-router/src/middleware/request-handler/request-event-core.ts

@@ -1,17 +1,16 @@
-import type { ValueOrPromise } from '@qwik.dev/core';
-import {
-  _deserialize,
-  _UNINITIALIZED,
-  isDev,
-  type SerializationStrategy,
-} from '@qwik.dev/core/internal';
+import { _deserialize, isDev } from '@qwik.dev/core/internal';
 import type {
   ActionInternal,
   FailReturn,
   JSONValue,
   LoadedRoute,
   LoaderInternal,
 } from '../../runtime/src/types';
+import {
+  ensureRouteLoaderSignal,
+  getRouteLoaderState,
+  getRouteLoaderCtx,
+} from '../../runtime/src/route-loaders';
 import type { AbortMessage, RedirectMessage } from './redirect-handler';
 import type { RewriteMessage } from './rewrite-handler';
 import type { ServerError } from './server-error';
@@ -37,7 +36,6 @@ interface RequestEventDeps {
   RedirectMessage: new () => RedirectMessage;
   RewriteMessage: new (pathname: string) => RewriteMessage;
   ServerError: new <T = any>(status: number, data: T) => ServerError<T>;
-  getRouteLoaderPromise: typeof import('./request-loader').getRouteLoaderPromise;
   recognizeRequest: typeof import('./request-path').recognizeRequest;
   IsQLoader: string;
   IsQAction: string;
@@ -48,12 +46,8 @@ interface RequestEventDeps {
   getContentType: typeof import('./request-utils').getContentType;
 }
 
-const RequestEvLoaders = Symbol('RequestEvLoaders');
 const RequestEvMode = Symbol('RequestEvMode');
 const RequestEvRoute = Symbol('RequestEvRoute');
-export const RequestEvLoaderSerializationStrategyMap = Symbol(
-  'RequestEvLoaderSerializationStrategyMap'
-);
 export const RequestRouteName = '@routeName';
 export const RequestEvSharedActionId = '@actionId';
 export const RequestEvSharedActionFormData = '@actionFormData';
@@ -181,10 +175,7 @@ export function createRequestEventWithDeps(
     return message;
   };
 
-  const loaders: Record<string, ValueOrPromise<unknown> | undefined> = {};
   const requestEv: RequestEventInternal = {
-    [RequestEvLoaders]: loaders,
-    [RequestEvLoaderSerializationStrategyMap]: new Map(),
     [RequestEvMode]: serverRequestEv.mode,
     get [RequestEvRoute]() {
       return loadedRoute;
@@ -231,25 +222,18 @@ export function createRequestEventWithDeps(
     },
 
     resolveValue: (async (loaderOrAction: LoaderInternal | ActionInternal) => {
-      // create user request event, which is a narrowed down request context
-      const id = loaderOrAction.__id;
       if (loaderOrAction.__brand === 'server_loader') {
-        if (!(id in loaders)) {
-          throw new Error(
-            'You can not get the returned data of a loader that has not been executed for this request.'
-          );
-        }
-        if (loaders[id] === _UNINITIALIZED) {
-          await deps.getRouteLoaderPromise(
-            loaderOrAction,
-            loaders,
-            requestEv[RequestEvLoaderSerializationStrategyMap],
-            requestEv
-          );
+        const loaderState = getRouteLoaderState(requestEv);
+        const routeLoaderCtx = getRouteLoaderCtx(requestEv);
+        const signal = ensureRouteLoaderSignal(loaderOrAction, loaderState, routeLoaderCtx);
+        if (signal.loading) {
+          await signal.promise();
         }
+        return signal.value;
       }
 
-      return loaders[id];
+      // Action result
+      return requestEv.sharedMap.get('@actionResult');
     }) as ResolveValue,
 
     status: (statusCode?: number) => {
@@ -379,8 +363,6 @@ export function createRequestEventWithDeps(
 }
 
 export interface RequestEventInternal extends Readonly<RequestEvent>, Readonly<RequestEventLoader> {
-  readonly [RequestEvLoaders]: Record<string, ValueOrPromise<unknown> | undefined>;
-  readonly [RequestEvLoaderSerializationStrategyMap]: Map<string, SerializationStrategy>;
   readonly [RequestEvMode]: ServerRequestMode;
   readonly [RequestEvRoute]: LoadedRoute;
 
@@ -405,14 +387,6 @@ export interface RequestEventInternal extends Readonly<RequestEvent>, Readonly<R
   ): void;
 }
 
-export function getRequestLoaders(requestEv: RequestEventCommon) {
-  return (requestEv as RequestEventInternal)[RequestEvLoaders];
-}
-
-export function getRequestLoaderSerializationStrategyMap(requestEv: RequestEventCommon) {
-  return (requestEv as RequestEventInternal)[RequestEvLoaderSerializationStrategyMap];
-}
-
 export function getRequestRoute(requestEv: RequestEventCommon) {
   return (requestEv as RequestEventInternal)[RequestEvRoute];
 }