feat(platform): use Fetchable server entries for analog({ server }) (#2729)

The custom server entry is now a Fetchable module (https://fetchable.org):
its default export has fetch(request), and optionally close(), which the dev
server calls before reloading the entry. createApp() entries are no longer
supported. Node frameworks (Express, NestJS, Fastify) wrap their app with
srvx's toFetchHandler(). The NestJS template in create-analog and the custom
server and NestJS guides use the new entry.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01S3NKyLNGL2d5Df2wt4WNbA

Author: brandonroberts

apps/docs-analog/src/content/features/server/custom-server.md

@@ -1,6 +1,6 @@
 # Custom Server
 
-Serve an Analog app from your own server, such as NestJS, Express, Fastify or Hono, instead of Nitro. Your server owns the process and its routes, and Analog handles server-side rendering, page endpoints and server functions inside it.
+Serve an Analog app from your own server entry instead of Nitro: a [Fetchable](https://fetchable.org) module that platforms and runtimes invoke directly, or a server built with a framework such as Hono, Express, NestJS or Fastify. Your entry owns its routes, and Analog handles server-side rendering, page endpoints and server functions inside it. A platform or runtime runs a Fetchable entry, while a Node server entry starts its own process.
 
 :::info
 
@@ -55,49 +55,98 @@ Vite compiles the TypeScript in the entry's directory. Frameworks that use decor
 
 ## The server entry
 
-The entry exports `createApp()`, which the dev server mounts behind Vite, and starts its own server in production. With Express:
+The entry is a [Fetchable](https://fetchable.org) module: its default export has a `fetch(request)` method that returns a `Response`. `createAnalogRequestHandler()` handles Analog's requests and returns `null` for anything else:
+
+```ts
+// src/server/main.ts
+import { createAnalogRequestHandler } from '@analogjs/router/server';
+
+const handleAnalogRequest = createAnalogRequestHandler();
+
+export default {
+  async fetch(request: Request) {
+    return (
+      (await handleAnalogRequest(request)) ??
+      new Response('Not Found', { status: 404 })
+    );
+  },
+};
+```
+
+Analog handles:
+
+- server functions (`/_analog/fn/:id`) and page endpoints (`/api/_analog/pages/**`);
+- server-side rendering for `GET` requests outside `/api/`.
+
+In development, Analog serves the entry's `fetch` behind Vite. In production, platforms and runtimes that invoke Fetchable modules, such as Netlify Functions, Deno and Bun, run the built entry without a server of your own.
+
+### Fetch-native frameworks
+
+Frameworks built on web `Request`/`Response`, such as Hono, are already Fetchable. Hand Analog the requests your routes don't handle, and export the app:
+
+```ts
+// src/server/main.ts
+import { createAnalogRequestHandler } from '@analogjs/router/server';
+import { Hono } from 'hono';
+
+const app = new Hono();
+const handleAnalogRequest = createAnalogRequestHandler({
+  fetch: (request) => app.fetch(request),
+});
+
+app.get('/api/health', (c) => c.json({ ok: true }));
+app.all(
+  '*',
+  async (c) => (await handleAnalogRequest(c.req.raw)) ?? c.notFound(),
+);
+
+export default app;
+```
+
+Passing the app's `fetch` lets [server-side fetches](#server-side-fetches) reach your Hono routes in-process.
+
+### Node frameworks
+
+Frameworks built on Node's request and response, such as Express, NestJS and Fastify, wrap their app with `toFetchHandler()` from [srvx](https://srvx.h3.dev). In development, the app gets the dev server's Node request and response directly. In production, the entry can start its own server. Install `srvx`, then with Express:
 
 ```ts
 // src/server/main.ts
 import { createAnalogHandler } from '@analogjs/router/server';
 import express from 'express';
 import { fileURLToPath } from 'node:url';
+import { toFetchHandler } from 'srvx/node';
 
-function createServer() {
-  const app = express();
-  app.get('/api/health', (req, res) => res.json({ ok: true }));
+const app = express();
+app.get('/api/health', (req, res) => res.json({ ok: true }));
 
-  // Vite serves client files in development.
-  if (!import.meta.env.DEV) {
-    const clientDir = fileURLToPath(new URL('../client', import.meta.url));
-    app.use(express.static(clientDir, { index: false }));
-  }
-
-  app.use(createAnalogHandler());
-  return app;
+// Vite serves client files in development.
+if (!import.meta.env.DEV) {
+  const clientDir = fileURLToPath(new URL('../client', import.meta.url));
+  app.use(express.static(clientDir, { index: false }));
 }
 
-export async function createApp() {
-  return { handle: createServer() };
-}
+app.use(createAnalogHandler());
 
 if (!import.meta.env.DEV) {
-  createServer().listen(process.env['PORT'] ?? 3000);
+  app.listen(process.env['PORT'] ?? 3000);
 }
-```
 
-`createApp()` returns `{ handle, close? }`, where `handle` is a Node `(req, res, next)` handler. When server code changes in development, Analog creates a new app and calls `close()` on the previous one.
+export default {
+  fetch: toFetchHandler((req, res) => app(req, res)),
+};
+```
 
-`createAnalogHandler()` handles Analog's own requests and passes everything else to `next()`:
+`(req, res) => app(req, res)` calls Express without a `next` callback, so a request nothing handles gets Express's `404` instead of an empty response.
 
-- server functions (`/_analog/fn/:id`) and page endpoints (`/api/_analog/pages/**`);
-- server-side rendering for `GET` requests outside `/api/`.
+When server code changes in development, Analog reloads the entry. Add a `close()` next to `fetch` to release what the previous entry holds, such as database connections; Analog calls it before using the new entry. See [NestJS](/docs/integrations/nestjs) for an entry that closes its app.
 
-Register your own routes before it. Routes under `/api/` that nothing handles reach your server's 404 handling instead of server-side rendering.
+`createAnalogHandler()` is the Node adapter for `createAnalogRequestHandler()`: it handles Analog's requests and passes everything else to `next()`. Register your own routes before it. Routes under `/api/` that nothing handles reach your server's 404 handling instead of server-side rendering. It also passes the Node request and response to Analog as the `REQUEST` and `RESPONSE` tokens; with `createAnalogRequestHandler()`, pass them yourself as `handleAnalogRequest(request, { req, res })`.
 
 ## Server-side fetches
 
-Requests that server-side rendering and page endpoints make to the app's own origin, such as `HttpClient` calls to `/api/...` and the `fetch` passed to page endpoints, run in-process instead of over the network, as with Nitro. Analog serves its own routes. To serve your server's routes too, pass a `fetch` that handles a `Request`. It gets the requests Analog doesn't handle: routes under `/api/`, and non-`GET` requests elsewhere; other `GET` requests are server-rendered.
+Requests that server-side rendering and page endpoints make to the app's own origin, such as `HttpClient` calls to `/api/...` and the `fetch` passed to page endpoints, run in-process instead of over the network, as with Nitro. Analog serves its own routes. To serve your server's routes too, pass a `fetch` that handles a `Request`, as the Hono example does. It gets the requests Analog doesn't handle, such as your own routes under `/api/` and non-`GET` requests outside `/api/`; other `GET` requests are server-rendered.
+
+With a Node framework, forward these requests to the server's address:
 
 ```ts
 // Your server's own address, never one taken from the request.
@@ -119,32 +168,11 @@ In development, set `SERVER_ORIGIN` to Vite's dev server origin, such as `http:/
 
 ## Static files
 
-Serving client files is the server's job, with its own tools (`express.static`, `serve-static`, NestJS's `useStaticAssets()`, a CDN). In production they're in `dist/client`, next to the `dist/server` directory that holds the server entry:
+Vite serves client files in development. In production they're in `dist/client`, next to the `dist/server` directory that holds the server entry. A Fetchable entry leaves them to the platform, usually its CDN. A Node server serves them with its own tools (`express.static`, `serve-static`, NestJS's `useStaticAssets()`). Either way:
 
-- Register them **before** the Analog handler. Otherwise server-side rendering answers asset URLs.
+- Serve them **before** the Analog handler. Otherwise server-side rendering answers asset URLs.
 - Disable the index fallback (`index: false`), so `/` is server-rendered instead of returning the client's `index.html`.
 
-## Fetch-native servers
-
-Servers built on web `Request`/`Response`, such as Hono, use `createAnalogRequestHandler()`. It returns a function that takes a `Request` and returns a `Response`, or `null` for requests Analog doesn't handle:
-
-```ts
-import { createAnalogRequestHandler } from '@analogjs/router/server';
-import { Hono } from 'hono';
-
-const handleAnalogRequest = createAnalogRequestHandler();
-const app = new Hono();
-
-app.all(
-  '*',
-  async (c) => (await handleAnalogRequest(c.req.raw)) ?? c.notFound(),
-);
-```
-
-Pass your app's `fetch`, `createAnalogRequestHandler({ fetch: (request) => app.fetch(request) })`, so [server-side fetches](#server-side-fetches) reach your Hono routes in-process.
-
-Node servers that have the Node request and response can pass them as a second argument, `handleAnalogRequest(request, { req, res })`, so they become Analog's `REQUEST` and `RESPONSE` tokens. `createAnalogHandler()` does this for you.
-
 ## Streaming
 
 [Streaming SSR](/docs/features/server/streaming-ssr) works with a custom server: enable `experimental.streaming` and export `renderStream` from `main.server.ts`. Analog returns the document as a stream with `Cache-Control: no-store, no-transform`, and stops rendering when the client disconnects.
@@ -173,7 +201,7 @@ Two details of locale detection apply here as on Nitro:
 
 ## Building and running
 
-`vite build` builds the client into `dist/client` and the server entry into `dist/server/main.js`. Run it with Node:
+`vite build` builds the client into `dist/client` and the server entry into `dist/server/main.js`. A Fetchable entry keeps its default export and doesn't listen on a port; deploy it to a platform or runtime that invokes Fetchable modules. Run a Node entry that starts its own server with Node:
 
 ```shell
 node dist/server/main.js

apps/docs-analog/src/content/integrations/nestjs/index.md

@@ -24,23 +24,23 @@ To add NestJS to an existing project, follow the steps below.
   <TabItem value="npm">
 
 ```shell
-npm install @nestjs/common @nestjs/core @nestjs/platform-express reflect-metadata h3
+npm install @nestjs/common @nestjs/core @nestjs/platform-express reflect-metadata h3 srvx
 ```
 
   </TabItem>
 
   <TabItem label="yarn" value="yarn">
 
 ```shell
-yarn add @nestjs/common @nestjs/core @nestjs/platform-express reflect-metadata h3
+yarn add @nestjs/common @nestjs/core @nestjs/platform-express reflect-metadata h3 srvx
 ```
 
   </TabItem>
 
   <TabItem value="pnpm">
 
 ```shell
-pnpm add @nestjs/common @nestjs/core @nestjs/platform-express reflect-metadata h3
+pnpm add @nestjs/common @nestjs/core @nestjs/platform-express reflect-metadata h3 srvx
 ```
 
   </TabItem>
@@ -104,52 +104,49 @@ Server-side rendering and page endpoints fetch Analog's own routes in-process. T
 
 ## Step 4: Create the server entry
 
-The entry exports `createApp()`, which the dev server mounts behind Vite, and listens in production:
+The entry is a [Fetchable](https://fetchable.org) module. srvx's `toFetchHandler()` turns NestJS's Express instance into the `fetch` the dev server calls, and the entry listens on its own port in production:
 
 ```ts
 // src/server/main.ts
 import 'reflect-metadata';
 import { NestFactory } from '@nestjs/core';
 import type { NestExpressApplication } from '@nestjs/platform-express';
 import { fileURLToPath } from 'node:url';
+import { toFetchHandler } from 'srvx/node';
 
 import { AppModule } from './app.module';
 
-async function createNestApp() {
-  // Keeps the request body for Analog after Nest's body parsers have run.
-  const app = await NestFactory.create<NestExpressApplication>(AppModule, {
-    rawBody: true,
-  });
-
-  // Vite serves client files in development.
-  if (!import.meta.env.DEV) {
-    const clientDir = fileURLToPath(new URL('../client', import.meta.url));
-    app.useStaticAssets(clientDir, { index: false });
-  }
+// Keeps the request body for Analog after Nest's body parsers have run.
+const app = await NestFactory.create<NestExpressApplication>(AppModule, {
+  rawBody: true,
+});
 
-  return app.init();
+// Vite serves client files in development.
+if (!import.meta.env.DEV) {
+  const clientDir = fileURLToPath(new URL('../client', import.meta.url));
+  app.useStaticAssets(clientDir, { index: false });
 }
 
-export async function createApp() {
-  const app = await createNestApp();
-  return {
-    handle: app.getHttpAdapter().getInstance(),
-    close: () => app.close(),
-  };
-}
+await app.init();
+const server = app.getHttpAdapter().getInstance();
 
 if (!import.meta.env.DEV) {
-  const app = await createNestApp();
   await app.listen(process.env['PORT'] ?? 3000);
 }
+
+export default {
+  fetch: toFetchHandler((req, res) => server(req, res)),
+  close: () => app.close(),
+};
 ```
 
 A few details matter here:
 
 - `rawBody: true` keeps the original request bytes, so form actions and server functions can read bodies that NestJS's parsers already consumed.
 - Static files are registered before `app.init()`. Anything registered after it sits behind NestJS's 404 handler, and `init()` is also where the Analog handler is mounted.
 - `index: false` keeps `/` server-rendered instead of returning the client's `index.html`.
-- In development, Analog creates a new NestJS app when server code changes, and calls `close()` on the previous one.
+- `(req, res) => server(req, res)` calls Express without a `next` callback, so a request nothing handles gets a `404` instead of an empty response.
+- In development, Analog reloads the entry when server code changes, and calls `close()` on the previous one.
 
 ## Using the Fastify adapter
 
@@ -181,7 +178,7 @@ pnpm add @nestjs/platform-fastify serve-static
   </TabItem>
 </Tabs>
 
-The module from [Step 3](#step-3-mount-analog-in-your-module) stays the same. The entry creates a Fastify app and hands Vite Fastify's request handler:
+The module from [Step 3](#step-3-mount-analog-in-your-module) stays the same. The entry creates a Fastify app and exports Fastify's request handler as its `fetch`:
 
 ```ts
 // src/server/main.ts
@@ -193,39 +190,33 @@ import {
 } from '@nestjs/platform-fastify';
 import { fileURLToPath } from 'node:url';
 import serveStatic from 'serve-static';
+import { toFetchHandler } from 'srvx/node';
 
 import { AppModule } from './app.module';
 
-async function createNestApp() {
-  const app = await NestFactory.create<NestFastifyApplication>(
-    AppModule,
-    new FastifyAdapter(),
-  );
-
-  // Vite serves client files in development.
-  if (!import.meta.env.DEV) {
-    const clientDir = fileURLToPath(new URL('../client', import.meta.url));
-    app.use(serveStatic(clientDir, { index: false }));
-  }
+const app = await NestFactory.create<NestFastifyApplication>(
+  AppModule,
+  new FastifyAdapter(),
+);
 
-  await app.init();
-  await app.getHttpAdapter().getInstance().ready();
-  return app;
+// Vite serves client files in development.
+if (!import.meta.env.DEV) {
+  const clientDir = fileURLToPath(new URL('../client', import.meta.url));
+  app.use(serveStatic(clientDir, { index: false }));
 }
 
-export async function createApp() {
-  const app = await createNestApp();
-  const fastify = app.getHttpAdapter().getInstance();
-  return {
-    handle: (req, res) => fastify.routing(req, res),
-    close: () => app.close(),
-  };
-}
+await app.init();
+const fastify = app.getHttpAdapter().getInstance();
+await fastify.ready();
 
 if (!import.meta.env.DEV) {
-  const app = await createNestApp();
   await app.listen(process.env['PORT'] ?? 3000, '0.0.0.0');
 }
+
+export default {
+  fetch: toFetchHandler((req, res) => fastify.routing(req, res)),
+  close: () => app.close(),
+};
 ```
 
 How it differs from Express:
@@ -239,10 +230,10 @@ How it differs from Express:
 
 Under `vite`, NestJS runs inside the dev server rather than listening on its own port:
 
-- The first request Vite doesn't serve itself calls `createApp()`, which runs `NestFactory.create()` and `init()`.
+- The first request Vite doesn't serve itself loads the entry, which runs `NestFactory.create()` and `init()`.
 - Vite serves client files and HMR, and passes every other request to NestJS, which routes it as in production.
 - Vite compiles the NestJS code, so there's no `nest start --watch` or `tsc` step.
-- When server code changes, the next request creates a new NestJS app and calls `close()` on the previous one, so shutdown hooks run.
+- When server code changes, the next request reloads the entry, creating a new NestJS app, and calls `close()` on the previous one, so shutdown hooks run.
 - To reach controllers from [server-side fetches](/docs/features/server/custom-server#server-side-fetches), point the origin at Vite's dev server, such as `http://localhost:5173`.
 
 ## Using NestJS services from Angular code

packages/create-analog/__tests__/cli.spec.ts

@@ -242,6 +242,7 @@ test(
           '@nestjs/platform-express',
           'h3',
           'reflect-metadata',
+          'srvx',
         ]),
       );
       expect(