handle preloading

Author: conico974

.changeset/warm-pans-argue.md

@@ -2,4 +2,7 @@
 "@opennextjs/aws": patch
 ---
 
-patch code to avoid useless import at runtime
+Some perf improvements : 
+- Eliminate unnecessary runtime imports.
+- Refactor route preloading to be either on-demand or using waitUntil or at the start or during warmerEvent.
+- Add a global function to preload routes when needed.

packages/open-next/src/core/createMainHandler.ts

@@ -26,6 +26,8 @@ export async function createMainHandler() {
   globalThis.serverId = generateUniqueId();
   globalThis.openNextConfig = config;
 
+  await globalThis.__next_route_preloader("start");
+
   // Default queue
   globalThis.queue = await resolveQueue(thisFunction.override?.queue);
 

packages/open-next/src/core/requestHandler.ts

@@ -47,6 +47,7 @@ export async function openNextHandler(
       waitUntil: options?.waitUntil,
     },
     async () => {
+      await globalThis.__next_route_preloader("waitUntil");
       if (initialHeaders["x-forwarded-host"]) {
         initialHeaders.host = initialHeaders["x-forwarded-host"];
       }

packages/open-next/src/core/util.ts

@@ -6,7 +6,7 @@ import {
 // @ts-ignore
 import NextServer from "next/dist/server/next-server.js";
 
-import { debug } from "../adapters/logger.js";
+import { debug, error } from "../adapters/logger.js";
 import {
   applyOverride as applyNextjsRequireHooksOverride,
   overrideHooks as overrideNextjsRequireHooks,
@@ -59,6 +59,51 @@ const nextServer = new NextServer.default({
   dir: __dirname,
 });
 
+let alreadyLoaded = false;
+
+globalThis.__next_route_preloader = async (stage) => {
+  if (alreadyLoaded) {
+    return;
+  }
+  const thisFunction = globalThis.fnName
+    ? globalThis.openNextConfig.functions![globalThis.fnName]
+    : globalThis.openNextConfig.default;
+  const routePreloadingBehavior =
+    thisFunction?.routePreloadingBehavior ?? "none";
+  if (routePreloadingBehavior === "none") {
+    alreadyLoaded = true;
+    return;
+  }
+  if (!("unstable_preloadEntries" in nextServer)) {
+    debug(
+      "The current version of Next.js does not support route preloading. Skipping route preloading.",
+    );
+    alreadyLoaded = true;
+    return;
+  }
+  if (stage === "waitUntil" && routePreloadingBehavior === "withWaitUntil") {
+    // We need to access the waitUntil
+    const waitUntil = globalThis.__openNextAls.getStore()?.waitUntil;
+    if (!waitUntil) {
+      error(
+        "You've tried to use the 'withWaitUntil' route preloading behavior, but the 'waitUntil' function is not available.",
+      );
+    }
+    debug("Preloading entries with waitUntil");
+    waitUntil?.(nextServer.unstable_preloadEntries());
+    alreadyLoaded = true;
+  } else if (
+    (stage === "start" && routePreloadingBehavior === "onStart") ||
+    (stage === "warmerEvent" && routePreloadingBehavior === "onWarmerEvent") ||
+    stage === "onDemand"
+  ) {
+    const startTimestamp = Date.now();
+    debug("Preloading entries");
+    await nextServer.unstable_preloadEntries();
+    debug("Preloading entries took", Date.now() - startTimestamp, "ms");
+    alreadyLoaded = true;
+  }
+};
 // `getRequestHandlerWithMetadata` is not available in older versions of Next.js
 // It is required to for next 15.2 to pass metadata for page router data route
 export const requestHandler = (metadata: Record<string, any>) =>

packages/open-next/src/overrides/wrappers/aws-lambda-streaming.ts

@@ -35,6 +35,7 @@ const handler: WrapperHandler = async (handler, converter) =>
       if ("type" in event) {
         const result = await formatWarmerResponse(event);
         responseStream.end(Buffer.from(JSON.stringify(result)), "utf-8");
+        await globalThis.__next_route_preloader("warmerEvent");
         return;
       }
 

packages/open-next/src/types/global.ts

@@ -211,4 +211,13 @@ declare global {
    * Defined in `createMainHandler`
    */
   var cdnInvalidationHandler: CDNInvalidationHandler;
+
+  /**
+   * A function to preload the routes.
+   * This needs to be defined on globalThis because it can be used by custom overrides.
+   * Only available in main functions.
+   */
+  var __next_route_preloader: (
+    stage: "waitUntil" | "start" | "warmerEvent" | "onDemand",
+  ) => Promise<void>;
 }

packages/open-next/src/types/open-next.ts

@@ -118,6 +118,12 @@ export interface ResolvedRoute {
   type: RouteType;
 }
 
+export type RoutePreloadingBehavior =
+  | "none"
+  | "withWaitUntil"
+  | "onWarmerEvent"
+  | "onStart";
+
 export interface RoutingResult {
   internalEvent: InternalEvent;
   // If the request is an external rewrite, if used with an external middleware will be false on every server function
@@ -170,7 +176,6 @@ export type IncludedWarmer = "aws-lambda" | "dummy";
 export type IncludedProxyExternalRequest = "node" | "fetch" | "dummy";
 
 export type IncludedCDNInvalidationHandler = "cloudfront" | "dummy";
-
 export interface DefaultOverrideOptions<
   E extends BaseEventOrResult = InternalEvent,
   R extends BaseEventOrResult = InternalResult,
@@ -313,6 +318,16 @@ export interface FunctionOptions extends DefaultFunctionOptions {
    * @deprecated This is not supported in 14.2+
    */
   experimentalBundledNextServer?: boolean;
+
+  /**
+   * The route preloading behavior. Only supported in Next 15+.
+   * - "none" - No preloading of the route at all
+   * - "withWaitUntil" - Preload the route using the waitUntil provided by the wrapper - If not supported, it will fallback to "none"
+   * - "onWarmerEvent" - Preload the route on the warmer event - Needs to be implemented by the wrapper. Only supported in `aws-lambda-streaming` wrapper for now
+   * - "onStart" - Preload the route before even invoking the wrapper - This is a blocking operation and if not used properly, may increase the cold start time by a lot
+   * @default "none"
+   */
+  routePreloadingBehavior?: RoutePreloadingBehavior;
 }
 
 export type RouteTemplate =