@reckona/mreact-router 0.0.202 → 0.0.203

package/src/actions.ts

@@ -9,6 +9,7 @@ import {
 import {
   createServerActionHandler,
   type ServerActionHandlerOptions,
+  type ServerActionReplayClaim,
   type ServerActionRegistry,
   type ServerActionReplayStore,
   type ServerActionRequestReference,
@@ -112,42 +113,44 @@ function configuredActionTokenSecret(value: string | undefined): string {
 }
 
 class BoundedReplayStore {
-  private readonly entries = new Map<string, number>();
+  private readonly entries = new Map<
+    string,
+    { state: "in-flight" } | { state: "completed"; expiresAt: number }
+  >();
 
   constructor(
     private readonly ttlMs: number,
     private readonly maxEntries: number,
   ) {}
 
-  has(value: string): boolean {
-    const expiresAt = this.entries.get(value);
-    if (expiresAt === undefined) return false;
-    if (expiresAt < Date.now()) {
+  claim(value: string): ServerActionReplayClaim {
+    const existing = this.entries.get(value);
+    if (existing?.state === "completed" && existing.expiresAt < Date.now()) {
       this.entries.delete(value);
-      return false;
     }
-    return true;
-  }
 
-  add(value: string): void {
-    const now = Date.now();
+    if (this.entries.has(value)) return { status: "replay" };
     if (this.entries.size >= this.maxEntries) {
-      const oldest = this.entries.entries().next().value;
-      if (oldest !== undefined) {
-        const [key, expiresAt] = oldest;
-        this.entries.delete(key);
-        if (expiresAt < now) {
-          while (this.entries.size >= this.maxEntries) {
-            const nextOldest = this.entries.entries().next().value;
-            if (nextOldest === undefined || nextOldest[1] >= now) {
-              break;
-            }
-            this.entries.delete(nextOldest[0]);
-          }
-        }
+      const now = Date.now();
+      for (const [key, entry] of this.entries) {
+        if (entry.state === "completed" && entry.expiresAt < now) this.entries.delete(key);
       }
+      if (this.entries.size >= this.maxEntries) return { status: "capacity-exceeded" };
     }
-    this.entries.set(value, now + this.ttlMs);
+
+    const entry = { state: "in-flight" as const };
+    this.entries.set(value, entry);
+    let finalized = false;
+    return {
+      status: "claimed",
+      finalize: () => {
+        if (finalized) return;
+        finalized = true;
+        if (this.entries.get(value) === entry) {
+          this.entries.set(value, { state: "completed", expiresAt: Date.now() + this.ttlMs });
+        }
+      },
+    };
   }
 
   // Exposed for tests; not part of the ServerActionReplayStore interface.
@@ -456,7 +459,7 @@ async function dispatchServerActionRequestWithoutCacheContext(options: {
         : { allowedActions: jsonAllowedServerActions(options.serverActions.allowedActions) }),
       csrf: { cookieName: serverActionCookieName() },
       maxBodyBytes: options.serverActions?.maxBodyBytes ?? DEFAULT_ACTION_BODY_MAX_BYTES,
-      replayProtection: { seen: replayStore },
+      replayProtection: { store: replayStore },
     });
 
     return handle(options.request);
@@ -528,15 +531,6 @@ async function dispatchServerActionRequestWithoutCacheContext(options: {
     return jsonResponse({ ok: false, error: "Unknown server action." }, 404);
   }
 
-  const nonceResponse = validateFormNonce(
-    formData,
-    options.serverActions?.replayStore ?? usedFormActionNonces,
-  );
-
-  if (nonceResponse !== undefined) {
-    return nonceResponse;
-  }
-
   let registry: ServerActionRegistry;
   try {
     registry = await loadServerActionRegistry({
@@ -570,24 +564,40 @@ async function dispatchServerActionRequestWithoutCacheContext(options: {
     return authorizationResponse;
   }
 
+  const replayClaim = await claimFormNonce(
+    nonce,
+    options.serverActions?.replayStore ?? usedFormActionNonces,
+  );
+  if (replayClaim instanceof Response) return replayClaim;
+
+  let actionResponse: Response | undefined;
+  let actionError: unknown;
   try {
     const value = await action(actionFormData, createServerActionContext(options.request));
 
     if (value instanceof Response) {
-      return value;
+      actionResponse = value;
+    } else if (value === undefined || value === null) {
+      actionResponse = redirectToFormReferer(options.request);
+    } else {
+      actionResponse = jsonResponse({ ok: true, value }, 200);
     }
-
-    if (value === undefined || value === null) {
-      return redirectToFormReferer(options.request);
-    }
-
-    return jsonResponse({ ok: true, value }, 200);
   } catch (error) {
-    return jsonResponse(
-      { ok: false, error: error instanceof Error ? error.message : String(error) },
-      500,
-    );
+    actionError = error;
+  }
+
+  try {
+    await replayClaim.finalize();
+  } catch {
+    return replayStoreUnavailableResponse();
   }
+
+  return actionError === undefined
+    ? actionResponse!
+    : jsonResponse(
+        { ok: false, error: actionError instanceof Error ? actionError.message : String(actionError) },
+        500,
+      );
 }
 
 function createServerActionContext(request: Request): ServerActionContext {
@@ -1482,22 +1492,28 @@ function validateServerActionRequestOrigin(request: Request): Response | undefin
   }
 }
 
-function validateFormNonce(
-  formData: FormData,
+async function claimFormNonce(
+  nonce: string,
   replayStore: ServerActionReplayStore,
-): Response | undefined {
-  const nonce = stringFormValue(formData.get(formFieldNonce));
-
-  if (nonce === undefined || nonce.length === 0) {
-    return jsonResponse({ ok: false, error: "Missing server action nonce." }, 400);
+): Promise<Extract<Awaited<ReturnType<ServerActionReplayStore["claim"]>>, { status: "claimed" }> | Response> {
+  let claim: Awaited<ReturnType<ServerActionReplayStore["claim"]>>;
+  try {
+    claim = await replayStore.claim(nonce);
+  } catch {
+    return replayStoreUnavailableResponse();
   }
-
-  if (replayStore.has(nonce)) {
+  if (claim.status === "replay") {
     return jsonResponse({ ok: false, error: "Server action nonce was already used." }, 409);
   }
+  if (claim.status === "capacity-exceeded") return replayStoreUnavailableResponse();
+  return claim;
+}
 
-  replayStore.add(nonce);
-  return undefined;
+function replayStoreUnavailableResponse(): Response {
+  return new Response(
+    JSON.stringify({ ok: false, error: "Server action replay protection is unavailable." }),
+    { status: 503, headers: { "content-type": "application/json", "retry-after": "1" } },
+  );
 }
 
 function cleanActionFormData(formData: FormData): FormData {

package/src/adapters/cloudflare.ts

@@ -10,6 +10,7 @@ import {
   isQueryClientScopeUnavailableError,
   runWithQueryClient,
   type DehydratedQueryClient,
+  type DehydrateOptions,
   type QueryAsyncStorage,
   type QueryClient,
 } from "@reckona/mreact-query";
@@ -38,7 +39,8 @@ import { routeSecurityHeaders } from "../security-headers.js";
 import type { AppRouterPrerenderStore } from "../serve.js";
 import { emitRouterDevtoolsEvent } from "./devtools.js";
 import { escapeHtmlAttribute, escapeHtmlText } from "@reckona/mreact-shared/html-escape";
-import { isCurrentPrerenderedRoute } from "../prerender-entry.js";
+import { isCurrentPrerenderedRoute, replayedPrerenderedRouteHeaders } from "../prerender-entry.js";
+import { hasNavigationRouteMarker } from "../navigation-marker.js";
 
 /** Re-exports build manifest contracts used by Cloudflare handlers. */
 export type {
@@ -291,6 +293,7 @@ export type CloudflareRouteModuleRegistry<Env = unknown> = Record<
  * Configures the Cloudflare route module renderer.
  */
 export interface CloudflareRouteModuleRendererOptions<Env = unknown> {
+  dehydrateOptions?: DehydrateOptions | undefined;
   document?:
     | ((
         context: CloudflareRouteModuleComponentProps<unknown, Env> & {
@@ -496,7 +499,7 @@ export function createCloudflareRouteModuleRenderer<Env = unknown>(
     const prerendered = prerenderedResponse(
       context.serverManifest.prerenderedRoutes,
       normalizeRoutePath(new URL(request.url).pathname),
-      request.method,
+      request,
       isCloudflareNavigationRequest(request),
     );
 
@@ -599,6 +602,16 @@ export function createCloudflareRouteModuleRenderer<Env = unknown>(
     );
 
     if (rendered instanceof Response) {
+      if (
+        (
+          pageModule as CloudflareRouteModule<unknown, Env> & {
+            __mreactSecurityHeadersApplied?: boolean | undefined;
+          }
+        ).__mreactSecurityHeadersApplied === true
+      ) {
+        return rendered;
+      }
+
       return withDefaultSecurityHeaders(rendered, request, metadata);
     }
 
@@ -623,7 +636,7 @@ export function createCloudflareRouteModuleRenderer<Env = unknown>(
           );
     const documentedWithQueryState = await injectCloudflareQueryState(
       documented,
-      dehydrate(queryClient),
+      dehydrate(queryClient, options.dehydrateOptions),
     );
 
     return withDefaultSecurityHeaders(
@@ -722,6 +735,9 @@ async function runWithCloudflareQueryClient<T>(
     if (isQueryClientScopeUnavailableError(error)) {
       installQueryAsyncStorage(cloudflareQueryClientStorage);
       cloudflareQueryClientFallbackInstalled = true;
+      console.warn(
+        '[mreact] Cloudflare AsyncLocalStorage is unavailable. Enable the "nodejs_compat" compatibility flag; rendering is serialized until native request-local storage is available.',
+      );
       return await runWithSerializedCloudflareQueryClient(queryClient, fn);
     }
 
@@ -733,6 +749,11 @@ const cloudflareQueryClientStorage = createCloudflareQueryClientStorage();
 let cloudflareQueryClientFallbackQueue: Promise<void> = Promise.resolve();
 let cloudflareQueryClientFallbackInstalled = false;
 
+export function __resetCloudflareQueryClientFallbackForTesting(): void {
+  cloudflareQueryClientFallbackQueue = Promise.resolve();
+  cloudflareQueryClientFallbackInstalled = false;
+}
+
 async function runWithSerializedCloudflareQueryClient<T>(
   queryClient: QueryClient,
   fn: () => T,
@@ -1234,7 +1255,7 @@ async function handleCloudflareRequest<Env>(
     : prerenderedResponse(
         options.serverManifest.prerenderedRoutes,
         normalizeRoutePath(url.pathname),
-        request.method,
+        request,
         isCloudflareNavigationRequest(request),
       );
 
@@ -1377,25 +1398,34 @@ function builtServerManifestHasMiddleware(manifest: {
 function prerenderedResponse(
   prerenderedRoutes: Record<string, BuiltPrerenderedRoute> | undefined,
   path: string,
-  method: string,
+  request: Request,
   isNavigation: boolean,
 ): Response | undefined {
-  if (method !== "GET" && method !== "HEAD") {
+  if (request.method !== "GET" && request.method !== "HEAD") {
     return undefined;
   }
 
   const prerendered = prerenderedRoutes?.[path];
+  const candidateNavigationHtml = prerendered?.navigationHtml;
 
   if (!isCurrentPrerenderedRoute(prerendered)) {
+    if (
+      isNavigation &&
+      typeof candidateNavigationHtml === "string" &&
+      !hasNavigationRouteMarker(candidateNavigationHtml)
+    ) {
+      return cloudflareDocumentReloadNavigationResponse();
+    }
     return undefined;
   }
 
-  if (isNavigation && !prerendered.html.includes("data-mreact-route-id")) {
+  const html = isNavigation ? prerendered.navigationHtml : prerendered.html;
+  if (html === undefined) {
     return cloudflareDocumentReloadNavigationResponse();
   }
 
-  return new Response(method === "HEAD" ? null : prerendered.html, {
-    headers: prerendered.headers,
+  return new Response(request.method === "HEAD" ? null : html, {
+    headers: replayedPrerenderedRouteHeaders(prerendered, request),
     status: prerendered.status,
   });
 }
@@ -1622,7 +1652,7 @@ function cloudflareHydrationMarkerParts(options: {
   const propsJson = escapeScriptJson(
     JSON.stringify({
       params: options.params,
-      request: { url: options.request.url },
+      request: { url: new URL(options.request.url).pathname },
       data: options.data,
     }),
   );

package/src/build.ts

@@ -46,6 +46,7 @@ import {
   buildNavigationRuntimeBundle,
   clientScriptForPath,
   routeIdForPath,
+  routeMarkerParts,
   type BuildClientRouteOutputOptions,
 } from "./navigation-runtime.js";
 import {
@@ -72,6 +73,7 @@ import type { RouteCachePolicy } from "./cache.js";
 import { routeCachePolicyFromSource } from "./cache.js";
 import {
   bundleMiddlewareModuleCode,
+  prerenderVariantMarkerParts,
   renderAppRequest,
   type RenderAppRequestRuntimeOptions,
 } from "./render.js";
@@ -105,6 +107,7 @@ import { collectBuildInferredServerActions } from "./server-action-inference.js"
 import {
   isVisitorDependentResponse,
   PRERENDERED_ROUTE_SCHEMA_VERSION,
+  storedPrerenderedRouteHeaders,
 } from "./prerender-entry.js";
 import { prepareRouteServerActionPlaceholders } from "./actions.js";
 import { viteDefineCacheKey, vitePluginsCacheKey } from "./vite-plugin-cache-key.js";
@@ -423,9 +426,11 @@ export interface BuiltServerModuleOutput {
 export interface BuiltPrerenderedRoute {
   headers: Record<string, string>;
   html: string;
+  navigationHtml?: string | undefined;
   /** Identifies entries that satisfy the complete current prerender contract. */
-  schemaVersion?: 2 | undefined;
+  schemaVersion?: 4 | undefined;
   status: number;
+  strictTransportSecurity?: string | undefined;
 }
 
 type StaticParams = Record<string, string | number | boolean | readonly string[]>;
@@ -2620,6 +2625,7 @@ async function prerenderStaticRoutes(options: {
       for (const pathname of await prerenderPathsForRoute(route, analysis, options.vitePlugins)) {
         const renderSignals = {
           headerDependent: () => true,
+          strictTransportSecurity: () => undefined as string | undefined,
         };
         const renderOptions = {
           appDir: options.appDir,
@@ -2629,31 +2635,52 @@ async function prerenderStaticRoutes(options: {
           define: options.define,
           importPolicy,
           navigationScripts,
-          request: new Request(`http://mreact.local${pathname}`),
+          request: new Request(
+            `http://mreact.local${pathname}`,
+            analysis.clientRoute
+              ? undefined
+              : { headers: { "x-mreact-prerender-variant-capture": "1" } },
+          ),
           renderSignals,
           serverModuleCacheVersion,
           serverModules: serverModuleMap,
           vitePlugins: options.vitePlugins,
         } satisfies RenderAppRequestRuntimeOptions;
         const response = await renderAppRequest(renderOptions);
-        const html = await response.text();
+        const renderedHtml = await response.text();
 
         if (renderSignals.headerDependent() || isVisitorDependentResponse(response)) {
           continue;
         }
 
-        const headers: Record<string, string> = {};
+        let html = renderedHtml;
+        let navigationHtml = renderedHtml;
+        if (!analysis.clientRoute) {
+          const capture = prerenderVariantMarkerParts(route.path);
+          const start = renderedHtml.indexOf(capture.prefix);
+          const end = renderedHtml.lastIndexOf(capture.suffix);
+          if (start === -1 || end < start + capture.prefix.length) {
+            throw new Error(`Failed to capture prerender response variants for ${pathname}.`);
+          }
+          const before = renderedHtml.slice(0, start);
+          const content = renderedHtml.slice(start + capture.prefix.length, end);
+          const after = renderedHtml.slice(end + capture.suffix.length);
+          const navigationMarker = routeMarkerParts(route.path);
+          html = `${before}${content}${after}`;
+          navigationHtml = `${before}${navigationMarker.prefix}${content}${navigationMarker.suffix}${after}`;
+        }
 
-        response.headers.forEach((value, key) => {
-          headers[key] = value;
-        });
+        const headers = storedPrerenderedRouteHeaders(response.headers);
+        const strictTransportSecurity = renderSignals.strictTransportSecurity();
         entries.push([
           pathname,
           {
             headers,
             html,
+            navigationHtml,
             schemaVersion: PRERENDERED_ROUTE_SCHEMA_VERSION,
             status: response.status,
+            ...(strictTransportSecurity === undefined ? {} : { strictTransportSecurity }),
           },
         ]);
       }
@@ -3954,6 +3981,7 @@ function cloudflarePageRouteFacadeModuleSource(componentImport: string): string
 const componentSlots = readComponentModuleExport(componentModule, "slots");
 const componentGenerateMetadata = readComponentModuleExport(componentModule, "generateMetadata");
 const componentMetadata = readComponentModuleExport(componentModule, "metadata");
+const componentSecurityHeadersApplied = readComponentModuleExport(componentModule, "__mreactSecurityHeadersApplied");
 
 export function App(props) {
   return renderCloudflareRouteComponent(props);
@@ -3968,6 +3996,7 @@ export const slots = componentSlots === undefined ? undefined : { ...componentSl
 export const generateMetadata =
   typeof componentGenerateMetadata === "function" ? componentGenerateMetadata : undefined;
 export const metadata = componentMetadata;
+export const __mreactSecurityHeadersApplied = componentSecurityHeadersApplied === true;
 
 function renderCloudflareRouteComponent(props) {
   const routeComponent = resolveCloudflareRouteComponent();
@@ -4714,7 +4743,9 @@ ${cloudflareShellRuntimeSource()}`;
 }
 
 function cloudflareShellRuntimeSource(): string {
-  return `async function renderLayoutShells(shells, props, namedSlots) {
+  return `export const __mreactSecurityHeadersApplied = true;
+
+async function renderLayoutShells(shells, props, namedSlots) {
   const slotContext = { consumedSlots: new Set(), namedSlots };
   const rendered = [];
   for (const shell of shells) {
@@ -4793,7 +4824,7 @@ function cloudflareHydrationMarkerParts(props) {
   const escapedRouteId = escapeHtmlAttribute(routeId);
   const propsJson = escapeScriptJson(JSON.stringify({
     params: props.params,
-    request: { url: props.request.url },
+    request: { url: new URL(props.request.url).pathname },
     data: props.data,
   }));
   const clientReferencesJson = route.clientReferenceManifest === undefined || route.clientReferenceManifest.length === 0
@@ -5216,17 +5247,63 @@ function routeSecurityHeaders(security, request) {
   } else {
     headers["referrer-policy"] = validateHeaderValue(security?.referrerPolicy ?? "strict-origin-when-cross-origin");
   }
+  if (security?.permissionsPolicy === null) {
+    delete headers["permissions-policy"];
+  } else {
+    const permissionsPolicy = serializePermissionsPolicy(security?.permissionsPolicy);
+    if (permissionsPolicy === undefined) {
+      delete headers["permissions-policy"];
+    } else {
+      headers["permissions-policy"] = permissionsPolicy;
+    }
+  }
   if (security?.frameOptions === null) {
     delete headers["x-frame-options"];
   } else if (security?.frameOptions !== undefined) {
     headers["x-frame-options"] = validateHeaderValue(security.frameOptions);
   }
   if (request.url.startsWith("https://") && security?.hsts !== undefined && security.hsts !== false && security.hsts !== null) {
-    headers["strict-transport-security"] = \`max-age=\${Math.trunc(security.hsts.maxAge)}\${security.hsts.includeSubDomains === true ? "; includeSubDomains" : ""}\${security.hsts.preload === true ? "; preload" : ""}\`;
+    headers["strict-transport-security"] = serializeHsts(security.hsts);
   }
   return headers;
 }
 
+function serializeHsts(hsts) {
+  if (hsts === false) {
+    throw new TypeError("Invalid security header value for hsts.");
+  }
+  const maxAge = Math.trunc(hsts.maxAge);
+  if (!Number.isFinite(maxAge) || maxAge < 0) {
+    throw new TypeError("Invalid security header value for hsts.maxAge.");
+  }
+  const parts = [\`max-age=\${maxAge}\`];
+  if (hsts.includeSubDomains === true) {
+    parts.push("includeSubDomains");
+  }
+  if (hsts.preload === true) {
+    parts.push("preload");
+  }
+  return parts.join("; ");
+}
+
+function serializePermissionsPolicy(policy) {
+  if (policy === undefined) {
+    return "camera=(), microphone=(), geolocation=()";
+  }
+  const directives = [];
+  for (const [directive, allowlist] of Object.entries(policy)) {
+    if (allowlist === null || allowlist === undefined) {
+      continue;
+    }
+    validateToken(directive, "permissionsPolicy directive");
+    for (const value of allowlist) {
+      validatePermissionAllowlistValue(value);
+    }
+    directives.push(\`\${directive}=(\${allowlist.join(" ")})\`);
+  }
+  return directives.length === 0 ? undefined : directives.join(", ");
+}
+
 function validateHeaderValue(value) {
   for (let index = 0; index < value.length; index += 1) {
     const code = value.charCodeAt(index);
@@ -5237,6 +5314,22 @@ function validateHeaderValue(value) {
   return value;
 }
 
+function validateToken(value, label) {
+  if (!/^[A-Za-z][A-Za-z0-9-]*$/.test(value)) {
+    throw new TypeError(\`Invalid security header value for \${label}: \${JSON.stringify(value)}\`);
+  }
+}
+
+function validatePermissionAllowlistValue(value) {
+  if (value === "self" || value === "*" || /^[A-Za-z][A-Za-z0-9+.-]*:$/.test(value)) {
+    return;
+  }
+  if (/^https:\\/\\/[A-Za-z0-9.-]+(?::[0-9]+)?$/.test(value)) {
+    return;
+  }
+  throw new TypeError(\`Invalid security header value for permissionsPolicy allowlist: \${JSON.stringify(value)}\`);
+}
+
 function mergeRouteMetadata(metadata) {
   if (metadata.length === 0) {
     return undefined;
@@ -6216,6 +6309,10 @@ async function writeClientRouteBundles(options: {
             options.sourceAnalysis.byRouteFile.get(
               relative(options.projectRoot, route.file).split(sep).join("/"),
             )?.streamRoute === true,
+          restoreRequestUrl:
+            options.sourceAnalysis.byRouteFile.get(
+              relative(options.projectRoot, route.file).split(sep).join("/"),
+            )?.usesRequestInput === true,
           cacheDir: options.cacheDir,
           dropConsoleFunctions: options.clientConsolePureFunctions,
           filename: route.file,

package/src/cache.ts

@@ -650,10 +650,16 @@ export function activeRouteCacheContext(): RouteCacheContext | undefined {
 
 // Host is excluded from the cache key to prevent attacker-supplied Host
 // headers from fragmenting / poisoning the cache (Issue 068). The Vary
-// dimension is the request path + query; same-origin reverse proxies are
-// expected to handle vhost separation at their layer.
-export function routeCacheKey(appDir: string, routePath: string, url: URL): string {
-  return `${appDir}\0${normalizeRevalidationPath(routePath)}\0${url.pathname}${url.search}`;
+// dimensions are the request path + query and the document/navigation HTML
+// shape; same-origin reverse proxies are expected to handle vhost separation
+// at their layer.
+export function routeCacheKey(
+  appDir: string,
+  routePath: string,
+  url: URL,
+  responseVariant: "document" | "navigation" = "document",
+): string {
+  return `${appDir}\0${normalizeRevalidationPath(routePath)}\0${url.pathname}${url.search}\0${responseVariant}`;
 }
 
 export function stripRevalidateExport(code: string): string {

package/src/cli-options.ts

@@ -335,6 +335,7 @@ export function formatCliHelp(command?: string | undefined): string {
       "",
       "Options:",
       "  --host <host>  Bind address. Default: 127.0.0.1. Use 0.0.0.0 inside containers behind explicit port publishing or a reverse proxy.",
+      "  --port <port>  TCP port. Overrides PORT. Default: 3001.",
       "  --host-policy=strict|trusted-proxy",
       "      Control Host header trust for request origin reconstruction.",
       "  --allowed-hosts <host[,host...]>",
@@ -469,6 +470,18 @@ export function resolveCliDevPort(
   return envValue === undefined || envValue === "" ? viteConfigPort : parseCliPort(envValue);
 }
 
+export function resolveCliStartPort(
+  flagValue: number | undefined,
+  env: { PORT?: string | undefined },
+): number {
+  if (flagValue !== undefined) {
+    return flagValue;
+  }
+
+  const envValue = env.PORT;
+  return envValue === undefined || envValue === "" ? 3001 : parseCliPort(envValue, "PORT");
+}
+
 export function resolveCliHostPolicy(
   flagValue: RequestHostPolicy | undefined,
   env: { MREACT_ROUTER_HOST_POLICY?: string | undefined },
@@ -527,7 +540,7 @@ function parseCliRequestLogMode(value: string): CliRequestLogMode {
   throw new Error(`Unsupported log mode ${JSON.stringify(value)}. Expected "requests".`);
 }
 
-function parseCliPort(value: string): number {
+function parseCliPort(value: string, source = "port"): number {
   const port = Number(value);
 
   if (Number.isInteger(port) && port >= 0 && port <= 65535) {
@@ -535,7 +548,7 @@ function parseCliPort(value: string): number {
   }
 
   throw new Error(
-    `Unsupported port ${JSON.stringify(value)}. Expected an integer from 0 to 65535.`,
+    `Unsupported ${source} ${JSON.stringify(value)}. Expected an integer from 0 to 65535.`,
   );
 }
 

package/src/cli.ts

@@ -25,6 +25,7 @@ import {
   resolveCliHost,
   resolveCliHostPolicy,
   resolveCliRequestLogMode,
+  resolveCliStartPort,
   resolveCliTrustForwardedProto,
 } from "./cli-options.js";
 import { startDevServer } from "./dev-server.js";
@@ -169,7 +170,7 @@ if (parsed !== undefined) {
           hostname: resolveCliHost(parsed.host, process.env),
           logger,
           outDir: resolve(routeArg ?? ".mreact"),
-          port: Number(process.env.PORT ?? 3001),
+          port: resolveCliStartPort(parsed.port, process.env),
           trustForwardedProto: resolveCliTrustForwardedProto(
             parsed.trustForwardedProto,
             process.env,