arcway 0.4.14 → 0.4.16

package/client/router.js

@@ -23,9 +23,9 @@ import { parseQuery, stringifyQuery } from './query.js';
 const ROUTER_CTX_KEY = '__router_context__';
 const RouterContext = (globalThis[ROUTER_CTX_KEY] ??= createContext(null));
 
-function wrapInLayouts(element, layouts) {
+function wrapInLayouts(element, layouts, props = {}) {
   for (let i = layouts.length - 1; i >= 0; i--) {
-    element = createElement(layouts[i], null, element);
+    element = createElement(layouts[i], props, element);
   }
   return element;
 }
@@ -56,8 +56,10 @@ function useRouter() {
       pathname: ctx.pathname,
       params: ctx.params,
       query: typeof window !== 'undefined' ? parseQuery(window.location.search) : {},
-      push: (to, options) => ctx.navigate(normalizeNavigateTarget(to), { ...options, replace: false }),
-      replace: (to, options) => ctx.navigate(normalizeNavigateTarget(to), { ...options, replace: true }),
+      push: (to, options) =>
+        ctx.navigate(normalizeNavigateTarget(to), { ...options, replace: false }),
+      replace: (to, options) =>
+        ctx.navigate(normalizeNavigateTarget(to), { ...options, replace: true }),
       back: () => {
         if (typeof window !== 'undefined') window.history.back();
       },
@@ -77,6 +79,7 @@ function useRouter() {
 function Router({
   initialPath,
   initialParams,
+  initialPageProps,
   initialPattern,
   initialComponent,
   initialLayouts,
@@ -92,6 +95,7 @@ function Router({
     layouts: initialLayouts ?? [],
     loadings: initialLoadings ?? [],
     params: initialParams ?? {},
+    props: initialPageProps ?? initialParams ?? {},
   });
   const [isNavigating, setIsNavigating] = useState(false);
   const [isPending, startTransition] = useTransition();
@@ -140,6 +144,7 @@ function Router({
         layouts: loaded.layouts,
         loadings: loaded.loadings,
         params: loaded.params,
+        props: loaded.params,
       });
       setIsNavigating(false);
       if (bumpQuery) setQueryVersion((v) => v + 1);
@@ -158,8 +163,7 @@ function Router({
       const qIdx = to.indexOf('?');
       const pathOnly = qIdx === -1 ? to : to.slice(0, qIdx);
       const search = qIdx === -1 ? '' : to.slice(qIdx);
-      const currentSearch =
-        typeof window !== 'undefined' ? window.location.search : '';
+      const currentSearch = typeof window !== 'undefined' ? window.location.search : '';
 
       if (pathOnly === pathname && search === currentSearch) return;
 
@@ -184,6 +188,10 @@ function Router({
         window.location.href = to;
         return;
       }
+      if (matched.route.hasLoader) {
+        window.location.href = to;
+        return;
+      }
 
       setIsNavigating(true);
       if (replace) {
@@ -200,6 +208,7 @@ function Router({
           pattern: matched.route.pattern,
           loadings: targetLoadings,
           params: matched.params,
+          props: matched.params,
         }));
       }
 
@@ -244,6 +253,11 @@ function Router({
       }
 
       try {
+        const matched = matchClientRoute(manifest, newPath);
+        if (matched?.route.hasLoader) {
+          window.location.reload();
+          return;
+        }
         const loaded = await loadPage(manifest, newPath);
         if (loaded) {
           applyLoaded(loaded, newPath, true);
@@ -265,15 +279,15 @@ function Router({
     }
   }, [pageState.pattern]);
 
-  const { component: PageComponent, layouts, loadings, params } = pageState;
+  const { component: PageComponent, layouts, loadings, params, props } = pageState;
 
   let content;
   if (PageComponent) {
     const inner =
       isNavigating && loadings.length > 0
         ? createElement(loadings.at(-1))
-        : createElement(PageComponent, params);
-    content = wrapInLayouts(inner, layouts);
+        : createElement(PageComponent, props);
+    content = wrapInLayouts(inner, layouts, props);
   } else {
     content = children;
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "arcway",
-  "version": "0.4.14",
+  "version": "0.4.16",
   "description": "A convention-based framework for building modular monoliths with strict domain boundaries.",
   "license": "MIT",
   "type": "module",

package/server/bin/commands/start.js

@@ -1,4 +1,3 @@
-import boot from '#server/boot.js';
 import { loadEnvFiles } from '#server/env.js';
 
 async function startServer(mode) {
@@ -11,6 +10,11 @@ async function startServer(mode) {
   // dotenv never overrides already-set variables.
   loadEnvFiles(process.cwd(), mode);
 
+  // Importing the application boot graph loads React-backed page modules.
+  // Production mode must be established first so React and react-dom/server
+  // select matching builds. A static import here can cache development React
+  // before `arcway start` gets a chance to set NODE_ENV.
+  const { default: boot } = await import('#server/boot.js');
   const app = await boot({ mode, rootDir: process.cwd() });
   app.logger.info('Arcway framework ready', { mode, port: app.port });
 

package/server/config/modules/pages.js

@@ -72,6 +72,22 @@ function resolve(config, { rootDir } = {}) {
       ...(hmr ? { hmr } : {}),
     },
   };
+  if (pages.rewrite != null) {
+    if (
+      typeof pages.rewrite !== 'object' ||
+      Array.isArray(pages.rewrite) ||
+      typeof pages.rewrite.handler !== 'function' ||
+      typeof pages.rewrite.reservedPrefix !== 'string' ||
+      pages.rewrite.reservedPrefix === '/' ||
+      !pages.rewrite.reservedPrefix.startsWith('/') ||
+      pages.rewrite.reservedPrefix.endsWith('/') ||
+      /[?#\s]/.test(pages.rewrite.reservedPrefix)
+    ) {
+      throw new TypeError(
+        'Invalid config: pages.rewrite requires a handler function and a reservedPrefix such as "/_sites"',
+      );
+    }
+  }
   if (pages.dir && !path.isAbsolute(pages.dir)) {
     pages.dir = path.resolve(rootDir, pages.dir);
   }

package/server/mail/index.js

@@ -95,13 +95,9 @@ function registerSendJob(driver, queue, throughput) {
       handler: async () => {
         if (!queue) return;
         const items = await queue.pop(MAIL_TOPIC, 10);
-        const ids = [];
         for (const item of items) {
           await driver.send(item.data);
-          ids.push(item.id);
-        }
-        if (ids.length > 0) {
-          await queue.remove(ids);
+          await queue.remove([item.id]);
         }
       },
       throughput,

package/server/pages/build-client.js

@@ -6,6 +6,7 @@ import { resolveLayoutChain, resolveLoadingChain } from './discovery.js';
 import { clientIsolationPlugin } from './build-plugins.js';
 import { patternToFileName, layoutDirToFileName } from './build-server.js';
 import { reactRefreshPlugin } from './hmr.js';
+import { serverLoaderClientPlugin } from './server-loader-transform.js';
 import {
   sha256,
   ESBUILD_VERSION,
@@ -68,7 +69,14 @@ function planHydrationEntries(pages, layouts, loadings, tempDir) {
     entryPoints[loadingName] = navPath;
     entryToLoadingDir.set(navPath, loading.dirPath);
   }
-  return { files, entryPoints, entryToPattern, entryToNavPattern, entryToLayoutDir, entryToLoadingDir };
+  return {
+    files,
+    entryPoints,
+    entryToPattern,
+    entryToNavPattern,
+    entryToLayoutDir,
+    entryToLoadingDir,
+  };
 }
 
 function resolveReactAlias(rootDir) {
@@ -144,6 +152,7 @@ function buildClientEsbuildOptions({
   nodeEnv,
   reactAlias,
   rootDir,
+  pagePaths,
 }) {
   return {
     entryPoints,
@@ -162,7 +171,11 @@ function buildClientEsbuildOptions({
     metafile: true,
     alias: reactAlias,
     define: { 'process.env.NODE_ENV': JSON.stringify(nodeEnv) },
-    plugins: [...(devMode ? [reactRefreshPlugin(rootDir)] : []), clientIsolationPlugin()],
+    plugins: [
+      ...(devMode ? [reactRefreshPlugin(rootDir)] : []),
+      serverLoaderClientPlugin(pagePaths),
+      clientIsolationPlugin(),
+    ],
   };
 }
 
@@ -210,6 +223,7 @@ async function createClientBuildContext(
       nodeEnv,
       reactAlias,
       rootDir,
+      pagePaths: pages.map((page) => page.filePath),
     }),
   );
 
@@ -262,9 +276,7 @@ async function unlinkAll(absPaths) {
 // an atomic rename, so the served clientDir always contains exactly the
 // current build's outputs.
 async function collectStaleOutputs(metafile, clientDir) {
-  const currentOutputs = new Set(
-    Object.keys(metafile.outputs ?? {}).map((p) => path.resolve(p)),
-  );
+  const currentOutputs = new Set(Object.keys(metafile.outputs ?? {}).map((p) => path.resolve(p)));
   // Scope the scan to directories esbuild actually writes to. This keeps
   // sibling artifacts owned by other build steps (e.g. the HMR runtime under
   // `client/hmr/`) out of the GC set, since they will never appear in the
@@ -315,14 +327,7 @@ async function tryRestoreClientFromCache({ rootDir, clientDir, coarseKey }) {
   return { hit: true, bucket: lookup.bucket, metadata: deserializeMetadata(lookup.meta.metadata) };
 }
 
-async function storeClientInCache({
-  bucket,
-  coarseKey,
-  clientDir,
-  tempDir,
-  result,
-  metadata,
-}) {
+async function storeClientInCache({ bucket, coarseKey, clientDir, tempDir, result, metadata }) {
   const outputs = Object.keys(result.metafile.outputs)
     .map((p) => path.relative(clientDir, path.resolve(p)).replace(/\\/g, '/'))
     .filter((rel) => !rel.startsWith('..'));
@@ -403,6 +408,7 @@ async function buildClientBundles(
     nodeEnv,
     reactAlias,
     rootDir,
+    pagePaths: pages.map((page) => page.filePath),
   });
   const result = await limit(() => runClientEsbuild(plan, esbuildOptions, tempDir));
   const metadata = extractMetadata(result, plan, outDir);
@@ -494,9 +500,11 @@ function generateHydrationEntry(componentPath, layouts = [], loadings = [], patt
 const container = document.getElementById('__app');
 const propsEl = document.getElementById('__app_props');
 const props = propsEl ? JSON.parse(propsEl.textContent || '{}') : {};
+const routeParamsEl = document.getElementById('__app_route_params');
+const routeParams = routeParamsEl ? JSON.parse(routeParamsEl.textContent || '{}') : props;
 const ROOT_KEY = '__arcway_root__';
 const rootOwner = window;
-const element = <ApiProvider><Router initialPath={window.location.pathname} initialParams={props} initialPattern={${JSON.stringify(pattern)}} initialComponent={Component} initialLayouts={${layoutsArray}} initialLoadings={${loadingsArray}} /></ApiProvider>;
+const element = <ApiProvider><Router initialPath={window.location.pathname} initialParams={routeParams} initialPageProps={props} initialPattern={${JSON.stringify(pattern)}} initialComponent={Component} initialLayouts={${layoutsArray}} initialLoadings={${loadingsArray}} /></ApiProvider>;
 
 if (!container) {
   throw new Error('Arcway hydrate entry could not find #__app');

package/server/pages/build-manifest.js

@@ -39,6 +39,7 @@ function generateManifest(
     entries.push({
       pattern: page.pattern,
       paramNames: page.paramNames,
+      ...(page.hasLoader ? { hasLoader: true } : {}),
       ...(page.catchAllParam ? { catchAllParam: page.catchAllParam } : {}),
       serverBundle,
       clientBundle,

package/server/pages/discovery.js

@@ -7,6 +7,7 @@ import {
   sortBySpecificity,
   matchPattern,
 } from '../router/routes.js';
+import { hasServerLoaderExport } from './server-loader-transform.js';
 function dirDepth(dirPath) {
   return dirPath === '' ? 0 : dirPath.split(path.sep).length;
 }
@@ -49,6 +50,7 @@ async function discoverPages(pagesDir) {
     const fileName = path.basename(filePath);
     if (fileName.startsWith('_')) continue;
     const relPath = path.relative(pagesDir, filePath);
+    const source = await fs.readFile(filePath, 'utf8');
     const urlPattern = filePathToPattern(relPath);
     const { regex, paramNames, catchAllParam } = compilePattern(urlPattern);
     pages.push({
@@ -57,6 +59,7 @@ async function discoverPages(pagesDir) {
       paramNames,
       ...(catchAllParam ? { catchAllParam } : {}),
       filePath,
+      hasLoader: await hasServerLoaderExport(source, filePath),
     });
   }
   sortBySpecificity(pages);
@@ -125,9 +128,7 @@ function mapFileToAffected(filePath, manifest) {
   }
 
   const layoutEntries = asDirPathList(manifest.layouts);
-  const hitLayout = layoutEntries.find(
-    (l) => l.srcPath && path.resolve(l.srcPath) === target,
-  );
+  const hitLayout = layoutEntries.find((l) => l.srcPath && path.resolve(l.srcPath) === target);
   if (hitLayout) {
     result.layouts.push(hitLayout.dirPath);
     for (const entry of entries) {
@@ -139,9 +140,7 @@ function mapFileToAffected(filePath, manifest) {
   }
 
   const middlewareEntries = asDirPathList(manifest.middlewares);
-  const hitMw = middlewareEntries.find(
-    (m) => m.srcPath && path.resolve(m.srcPath) === target,
-  );
+  const hitMw = middlewareEntries.find((m) => m.srcPath && path.resolve(m.srcPath) === target);
   if (hitMw) {
     result.middlewares.push(hitMw.dirPath);
     for (const entry of entries) {
@@ -179,6 +178,7 @@ function buildPageManifestEntry(page, { layouts, middlewares, loadings }) {
     paramNames: page.paramNames,
     ...(page.catchAllParam ? { catchAllParam: page.catchAllParam } : {}),
     srcPath: path.resolve(page.filePath),
+    ...(page.hasLoader ? { hasLoader: true } : {}),
     layoutDirs: resolveLayoutChain(page.pattern, layouts).map((l) => l.dirPath),
     middlewareDirs: resolvePageMiddlewareChain(page.pattern, middlewares).map((m) => m.dirPath),
     loadingDirs: resolveLoadingChain(page.pattern, loadings).map((l) => l.dirPath),

package/server/pages/handler.js

@@ -1,5 +1,6 @@
 import path from 'node:path';
 import fs from 'node:fs';
+import { domainToASCII } from 'node:url';
 import { createRequire } from 'node:module';
 import { EventEmitter } from 'node:events';
 import { compilePattern, sortBySpecificity, matchPattern } from '../router/routes.js';
@@ -9,6 +10,7 @@ import {
   buildRouteCssLinkTags,
   buildScriptTags,
   loadComponent,
+  loadPageModule,
   renderErrorPage,
   renderPage,
   syncReactInternals,
@@ -33,6 +35,7 @@ function createPagesHandler(options) {
   let manifestPath = path.join(outDir, 'pages-manifest.json');
   const sessionConfig = options.session;
   const appContext = options.appContext ?? null;
+  const rewrite = options.rewrite ?? null;
   const mode = options.mode ?? 'production';
   const devMode = mode === 'development';
   const viteDev = options.viteDev === true;
@@ -57,6 +60,7 @@ function createPagesHandler(options) {
     rootDir,
     outDir,
     viteDev,
+    reservedPrefix: rewrite?.reservedPrefix,
   });
   let lastSeenVersion = lazyContext ? manifest.version : 0;
   const componentCache = new Map();
@@ -82,6 +86,7 @@ function createPagesHandler(options) {
       rootDir,
       outDir,
       viteDev,
+      reservedPrefix: rewrite?.reservedPrefix,
     });
     componentCache.clear();
     cacheVersion++;
@@ -110,6 +115,7 @@ function createPagesHandler(options) {
       rootDir,
       outDir,
       viteDev,
+      reservedPrefix: rewrite?.reservedPrefix,
     });
     componentCache.clear();
     cacheVersion++;
@@ -144,7 +150,8 @@ function createPagesHandler(options) {
   async function handle(req, res) {
     const method = req.method ?? 'GET';
     const url = req.url ?? '/';
-    const pathname = url.split('?')[0];
+    const requestUrl = new URL(url, 'http://arcway.internal');
+    const pathname = requestUrl.pathname;
     if (method !== 'GET') return false;
     // Internal `/_arcway/*` endpoints (dev only) resolve before the route
     // matcher so they can never be shadowed by a user-defined page.
@@ -173,20 +180,32 @@ function createPagesHandler(options) {
     // last request before we resolve the route.
     if (!lazyContext) reload();
     refreshFromLazy();
-    const matched = matchPageRoute(routes, pathname);
+    let requestContext;
+    let rewritten;
+    try {
+      requestContext = await createPageRequestContext({
+        req,
+        pathname,
+        internalPathname: pathname,
+        params: {},
+        requestUrl,
+        sessionConfig,
+        appContext,
+      });
+      rewritten = await resolvePageRewrite(rewrite, requestContext);
+    } catch (err) {
+      await renderRuntimeError(err, res);
+      return true;
+    }
+    if (rewritten.notFound) {
+      await renderNotFound(pathname);
+      return true;
+    }
+    const internalPathname = rewritten.pathname;
+    let matched = matchPageRoute(routes, internalPathname);
     if (!matched) {
-      if (manifest.notFoundBundle) {
-        await renderErrorPage(
-          manifest.notFoundBundle,
-          404,
-          { pathname },
-          outDir,
-          res,
-          componentCache,
-          manifest,
-          cacheVersion,
-          projectReact,
-        );
+      if (rewrite || manifest.notFoundBundle) {
+        await renderNotFound(pathname);
         return true;
       }
       return false;
@@ -210,20 +229,19 @@ function createPagesHandler(options) {
         return true;
       }
       refreshFromLazy();
-      const rematched = matchPageRoute(routes, pathname);
+      const rematched = matchPageRoute(routes, internalPathname);
       if (rematched) matched.route = rematched.route;
     }
+    requestContext.page.internalPathname = internalPathname;
+    requestContext.page.params = matched.params;
+    requestContext.page.query = matched.params;
     if (matched.route.middlewareServerBundles.length > 0) {
       const middlewareResult = await runPageMiddleware(
         matched.route,
-        matched.params,
-        pathname,
-        req,
         outDir,
         componentCache,
         cacheVersion,
-        sessionConfig,
-        appContext,
+        requestContext,
       );
       if (middlewareResult) {
         if (middlewareResult.redirect) {
@@ -246,6 +264,37 @@ function createPagesHandler(options) {
         return true;
       }
     }
+    let loaderResult;
+    try {
+      loaderResult = await runPageLoader(
+        matched.route,
+        matched.params,
+        outDir,
+        componentCache,
+        cacheVersion,
+        requestContext,
+      );
+    } catch (err) {
+      await renderRuntimeError(err, res);
+      return true;
+    }
+    if (loaderResult?.redirect) {
+      res.writeHead(loaderResult.status ?? 302, {
+        Location: loaderResult.redirect,
+        ...loaderResult.headers,
+      });
+      res.end();
+      return true;
+    }
+    if (loaderResult?.notFound) {
+      await renderNotFound(pathname);
+      return true;
+    }
+    const pageProps = {
+      ...matched.params,
+      ...(loaderResult?.props ?? {}),
+      ...(loaderResult?.metadata === undefined ? {} : { metadata: loaderResult.metadata }),
+    };
     try {
       await renderPage(
         matched.route,
@@ -261,11 +310,35 @@ function createPagesHandler(options) {
         devMode,
         viteDev,
         (err) => renderRuntimeError(err, res),
+        pageProps,
+        {
+          status: loaderResult?.status,
+          headers: loaderResult?.headers,
+        },
       );
     } catch (err) {
       await renderRuntimeError(err, res);
     }
     return true;
+
+    async function renderNotFound(originalPathname) {
+      if (manifest.notFoundBundle) {
+        await renderErrorPage(
+          manifest.notFoundBundle,
+          404,
+          { pathname: originalPathname },
+          outDir,
+          res,
+          componentCache,
+          manifest,
+          cacheVersion,
+          projectReact,
+        );
+      } else {
+        res.writeHead(404, getHtmlHeaders());
+        res.end('<h1>404 - Not Found</h1>');
+      }
+    }
   }
   return {
     handle,
@@ -329,6 +402,7 @@ function compileRoutes(manifest, { rootDir, outDir, viteDev } = {}) {
       middlewareServerBundles: entry.middlewareServerBundles ?? [],
       sharedChunks: entry.sharedChunks ?? [],
       sharedCssChunks: entry.sharedCssChunks ?? [],
+      hasLoader: entry.hasLoader === true,
     };
     if (viteDev) {
       route = buildViteRoute(route, { rootDir, outDir });
@@ -343,28 +417,51 @@ function matchPageRoute(routes, pathname) {
   if (!result) return null;
   return { route: result.match, params: result.params };
 }
-async function runPageMiddleware(
-  route,
-  params,
-  pathname,
+async function runPageMiddleware(route, outDir, componentCache, cacheVersion, ctx) {
+  for (const bundlePath of route.middlewareServerBundles) {
+    const fullPath = path.join(outDir, bundlePath);
+    const middlewareFn = await loadComponent(
+      fullPath,
+      `middleware:${bundlePath}`,
+      componentCache,
+      cacheVersion,
+    );
+    if (!middlewareFn || typeof middlewareFn !== 'function') {
+      continue;
+    }
+    const result = await middlewareFn(ctx);
+    if (result) {
+      return result;
+    }
+  }
+  return null;
+}
+
+async function createPageRequestContext({
   req,
-  outDir,
-  componentCache,
-  cacheVersion,
+  pathname,
+  internalPathname,
+  params,
+  requestUrl,
   sessionConfig,
   appContext,
-) {
+}) {
   const headers = flattenHeaders(req.headers);
   const cookies = parseCookies(req);
   const session = await resolveSession(cookies, sessionConfig);
   const page = {
+    host: normalizeHost(headers.host),
     pathname,
+    internalPathname,
+    params,
     query: params,
+    search: requestUrl.search,
+    searchParams: requestUrl.searchParams,
     headers,
     cookies,
     session,
   };
-  const ctx = appContext
+  return appContext
     ? {
         page,
         db: appContext.db,
@@ -377,34 +474,166 @@ async function runPageMiddleware(
         meta: appContext.meta,
       }
     : { page };
-  for (const bundlePath of route.middlewareServerBundles) {
-    const fullPath = path.join(outDir, bundlePath);
-    const middlewareFn = await loadComponent(
-      fullPath,
-      `middleware:${bundlePath}`,
-      componentCache,
-      cacheVersion,
-    );
-    if (!middlewareFn || typeof middlewareFn !== 'function') {
-      continue;
+}
+
+function normalizeHost(value) {
+  if (typeof value !== 'string' || !value || /[\s,/@?#]/.test(value)) return null;
+  const match = value.match(/^([^:]+?)(?::([0-9]+))?$/);
+  if (!match) return null;
+  const port = match[2] ? Number(match[2]) : null;
+  if (port !== null && (port < 1 || port > 65535)) return null;
+  const source = match[1].endsWith('.') ? match[1].slice(0, -1) : match[1];
+  const host = domainToASCII(source.toLowerCase());
+  if (
+    !host ||
+    host.length > 253 ||
+    !host
+      .split('.')
+      .every(
+        (label) =>
+          label.length > 0 && label.length <= 63 && /^[a-z0-9](?:[a-z0-9-]*[a-z0-9])?$/.test(label),
+      )
+  ) {
+    return null;
+  }
+  return host;
+}
+
+async function resolvePageRewrite(rewrite, ctx) {
+  if (!rewrite) return { pathname: ctx.page.pathname };
+  const { reservedPrefix, handler } = rewrite;
+  if (
+    !ctx.page.host ||
+    ctx.page.pathname === reservedPrefix ||
+    ctx.page.pathname.startsWith(`${reservedPrefix}/`)
+  ) {
+    return { notFound: true };
+  }
+  const result = await handler(ctx);
+  if (!result) return { pathname: ctx.page.pathname };
+  if (result.notFound === true) return { notFound: true };
+  if (
+    typeof result.pathname !== 'string' ||
+    (result.pathname !== reservedPrefix && !result.pathname.startsWith(`${reservedPrefix}/`)) ||
+    /[?#]/.test(result.pathname)
+  ) {
+    throw new TypeError('Page rewrite must target its configured reservedPrefix');
+  }
+  return { pathname: result.pathname };
+}
+
+async function runPageLoader(route, params, outDir, componentCache, cacheVersion, ctx) {
+  const bundlePath = path.join(outDir, route.serverBundle);
+  const pageModule = await loadPageModule(
+    bundlePath,
+    `page-module:${route.pattern}`,
+    componentCache,
+    cacheVersion,
+  );
+  if (pageModule.loader === undefined) return null;
+  if (typeof pageModule.loader !== 'function') {
+    throw new TypeError(`Page loader for ${route.pattern} must be a function`);
+  }
+  const result = await pageModule.loader(ctx);
+  if (result == null) return { props: {} };
+  if (typeof result !== 'object' || Array.isArray(result)) {
+    throw new TypeError(`Page loader for ${route.pattern} must return an object`);
+  }
+  if (result.redirect !== undefined) {
+    if (typeof result.redirect !== 'string' || !result.redirect) {
+      throw new TypeError('Page loader redirect must be a non-empty string');
     }
-    const result = await middlewareFn(ctx);
-    if (result) {
-      return result;
+    if (
+      result.status !== undefined &&
+      (!Number.isInteger(result.status) || result.status < 300 || result.status > 399)
+    ) {
+      throw new TypeError('Page loader redirect status must be an integer from 300 to 399');
     }
+    validateLoaderHeaders(result.headers);
+    return result;
   }
-  return null;
+  if (result.notFound === true) return result;
+  assertJsonSerializable(result.props ?? {}, 'loader props');
+  if (result.metadata !== undefined) {
+    assertJsonSerializable(result.metadata, 'loader metadata');
+  }
+  if (
+    result.status !== undefined &&
+    (!Number.isInteger(result.status) || result.status < 200 || result.status > 599)
+  ) {
+    throw new TypeError('Page loader status must be an integer from 200 to 599');
+  }
+  validateLoaderHeaders(result.headers);
+  return result;
 }
-function buildClientManifestJson(manifest, { rootDir, viteDev } = {}) {
+
+function validateLoaderHeaders(headers) {
+  if (headers === undefined) return;
+  if (!headers || typeof headers !== 'object' || Array.isArray(headers)) {
+    throw new TypeError('Page loader headers must be an object');
+  }
+  const forbidden = new Set([
+    'connection',
+    'content-length',
+    'keep-alive',
+    'proxy-authenticate',
+    'proxy-authorization',
+    'set-cookie',
+    'te',
+    'trailer',
+    'transfer-encoding',
+    'upgrade',
+  ]);
+  for (const [name, value] of Object.entries(headers)) {
+    if (forbidden.has(name.toLowerCase())) {
+      throw new TypeError(`Page loader may not set the ${name} header`);
+    }
+    if (typeof value !== 'string' && typeof value !== 'number') {
+      throw new TypeError('Page loader header values must be strings or numbers');
+    }
+  }
+}
+
+function assertJsonSerializable(value, label, seen = new Set()) {
+  if (value === null || typeof value === 'string' || typeof value === 'boolean') return;
+  if (typeof value === 'number' && Number.isFinite(value)) return;
+  if (typeof value !== 'object') {
+    throw new TypeError(`${label} must contain only JSON-serializable values`);
+  }
+  if (
+    seen.has(value) ||
+    (!Array.isArray(value) && Object.getPrototypeOf(value) !== Object.prototype)
+  ) {
+    throw new TypeError(`${label} must contain only JSON-serializable values`);
+  }
+  seen.add(value);
+  for (const entry of Array.isArray(value) ? value : Object.values(value)) {
+    assertJsonSerializable(entry, label, seen);
+  }
+  seen.delete(value);
+}
+function buildClientManifestJson(manifest, { rootDir, viteDev, reservedPrefix } = {}) {
+  const clientVisibleManifest = reservedPrefix
+    ? {
+        ...manifest,
+        entries: manifest.entries.filter(
+          (entry) =>
+            entry.pattern !== reservedPrefix && !entry.pattern.startsWith(`${reservedPrefix}/`),
+        ),
+      }
+    : manifest;
   if (viteDev) {
-    return buildViteClientManifestJson(manifest, rootDir);
+    return buildViteClientManifestJson(clientVisibleManifest, rootDir);
   }
   const clientManifest = {
-    cssBundle: manifest.cssBundle ? `/static/${manifest.cssBundle}` : null,
-    routes: manifest.entries.map((entry) => {
+    cssBundle: clientVisibleManifest.cssBundle
+      ? `/static/${clientVisibleManifest.cssBundle}`
+      : null,
+    routes: clientVisibleManifest.entries.map((entry) => {
       const route = {
         pattern: entry.pattern,
         paramNames: entry.paramNames,
+        ...(entry.hasLoader ? { hasLoader: true } : {}),
         clientBundle: `/static/${entry.navBundle}`,
         layoutBundles: (entry.layoutClientBundles ?? []).map((b) => `/static/${b}`),
         loadingBundles: (entry.loadingClientBundles ?? []).map((b) => `/static/${b}`),

package/server/pages/pages-router.js

@@ -55,6 +55,7 @@ class PagesRouter {
       ...(isDev ? { outDir } : { resolveOutDir }),
       session: config.session,
       appContext: this.appContext,
+      rewrite: config.pages?.rewrite,
       mode,
       viteDev,
       ...(this.lazyContext ? { lazyContext: this.lazyContext } : {}),

package/server/pages/server-loader-transform.js

@@ -0,0 +1,191 @@
+import path from 'node:path';
+import fs from 'node:fs/promises';
+import { parseAsync, transformAsync } from '@babel/core';
+
+function exportedName(specifier) {
+  if (specifier?.exported?.type === 'Identifier') return specifier.exported.name;
+  if (specifier?.exported?.type === 'StringLiteral') return specifier.exported.value;
+  return null;
+}
+
+async function hasServerLoaderExport(code, filename) {
+  if (!code.includes('loader') && !/\bexport\s*\*/.test(code)) return false;
+  const ast = await parseAsync(code, {
+    filename,
+    babelrc: false,
+    configFile: false,
+    parserOpts: { plugins: ['jsx', 'typescript'] },
+  });
+  return ast.program.body.some((node) => {
+    // A star re-export can acquire a loader through any depth of barrel module.
+    // Treat it conservatively so client navigation can never bypass a loader
+    // that is only visible after module resolution.
+    if (node.type === 'ExportAllDeclaration') return true;
+    if (node.type !== 'ExportNamedDeclaration') return false;
+    if (node.declaration?.type === 'FunctionDeclaration') {
+      return node.declaration.id?.name === 'loader';
+    }
+    if (node.declaration?.type === 'VariableDeclaration') {
+      return node.declaration.declarations.some(
+        (item) => item.id.type === 'Identifier' && item.id.name === 'loader',
+      );
+    }
+    return node.specifiers.some((specifier) => exportedName(specifier) === 'loader');
+  });
+}
+
+function rememberDependencies(targetPath, state) {
+  const dependencies = state.file.get('arcwayLoaderDependencies') ?? new Set();
+  targetPath.traverse({
+    ReferencedIdentifier(identifierPath) {
+      const binding = identifierPath.scope.getBinding(identifierPath.node.name);
+      if (binding?.scope.path.isProgram()) dependencies.add(identifierPath.node.name);
+    },
+  });
+  state.file.set('arcwayLoaderDependencies', dependencies);
+}
+
+function removeBinding(binding, state) {
+  if (!binding) return;
+  const bindingPath = binding.path;
+  rememberDependencies(bindingPath, state);
+  if (bindingPath.isFunctionDeclaration() || bindingPath.isClassDeclaration()) {
+    bindingPath.remove();
+    return;
+  }
+  if (bindingPath.isVariableDeclarator()) {
+    const declarationPath = bindingPath.parentPath;
+    bindingPath.remove();
+    if (declarationPath.node?.declarations.length === 0) declarationPath.remove();
+  }
+}
+
+function stripLoaderExportPlugin() {
+  return {
+    visitor: {
+      ExportAllDeclaration(exportPath) {
+        // Page named exports have no browser runtime contract. Removing a star
+        // export is the only safe client transform because its export names can
+        // change through transitive barrels without changing this page file.
+        exportPath.remove();
+      },
+      ExportNamedDeclaration(exportPath, state) {
+        const declaration = exportPath.node.declaration;
+        if (declaration?.type === 'FunctionDeclaration' && declaration.id?.name === 'loader') {
+          rememberDependencies(exportPath.get('declaration'), state);
+          exportPath.remove();
+          return;
+        }
+        if (declaration?.type === 'VariableDeclaration') {
+          for (const declaratorPath of exportPath.get('declaration.declarations')) {
+            if (
+              declaratorPath.node.id.type === 'Identifier' &&
+              declaratorPath.node.id.name === 'loader'
+            ) {
+              rememberDependencies(declaratorPath, state);
+            }
+          }
+          declaration.declarations = declaration.declarations.filter(
+            (item) => item.id.type !== 'Identifier' || item.id.name !== 'loader',
+          );
+          if (declaration.declarations.length === 0) exportPath.remove();
+          return;
+        }
+        exportPath.node.specifiers = exportPath.node.specifiers.filter((specifier) => {
+          if (exportedName(specifier) !== 'loader') return true;
+          if (!exportPath.node.source && specifier.local?.name) {
+            const names = state.file.get('arcwayLoaderBindings') ?? [];
+            names.push(specifier.local.name);
+            state.file.set('arcwayLoaderBindings', names);
+          }
+          return false;
+        });
+        if (exportPath.node.specifiers.length === 0 && !declaration) exportPath.remove();
+      },
+      Program: {
+        exit(programPath, state) {
+          for (const name of state.file.get('arcwayLoaderBindings') ?? []) {
+            const binding = programPath.scope.getBinding(name);
+            removeBinding(binding, state);
+          }
+
+          const pending = state.file.get('arcwayLoaderDependencies') ?? new Set();
+          const inspected = new Set();
+          while (pending.size > 0) {
+            programPath.scope.crawl();
+            const name = pending.values().next().value;
+            pending.delete(name);
+            if (inspected.has(name)) continue;
+            inspected.add(name);
+            const binding = programPath.scope.getBinding(name);
+            if (binding && !binding.referenced) removeBinding(binding, state);
+          }
+
+          programPath.scope.crawl();
+          for (const importPath of programPath.get('body')) {
+            if (!importPath.isImportDeclaration()) continue;
+            const hadSpecifiers = importPath.node.specifiers.length > 0;
+            for (const specifierPath of importPath.get('specifiers')) {
+              const binding = programPath.scope.getBinding(specifierPath.node.local.name);
+              if (!binding?.referenced) specifierPath.remove();
+            }
+            if (hadSpecifiers && importPath.node.specifiers.length === 0) importPath.remove();
+          }
+        },
+      },
+    },
+  };
+}
+
+async function stripServerLoaderExport(code, filename) {
+  if (!code.includes('loader') && !/\bexport\s*\*/.test(code)) return code;
+  const result = await transformAsync(code, {
+    filename,
+    babelrc: false,
+    configFile: false,
+    sourceMaps: false,
+    parserOpts: {
+      plugins: ['jsx', 'typescript'],
+    },
+    plugins: [stripLoaderExportPlugin],
+  });
+  return result?.code ?? code;
+}
+
+function serverLoaderClientPlugin(pagePaths) {
+  const pages = new Set(pagePaths.map((filePath) => path.resolve(filePath)));
+  return {
+    name: 'arcway-server-page-loader',
+    setup(build) {
+      build.onLoad({ filter: /\.[cm]?[jt]sx?$/ }, async (args) => {
+        if (!pages.has(path.resolve(args.path))) return null;
+        const source = await fs.readFile(args.path, 'utf8');
+        const contents = await stripServerLoaderExport(source, args.path);
+        const extension = path.extname(args.path).toLowerCase();
+        const loader = extension === '.ts' ? 'ts' : extension === '.tsx' ? 'tsx' : 'jsx';
+        return { contents, loader };
+      });
+    },
+  };
+}
+
+function serverLoaderVitePlugin(pagesRoot) {
+  const pagesDir = `${path.resolve(pagesRoot)}${path.sep}`;
+  return {
+    name: 'arcway-server-page-loader',
+    enforce: 'pre',
+    async transform(code, id) {
+      const filename = id.split('?')[0];
+      if (!filename.startsWith(pagesDir) || !/\.[cm]?[jt]sx?$/.test(filename)) return null;
+      const transformed = await stripServerLoaderExport(code, filename);
+      return transformed === code ? null : { code: transformed, map: null };
+    },
+  };
+}
+
+export {
+  hasServerLoaderExport,
+  serverLoaderClientPlugin,
+  serverLoaderVitePlugin,
+  stripServerLoaderExport,
+};

package/server/pages/ssr.js

@@ -56,6 +56,16 @@ async function loadComponent(bundlePath, cacheKey, componentCache, cacheVersion)
     return null;
   }
 }
+async function loadPageModule(bundlePath, cacheKey, componentCache, cacheVersion) {
+  if (componentCache.has(cacheKey)) {
+    return componentCache.get(cacheKey);
+  }
+  const fileUrl = pathToFileURL(bundlePath).href;
+  const specifier = cacheVersion > 0 ? `${fileUrl}?v=${cacheVersion}` : fileUrl;
+  const mod = await import(specifier);
+  componentCache.set(cacheKey, mod);
+  return mod;
+}
 const ROUTER_CTX_KEY = '__router_context__';
 const PROVIDER_CTX_KEY = '__provider_context__';
 function wrapWithProviders(createElement, element, pathname, params) {
@@ -153,15 +163,22 @@ async function renderPage(
   devMode,
   viteDev = false,
   onRenderFailure = null,
+  pageProps = params,
+  response = {},
 ) {
   const { createElement, renderToPipeableStream } = react;
   const bundlePath = path.join(outDir, route.serverBundle);
-  const Component = await loadComponent(
-    bundlePath,
-    `page:${route.pattern}`,
-    componentCache,
-    cacheVersion,
-  );
+  const legacyCachedComponent = componentCache.get(`page:${route.pattern}`);
+  const Component = legacyCachedComponent
+    ? legacyCachedComponent
+    : (
+        await loadPageModule(
+          bundlePath,
+          `page-module:${route.pattern}`,
+          componentCache,
+          cacheVersion,
+        )
+      ).default;
   if (!Component || typeof Component !== 'function') {
     res.writeHead(500, getHtmlHeaders());
     res.end('<h1>500 - Page component is not a valid React component</h1>');
@@ -188,12 +205,13 @@ async function renderPage(
   const envScriptTag = buildEnvScriptTag(collectPublicEnv());
   const hmrTag = devMode && !viteDev ? buildHmrScript() : '';
   const liveReloadTag = devMode && !viteDev && !hmrTag ? buildLiveReloadScript() : '';
-  const propsJson = JSON.stringify(params).replace(/</g, '\\u003c');
+  const propsJson = JSON.stringify(pageProps).replace(/</g, '\\u003c');
+  const routeParamsJson = JSON.stringify(params).replace(/</g, '\\u003c');
   const headData = { meta: [], links: [] };
   setSSRHeadData(headData);
-  let element = createElement(Component, params);
+  let element = createElement(Component, pageProps);
   for (let i = layoutComponents.length - 1; i >= 0; i--) {
-    element = createElement(layoutComponents[i], null, element);
+    element = createElement(layoutComponents[i], pageProps, element);
   }
   element = wrapWithProviders(createElement, element, pathname, params);
   const { PassThrough } = await import('node:stream');
@@ -209,7 +227,10 @@ async function renderPage(
       // React may call onAllReady after onShellError but before the recovery
       // promise starts. Never let the failed stream win that race and commit 200.
       if (res.headersSent || closed || renderFailureHandled) return;
-      res.writeHead(200, getHtmlHeaders());
+      res.writeHead(response.status ?? 200, {
+        ...getHtmlHeaders(),
+        ...response.headers,
+      });
       const headHtml = renderHeadToString(headData);
       const shell = buildHtmlShell({
         headHtml,
@@ -217,6 +238,7 @@ async function renderPage(
         cssLinkTag,
         bodysuffix: `${envScriptTag}
 <script id="__app_props" type="application/json">${propsJson}</script>
+<script id="__app_route_params" type="application/json">${routeParamsJson}</script>
 <script id="__app_manifest" type="application/json">${clientManifestJson}</script>
 ${hmrTag}
 ${scriptTags}
@@ -372,6 +394,7 @@ export {
   buildRouteCssLinkTags,
   buildScriptTags,
   loadComponent,
+  loadPageModule,
   renderErrorPage,
   renderPage,
   syncReactInternals,

package/server/pages/vite-dev.js

@@ -6,6 +6,7 @@ import tailwindcss from '@tailwindcss/vite';
 import { createServer as createViteServer } from 'vite';
 import { patternToFileName } from './build-server.js';
 import { closeServer, createHttpServer, listen } from '../server.js';
+import { serverLoaderVitePlugin } from './server-loader-transform.js';
 
 function toPosixPath(value) {
   return value.replace(/\\/g, '/');
@@ -72,9 +73,11 @@ function buildViteHydrationEntry({
 const container = document.getElementById('__app');
 const propsEl = document.getElementById('__app_props');
 const props = propsEl ? JSON.parse(propsEl.textContent || '{}') : {};
+const routeParamsEl = document.getElementById('__app_route_params');
+const routeParams = routeParamsEl ? JSON.parse(routeParamsEl.textContent || '{}') : props;
 const ROOT_KEY = '__arcway_root__';
 const rootOwner = window;
-const element = <ApiProvider><Router initialPath={window.location.pathname} initialParams={props} initialPattern={${JSON.stringify(pattern)}} initialComponent={Component} initialLayouts={${layoutsArray}} initialLoadings={${loadingsArray}} /></ApiProvider>;
+const element = <ApiProvider><Router initialPath={window.location.pathname} initialParams={routeParams} initialPageProps={props} initialPattern={${JSON.stringify(pattern)}} initialComponent={Component} initialLayouts={${layoutsArray}} initialLoadings={${loadingsArray}} /></ApiProvider>;
 
 if (!container) {
   throw new Error('Arcway Vite hydrate entry could not find #__app');
@@ -153,6 +156,7 @@ function buildViteClientManifestJson(manifest, rootDir) {
       const route = {
         pattern: entry.pattern,
         paramNames: entry.paramNames,
+        ...(entry.hasLoader ? { hasLoader: true } : {}),
         clientBundle: toViteModuleUrl(rootDir, entry.srcPath),
         layoutBundles: entry.layoutDirs
           .map((dirPath) => manifest.layouts.get(dirPath)?.srcPath)
@@ -187,14 +191,26 @@ function resolveAppAliases(rootDir) {
   try {
     const reactRoot = path.dirname(appRequire.resolve('react/package.json'));
     aliases.push({ find: /^react$/, replacement: toPosixPath(path.join(reactRoot, 'index.js')) });
-    aliases.push({ find: /^react\/jsx-runtime$/, replacement: toPosixPath(path.join(reactRoot, 'jsx-runtime.js')) });
-    aliases.push({ find: /^react\/jsx-dev-runtime$/, replacement: toPosixPath(path.join(reactRoot, 'jsx-dev-runtime.js')) });
+    aliases.push({
+      find: /^react\/jsx-runtime$/,
+      replacement: toPosixPath(path.join(reactRoot, 'jsx-runtime.js')),
+    });
+    aliases.push({
+      find: /^react\/jsx-dev-runtime$/,
+      replacement: toPosixPath(path.join(reactRoot, 'jsx-dev-runtime.js')),
+    });
   } catch {}
 
   try {
     const reactDomRoot = path.dirname(appRequire.resolve('react-dom/package.json'));
-    aliases.push({ find: /^react-dom$/, replacement: toPosixPath(path.join(reactDomRoot, 'index.js')) });
-    aliases.push({ find: /^react-dom\/client$/, replacement: toPosixPath(path.join(reactDomRoot, 'client.js')) });
+    aliases.push({
+      find: /^react-dom$/,
+      replacement: toPosixPath(path.join(reactDomRoot, 'index.js')),
+    });
+    aliases.push({
+      find: /^react-dom\/client$/,
+      replacement: toPosixPath(path.join(reactDomRoot, 'client.js')),
+    });
   } catch {}
 
   try {
@@ -251,7 +267,11 @@ async function createViteDevRouter({ rootDir, log, config }) {
           '@radix-ui/react-use-is-hydrated',
         ],
       },
-      plugins: [reactPlugin(), tailwindcss()],
+      plugins: [
+        serverLoaderVitePlugin(config?.pages?.dir ?? path.resolve(rootDir, 'pages')),
+        reactPlugin(),
+        tailwindcss(),
+      ],
       clearScreen: false,
     });
   } catch (error) {