feat: support lazily loading routes/handlers (#3131)

We can improve cold start times by only loading route modules when the particular pattern matches. This PR introduces the concept of lazy middlewares, routes and handlers to do that.

Author: marvinhagemeister

docs/canary/concepts/app.md

@@ -17,6 +17,23 @@ const app = new App()
 app.listen();
 ```
 
+All items are applied from top to bottom. This means that when you defined a
+middleware _after_ a `.get()` handler, it won't be included.
+
+```ts
+const app = new App()
+  .use((ctx) => {
+    // Will be called for all middlewares
+    return ctx.next();
+  })
+  .get("/", () => new Response("hello"))
+  .use((ctx) => {
+    // Will only be called for `/about
+    return ctx.next();
+  })
+  .get("/about", (ctx) => ctx.render(<h1>About me</h1>));
+```
+
 ## `.use()`
 
 Add one or more [middlewares](/docs/canary/concepts/middleware). Middlewares are
@@ -42,6 +59,15 @@ Adding middlewares at a specific path:
 app.use("/foo/bar", middleware);
 ```
 
+Middlewares can also be instantiated lazily:
+
+```ts
+app.use("/foo/bar", async () => {
+  const mod = await import("./path/to/my/middleware.ts");
+  return mod.default;
+});
+```
+
 ## `.get()`
 
 Respond to a `GET` request with the specified middlewares.
@@ -60,6 +86,15 @@ app.get("/about", middleware1, middleware2, async (ctx) => {
 });
 ```
 
+You can also pass lazy middlewares:
+
+```ts
+app.get("/about", async () => {
+  const mod = await import("./middleware-or-handler.ts");
+  return mod.default;
+});
+```
+
 ## `.post()`
 
 Respond to a `POST` request with the specified middlewares.
@@ -80,6 +115,15 @@ app.post("/api/user/:id", middleware1, middleware2, async (ctx) => {
 });
 ```
 
+You can also pass lazy middlewares:
+
+```ts
+app.post("/api/user/:id", async () => {
+  const mod = await import("./middleware-or-handler.ts");
+  return mod.default;
+});
+```
+
 ## `.put()`
 
 Respond to a `PUT` request with the specified middlewares.
@@ -100,6 +144,15 @@ app.put("/api/user/:id", middleware1, middleware2, async (ctx) => {
 });
 ```
 
+You can also pass lazy middlewares:
+
+```ts
+app.put("/api/user/:id", async () => {
+  const mod = await import("./middleware-or-handler.ts");
+  return mod.default;
+});
+```
+
 ## `.delete()`
 
 Respond to a `DELETE` request with the specified middlewares.
@@ -120,6 +173,15 @@ app.delete("/api/user/:id", middleware1, middleware2, async (ctx) => {
 });
 ```
 
+You can also pass lazy middlewares:
+
+```ts
+app.delete("/api/user/:id", async () => {
+  const mod = await import("./middleware-or-handler.ts");
+  return mod.default;
+});
+```
+
 ## `.head()`
 
 Respond to a `HEAD` request with the specified middlewares.
@@ -138,6 +200,15 @@ app.head("/api/user/:id", middleware1, middleware2, async (ctx) => {
 });
 ```
 
+You can also pass lazy middlewares:
+
+```ts
+app.head("/api/user/:id", async () => {
+  const mod = await import("./middleware-or-handler.ts");
+  return mod.default;
+});
+```
+
 ## `.all()`
 
 Respond to a request for all HTTP verbs with the specified middlewares.
@@ -156,6 +227,34 @@ app.all("/api/foo", middleware1, middleware2, async (ctx) => {
 });
 ```
 
+You can also pass lazy middlewares:
+
+```ts
+app.all("/api/foo", async () => {
+  const mod = await import("./middleware-or-handler.ts");
+  return mod.default;
+});
+```
+
+## `.fsRoute()`
+
+Injects all file-based routes, middlewares, layouts and error pages to the app
+instance.
+
+```ts
+app.fsRoutes();
+```
+
+You can optionally pass a path where they should be mounted.
+
+```ts
+app.fsRoutes("/foo/bar");
+```
+
+> [info]: If possible, routes are lazily loaded. Routes that set a route config
+> and set `routeOverride` in particular, are never lazily loaded as Fresh would
+> need to load the file to get the route pattern.
+
 ## `.route()`
 
 TODO

init/src/init_test.ts

@@ -165,27 +165,33 @@ Deno.test(
   },
 );
 
