feat(platform): support Fetchable server entries with analog({ server })

The custom server entry can now be a Fetchable module (https://fetchable.org)
whose default export has `fetch(request)`, in addition to `createApp()`.
In dev, Analog serves the entry's `fetch` behind Vite through srvx's Node
adapter. The build output keeps the default export, so platforms that invoke
Fetchable modules can run `dist/server/main.js` directly.

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

Author: claude

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

@@ -145,6 +145,30 @@ Pass your app's `fetch`, `createAnalogRequestHandler({ fetch: (request) => app.f
 
 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.
 
+## Fetchable entry
+
+Instead of `createApp()`, the server entry can be a [Fetchable](https://fetchable.org) module: its default export has a `fetch(request)` method that returns a `Response`. Platforms and runtimes that invoke Fetchable modules, such as Netlify Functions, Cloudflare Workers, Deno and Bun, run the built entry without a server of your own.
+
+```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 })
+    );
+  },
+};
+```
+
+A Hono app is already Fetchable, so the entry can `export default app`.
+
+In development, Analog serves the entry's `fetch` behind Vite. When the entry exports both, `createApp()` is used. The built `dist/server/main.js` keeps the default export and doesn't listen on a port, so the platform serves `dist/client`. Serve it without an index fallback so `/` is server-rendered.
+
 ## 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 +197,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`. Run an entry that starts its own server with Node:
 
 ```shell
 node dist/server/main.js

packages/platform/package.json

@@ -39,6 +39,7 @@
     "ofetch": "catalog:",
     "oxc-parser": "catalog:",
     "rolldown": "catalog:",
+    "srvx": "catalog:",
     "tinyglobby": "catalog:",
     "vitefu": "catalog:",
     "xmlbuilder2": "catalog:"

packages/platform/src/lib/options.ts

@@ -96,8 +96,9 @@ export interface ServerOptions {
   /**
    * The server entry, relative to the project root. It exports
    * `createApp(): Promise<{ handle, close? }>`, which the dev server mounts,
-   * and starts its own server in production. TypeScript in the entry's
-   * directory is compiled by Vite.
+   * and starts its own server in production, or is a Fetchable module whose
+   * default export has `fetch(request)`. TypeScript in the entry's directory
+   * is compiled by Vite.
    */
   entry: string;
 }

packages/platform/src/lib/server-plugin.spec.ts

@@ -1,4 +1,6 @@
 import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { createServer as createHttpServer } from 'node:http';
+import type { AddressInfo } from 'node:net';
 import { tmpdir } from 'node:os';
 import { dirname, join } from 'node:path';
 import type { Plugin } from 'vite';
@@ -150,6 +152,44 @@ describe('serverPlugin', () => {
     }
   });
 
+  it('serves requests from a Fetchable entry in dev', async () => {
+    writeFileSync(
+      join(root, 'src/main.ts'),
+      [
+        'export default {',
+        '  async fetch(request) {',
+        '    const { pathname } = new URL(request.url);',
+        '    const body = `${request.method} ${pathname} ${await request.text()}`;',
+        "    return new Response(body, { status: 201, headers: { 'x-entry': 'fetchable' } });",
+        '  },',
+        '};',
+      ].join('\n'),
+    );
+    const vite = await createServer({
+      root,
+      configFile: false,
+      logLevel: 'silent',
+      server: { middlewareMode: true, ws: false },
+      plugins: [
+        serverPlugin({ entry: 'src/main.ts' }, { workspaceRoot: root }),
+      ],
+    });
+    const http = createHttpServer(vite.middlewares).listen(0);
+    try {
+      const { port } = http.address() as AddressInfo;
+      const response = await fetch(`http://localhost:${port}/services/echo`, {
+        method: 'POST',
+        body: 'hello',
+      });
+      expect(response.status).toBe(201);
+      expect(response.headers.get('x-entry')).toBe('fetchable');
+      expect(await response.text()).toBe('POST /services/echo hello');
+    } finally {
+      http.close();
+      await vite.close();
+    }
+  });
+
   it('refuses to require locale workers', () => {
     const plugin = serverPlugin(
       { entry: 'src/server/main.ts' },

packages/platform/src/lib/server-plugin.ts

@@ -1,6 +1,8 @@
 import { existsSync, readFileSync } from 'node:fs';
 import type { IncomingMessage, ServerResponse } from 'node:http';
 import { relative, resolve } from 'node:path';
+import type { NodeHttp1Handler } from 'srvx';
+import { toNodeHandler } from 'srvx/node';
 import {
   normalizePath,
   type Connect,
@@ -30,7 +32,11 @@ type ServerApp = {
   ) => void;
   close?: () => Promise<void>;
 };
-type ServerEntry = { createApp: () => Promise<ServerApp> };
+type FetchHandler = (request: Request) => Response | Promise<Response>;
+type ServerEntry = {
+  createApp?: () => Promise<ServerApp>;
+  default?: { fetch?: FetchHandler };
+};
 
 /**
  * Builds and serves the app from `server.entry` instead of Nitro: the client
@@ -229,7 +235,7 @@ function devMiddleware(
     const loaded = (await viteServer.ssrLoadModule(entry)) as ServerEntry;
     if (current?.entry !== loaded) {
       const previous = current;
-      current = { entry: loaded, app: loaded.createApp() };
+      current = { entry: loaded, app: createApp(loaded) };
       void previous?.app.then(
         (app) => app.close?.(),
         () => undefined,
@@ -248,6 +254,34 @@ function devMiddleware(
   };
 }
 
+/**
+ * The entry's `createApp()`, or a Node app around the `fetch` of a Fetchable
+ * entry (https://fetchable.org).
+ */
+async function createApp(entry: ServerEntry): Promise<ServerApp> {
+  if (entry.createApp) {
+    return entry.createApp();
+  }
+  const fetchable = entry.default;
+  const handleRequest = fetchable?.fetch;
+  if (typeof handleRequest !== 'function') {
+    throw new Error(
+      '[@analogjs/platform] The server entry must export `createApp()` or a default export with `fetch(request)`.',
+    );
+  }
+  // Connect middleware is typed with the HTTP/1 request and response.
+  const handle = toNodeHandler((request) =>
+    handleRequest.call(fetchable, request),
+  ) as NodeHttp1Handler;
+  return {
+    handle: (req, res, next) => {
+      Promise.resolve()
+        .then(() => handle(req, res))
+        .catch(next);
+    },
+  };
+}
+
 function removeHtmlMiddlewares(middlewares: Connect.Server): void {
   middlewares.stack = middlewares.stack.filter(
     (layer) =>

pnpm-lock.yaml

@@ -173,6 +173,7 @@ catalog:
   semantic-release-replace-plugin: ^1.2.7
   shiki: ^1.29.2 || ^4.0.2
   sharp: ^0.34.5
+  srvx: ^1.0.8
   start-server-and-test: ^3.0.0
   storybook: 10.6.0
   tslib: ^2.3.0