-Deno.test("init - can start dev server", async () => {
-  await using tmp = await withTmpDir();
-  const dir = tmp.dir;
-  using _promptStub = stubPrompt(".");
-  using _confirmStub = stubConfirm();
-  await initProject(dir, [], {});
-  await expectProjectFile(dir, "main.ts");
-  await expectProjectFile(dir, "dev.ts");
+Deno.test({
+  // TODO: For some reason this test is flaky in GitHub CI. It works when
+  // testing locally on windows though. Not sure what's going on.
+  ignore: Deno.build.os === "windows" && Deno.env.get("CI") !== undefined,
+  name: "init - can start dev server",
+  fn: async () => {
+    await using tmp = await withTmpDir();
+    const dir = tmp.dir;
+    using _promptStub = stubPrompt(".");
+    using _confirmStub = stubConfirm();
+    await initProject(dir, [], {});
+    await expectProjectFile(dir, "main.ts");
+    await expectProjectFile(dir, "dev.ts");
 
-  await patchProject(dir);
-  await withChildProcessServer(
-    dir,
-    ["task", "dev"],
-    async (address) => {
-      await withBrowser(async (page) => {
-        await page.goto(address);
-        await page.locator("#decrement").click();
-        await waitForText(page, "button + p", "2");
-      });
-    },
-  );
+    await patchProject(dir);
+    await withChildProcessServer(
+      dir,
+      ["task", "dev"],
+      async (address) => {
+        await withBrowser(async (page) => {
+          await page.goto(address);
+          await page.locator("#decrement").click();
+          await waitForText(page, "button + p", "2");
+        });
+      },
+    );
+  },
 });
 
 Deno.test("init - can start built project", async () => {

src/app.ts

@@ -2,13 +2,17 @@ import { trace } from "@opentelemetry/api";
 
 import { DENO_DEPLOYMENT_ID } from "./runtime/build_id.ts";
 import * as colors from "@std/fmt/colors";
-import { type MiddlewareFn, runMiddlewares } from "./middlewares/mod.ts";
+import {
+  type MaybeLazyMiddleware,
+  type MiddlewareFn,
+  runMiddlewares,
+} from "./middlewares/mod.ts";
 import { Context } from "./context.ts";
 import { mergePath, type Method, UrlPatternRouter } from "./router.ts";
 import type { FreshConfig, ResolvedFreshConfig } from "./config.ts";
 import type { BuildCache } from "./build_cache.ts";
 import { HttpError } from "./error.ts";
-import type { LayoutConfig, Route } from "./types.ts";
+import type { LayoutConfig, MaybeLazy, Route, RouteConfig } from "./types.ts";
 import type { RouteComponent } from "./segments.ts";
 import {
   applyCommands,
@@ -182,14 +186,14 @@ export class App<State> {
   /**
    * Add one or more middlewares at the top or the specified path.
    */
-  use(...middleware: MiddlewareFn<State>[]): this;
-  use(path: string, ...middleware: MiddlewareFn<State>[]): this;
+  use(...middleware: MaybeLazyMiddleware<State>[]): this;
+  use(path: string, ...middleware: MaybeLazyMiddleware<State>[]): this;
   use(
-    pathOrMiddleware: string | MiddlewareFn<State>,
-    ...middlewares: MiddlewareFn<State>[]
+    pathOrMiddleware: string | MaybeLazyMiddleware<State>,
+    ...middlewares: MaybeLazyMiddleware<State>[]
   ): this {
     let pattern: string;
-    let fns: MiddlewareFn<State>[];
+    let fns: MaybeLazyMiddleware<State>[];
     if (typeof pathOrMiddleware === "string") {
       pattern = pathOrMiddleware;
       fns = middlewares!;
@@ -234,58 +238,62 @@ export class App<State> {
     return this;
   }
 
-  route(path: string, route: Route<State>): this {
-    this.#commands.push(newRouteCmd(path, route, false));
+  route(
+    path: string,
+    route: MaybeLazy<Route<State>>,
+    config?: RouteConfig,
+  ): this {
+    this.#commands.push(newRouteCmd(path, route, config, false));
     return this;
   }
 
   /**
    * Add middlewares for GET requests at the specified path.
    */
-  get(path: string, ...middlewares: MiddlewareFn<State>[]): this {
+  get(path: string, ...middlewares: MaybeLazy<MiddlewareFn<State>>[]): this {
     this.#commands.push(newHandlerCmd("GET", path, middlewares, false));
     return this;
   }
   /**
    * Add middlewares for POST requests at the specified path.
    */
-  post(path: string, ...middlewares: MiddlewareFn<State>[]): this {
+  post(path: string, ...middlewares: MaybeLazy<MiddlewareFn<State>>[]): this {
     this.#commands.push(newHandlerCmd("POST", path, middlewares, false));
     return this;
   }
   /**
    * Add middlewares for PATCH requests at the specified path.
    */
-  patch(path: string, ...middlewares: MiddlewareFn<State>[]): this {
+  patch(path: string, ...middlewares: MaybeLazy<MiddlewareFn<State>>[]): this {
     this.#commands.push(newHandlerCmd("PATCH", path, middlewares, false));
     return this;
   }
   /**
    * Add middlewares for PUT requests at the specified path.
    */
-  put(path: string, ...middlewares: MiddlewareFn<State>[]): this {
+  put(path: string, ...middlewares: MaybeLazy<MiddlewareFn<State>>[]): this {
     this.#commands.push(newHandlerCmd("PUT", path, middlewares, false));
     return this;
   }
   /**
    * Add middlewares for DELETE requests at the specified path.
    */
-  delete(path: string, ...middlewares: MiddlewareFn<State>[]): this {
+  delete(path: string, ...middlewares: MaybeLazy<MiddlewareFn<State>>[]): this {
     this.#commands.push(newHandlerCmd("DELETE", path, middlewares, false));
     return this;
   }
   /**
    * Add middlewares for HEAD requests at the specified path.
    */
-  head(path: string, ...middlewares: MiddlewareFn<State>[]): this {
+  head(path: string, ...middlewares: MaybeLazy<MiddlewareFn<State>>[]): this {
     this.#commands.push(newHandlerCmd("HEAD", path, middlewares, false));
     return this;
   }
 
   /**
    * Add middlewares for all HTTP verbs at the specified path.
    */
-  all(path: string, ...middlewares: MiddlewareFn<State>[]): this {
+  all(path: string, ...middlewares: MaybeLazy<MiddlewareFn<State>>[]): this {
     this.#commands.push(newHandlerCmd("ALL", path, middlewares, false));
     return this;
   }
@@ -359,7 +367,7 @@ export class App<State> {
       }
     }
 
-    const router = new UrlPatternRouter<MiddlewareFn<State>>();
+    const router = new UrlPatternRouter<MaybeLazyMiddleware<State>>();
 
     const { rootMiddlewares } = applyCommands(
       router,

src/app_test.tsx

@@ -616,3 +616,64 @@ Deno.test("App - .route() with basePath", async () => {
   expect(await res.text()).toEqual("ok");
   expect(res.status).toEqual(200);
 });
+
+Deno.test("App - .use() - lazy", async () => {
+  const app = new App<{ text: string }>()
+    // deno-lint-ignore require-await
+    .use(async () => {
+      return (ctx) => {
+        ctx.state.text = "ok";
+        return ctx.next();
+      };
+    })
+    .get("/", (ctx) => new Response(ctx.state.text));
+
+  const server = new FakeServer(app.handler());
+
+  const res = await server.get("/");
+  expect(await res.text()).toEqual("ok");
+});
+
+Deno.test("App - .route() - lazy", async () => {
+  const app = new App()
+    // deno-lint-ignore require-await
+    .route("/", async () => {
+      return { handler: () => new Response("ok") };
+    });
+
+  const server = new FakeServer(app.handler());
+
+  const res = await server.get("/");
+  expect(await res.text()).toEqual("ok");
+});
+
+Deno.test("App - .get/post/patch/put/delete/head/all() - lazy", async () => {
+  const app = new App()
+    .get("/", () => Promise.resolve(() => new Response("ok")))
+    .post("/", () => Promise.resolve(() => new Response("ok")))
+    .patch("/", () => Promise.resolve(() => new Response("ok")))
+    .delete("/", () => Promise.resolve(() => new Response("ok")))
+    .put("/", () => Promise.resolve(() => new Response("ok")))
+    .head("/", () => Promise.resolve(() => new Response("ok")))
+    .all("/", () => Promise.resolve(() => new Response("ok")));
+
+  const server = new FakeServer(app.handler());
+
+  let res = await server.get("/");
+  expect(await res.text()).toEqual("ok");
+
+  res = await server.post("/");
+  expect(await res.text()).toEqual("ok");
+
+  res = await server.put("/");
+  expect(await res.text()).toEqual("ok");
+
+  res = await server.patch("/");
+  expect(await res.text()).toEqual("ok");
+
+  res = await server.delete("/");
+  expect(await res.text()).toEqual("ok");
+
+  res = await server.head("/");
+  expect(await res.text()).toEqual("ok");
+});