feat(start): expose a Fetchable SSR service entry

Let provider Vite plugins adopt Solid's normal SSR environment while preserving the standalone server artifact and custom handler API.

Co-authored-by: Cursor <cursoragent@cursor.com>

Author: ryansolid

.changeset/fetchable-start-handler.md

@@ -0,0 +1,15 @@
+---
+'vite-plugin-solid': patch
+---
+
+Start mode's generated request handler now default-exports a Fetchable
+`{ fetch(request) }` object alongside its named `handleRequest` export.
+Deployment integrations that follow the web-standard Fetchable convention
+can consume the virtual handler or built server entry without a wrapper.
+The `fetch` method intentionally ignores provider arguments after the request
+instead of forwarding them as Solid handler options.
+
+The normal `ssr` environment now exposes that handler as its `index` service
+entry. Provider Vite plugins can adopt the same environment for development
+and production without `start.external`, a custom source entry, or explicit
+Rollup input. Standalone builds continue to emit `dist/server/server.js`.

README.md

@@ -200,17 +200,23 @@ With `ssr: true` — **SSR start mode**:
   client — e.g. @cloudflare/vite-plugin — with no hand-written ordering
   plugin; setups without another orchestrator keep Vite's stock
   build-everything behavior, just client-first.
-- **Prod**: the server bundle's entry is `virtual:solid-ssr-handler`, whose
-  `handleRequest(request)` export maps a web-standard `Request` to a
-  streamed `Response` — adapter-agnostic, so any node server / worker /
-  runtime mounts SSR in one line:
+- **Prod**: the server bundle's entry is `virtual:solid-ssr-handler`.
+  Its named `handleRequest(request)` export maps a web-standard `Request`
+  to a streamed `Response`; its default `{ fetch(request) }` export provides
+  the same handler in the Fetchable shape used by Workers, Nitro, Netlify
+  Functions, Bun, and `deno serve`:
 
 ```js
-import { handleRequest } from './dist/server/server.js';
+import app, { handleRequest } from './dist/server/server.js';
 // serve dist/client statically, everything else:
 const response = await handleRequest(request);
+const sameResponse = await app.fetch(request);
 ```
 
+The Fetchable wrapper deliberately accepts only the request. Hosts may pass
+environment or execution-context arguments after it; those are not the
+Solid options accepted by `handleRequest`'s second parameter.
+
 - **Preview**: `vite build && vite preview` runs the production artifact
   with no server file — Vite's preview statics serve `dist/client`, and
   everything else (pages, the server-function endpoint, middleware)
@@ -402,31 +408,23 @@ server-function middleware pre-loads the referenced module, then dispatches
 through the same handler), so one middleware chain and one request event
 front pages and server functions identically.
 
-**`external: true`** hands the server side of start mode to a host integration
-that owns the server environment — build wiring and HTTP serving alike. The
-plugin skips its start-mode server-build config (no `dist/server` output or
-builder flag; the host's orchestrator drives the server build) and stands
-its dev middlewares down (SSR serving and the server-function endpoint
-both). Start mode still provides everything the host loads through its own
-environment: the generated entries, the client manifest, and the
-`virtual:solid-ssr-handler` request handler — which self-serves in dev,
-inlining the entry graph's CSS through a virtual dev-styles module (HMR
-included) and composing the server-function endpoint, so
-`handleRequest(request)` is the whole contract in dev exactly as in
-production.
-
-Three switches cover host-owned setups, broadest first:
-
-1. **Nothing — capability detection.** When a provider (e.g.
-   @cloudflare/vite-plugin) replaces the dev server's `ssr` environment with
-   its own non-runnable one, the plugin detects that and stands the dev
-   middlewares down automatically; the handler self-serves as above. Zero
-   config.
-2. **`start.external: true`** — the explicit whole-server switch: everything
-   detection does, plus skipping the server-build wiring. Also needed when
-   the provider owns a _differently named_ environment (not `ssr`), which
-   detection can't see.
-3. **[`serverFunctions.devMiddleware: false`](#optionsserverfunctions)** —
+The normal `ssr` environment exposes the default Fetchable handler as its
+`index` service entry in development and production. Provider Vite plugins
+can adopt that environment directly: they supply its runtime and build
+orchestration while Solid continues to supply the application entry,
+manifest, middleware, and server-function dispatch. When a provider replaces
+the development environment with a non-runnable one, Solid detects that
+ownership and stands its HTTP middlewares down automatically.
+
+Two explicit switches remain for custom host setups:
+
+1. **`start.external: true`** — hands the whole server side to a host that
+   does not adopt Solid's normal `ssr` environment. Solid skips its
+   server-build wiring and stands its development middlewares down, while
+   continuing to provide the generated entries, client manifest, and
+   `virtual:solid-ssr-handler`. This is mainly for differently named or
+   independently configured environments.
+2. **[`serverFunctions.devMiddleware: false`](#optionsserverfunctions)** —
    the narrow, endpoint-only switch: keeps start mode's server build and SSR
    serving, hands only server-function dispatch in dev to the host. For
    setups without `start`, or when only the endpoint should move.

examples/turnkey/test/run.mjs

@@ -109,7 +109,7 @@
 // (default: all)
 
 import { spawn, execSync } from 'node:child_process';
-import { fileURLToPath } from 'node:url';
+import { fileURLToPath, pathToFileURL } from 'node:url';
 import path from 'node:path';
 import { rmSync, existsSync, readdirSync, readFileSync, writeFileSync } from 'node:fs';
 import http from 'node:http';
@@ -926,6 +926,31 @@ async function runProdMode() {
   // The virtual handler's manifest import must keep the registrations in the
   // SSR bundle even though the render graph also reaches them.
   const serverBundle = readFileSync(path.join(exampleDir, 'dist/server/server.js'), 'utf-8');
+  const builtHandler = await import(
+    pathToFileURL(path.join(exampleDir, 'dist/server/server.js')).href + `?fetchable=${Date.now()}`
+  );
+  record(
+    mode,
+    'build',
+    'server handler exposes a default Fetchable entry',
+    typeof builtHandler.default?.fetch === 'function',
+  );
+  const fetchableResponse = await builtHandler.default.fetch(
+    new Request(origin + '/'),
+    // Fetch hosts commonly pass bindings and execution context after the
+    // request. The wrapper must ignore them rather than forwarding this
+    // object as handleRequest's Solid options bag.
+    { clientEntry: '/provider-argument-must-not-be-forwarded.js' },
+  );
+  const fetchableHtml = await fetchableResponse.text();
+  record(
+    mode,
+    'build',
+    'default Fetchable ignores provider arguments',
+    fetchableResponse.status === 200 &&
+      fetchableHtml.includes('SSR Start Mode') &&
+      !fetchableHtml.includes('provider-argument-must-not-be-forwarded'),
+  );
   record(
     mode,
     'build',
@@ -2843,6 +2868,15 @@ async function runDetectMode() {
       'probe ssr environment is non-runnable',
       !isRunnableDevEnvironment(server.environments.ssr),
     );
+    const ssrInput = server.environments.ssr.config.build.rollupOptions.input;
+    record(
+      mode,
+      'env',
+      'provider environment sees the Fetchable index service entry',
+      !!ssrInput &&
+        typeof ssrInput === 'object' &&
+        ssrInput.index === 'virtual:solid-ssr-handler',
+    );
 
     httpServer = http.createServer(server.middlewares);
     await new Promise((resolve) => httpServer.listen(0, '127.0.0.1', resolve));

src/index.ts

@@ -267,7 +267,10 @@ export interface Options {
    *   `dist/client`, server to `dist/server` via the environments/builder
    *   API). The server bundle's entry is `virtual:solid-ssr-handler`, whose
    *   `handleRequest(request)` export maps a web `Request` to a streamed
-   *   `Response` — mount it on any server or adapter in one line.
+   *   `Response`; its default `{ fetch(request) }` export provides the same
+   *   handler in the Fetchable shape used by deployment integrations.
+   *   The normal `ssr` environment exposes it as the `index` service entry
+   *   so provider Vite plugins can supply the runtime and build orchestration.
    * - With `serverFunctions` also enabled, the prod handler serves the
    *   server-function endpoint too (in dev the server-function middleware
    *   already runs first).

src/ssr/index.ts

@@ -14,9 +14,10 @@
 // - Prod: the plugin configures a full-app build (client + server bundles
 //   via the Vite 6+ environments/builder API — a single `vite build` builds
 //   both) whose server entry is `virtual:solid-ssr-handler`: an
-//   adapter-agnostic `handleRequest(Request) => Promise<Response>` that
-//   scopes each request with `provideRequestEvent`, streams the render, and
-//   resolves hashed client assets through `virtual:solid-manifest`.
+//   adapter-agnostic named `handleRequest(Request) => Promise<Response>` plus
+//   a default Fetchable `{ fetch(request) }` export. Both scope each request
+//   with `provideRequestEvent`, stream the render, and resolve hashed client
+//   assets through `virtual:solid-manifest`.
 // - Entries are conventional with escape hatches: `src/entry-server.*` /
 //   `src/entry-client.*` are used when present (or set explicitly); when
 //   absent, default entries are generated from a single root component
@@ -193,14 +194,16 @@ export interface StartOptions {
    * stands its dev middlewares down (SSR serving and the server-function
    * endpoint); the generated `virtual:solid-ssr-handler` self-serves
    * instead, inlining dev styles through a virtual module and composing the
-   * server-function endpoint, so `handleRequest(request)` is the whole
-   * contract in dev exactly as in production. Generated entries and the
-   * client manifest are still provided.
+   * server-function endpoint. Its named `handleRequest(request)` and default
+   * Fetchable exports provide the same contract in dev and production.
+   * Generated entries and the client manifest are still provided.
    *
    * Often unnecessary: a provider-owned (non-runnable) `ssr` dev environment
-   * is detected automatically and the middlewares stand down on their own.
-   * Set this when the host also owns the server build, or when its
-   * environment uses a different name so detection can't see it. To hand
+   * is detected automatically and the middlewares stand down on their own;
+   * the normal `ssr` environment also exposes the handler as an `index`
+   * service entry for provider build orchestrators. Set this only when the
+   * host does not adopt that environment — for example, when it uses a
+   * different name or independently configures the server build. To hand
    * over only the server-function endpoint, use
    * `serverFunctions.devMiddleware: false` instead.
    *
@@ -863,6 +866,15 @@ export function startServe(
       // createSSRResponse committed and pass through untouched.
       `  return commitEventResponse(response, event);`,
       `}`,
+      ``,
+      `export default {`,
+      `  fetch(request) {`,
+      // Hosts may pass environment/context arguments after the request.
+      // Do not alias fetch directly to handleRequest: its second argument is
+      // the Solid handler options bag, not a provider binding object.
+      `    return handleRequest(request);`,
+      `  },`,
+      `};`,
     );
 
     return lines.join('\n');
@@ -952,9 +964,16 @@ export function startServe(
                       },
                     },
                     ssr: {
+                      consumer: 'server',
                       build: {
                         outDir: 'dist/server',
-                        rollupOptions: { input: { server: HANDLER_ID } },
+                        rollupOptions: {
+                          // `index` is the Vite service convention consumed
+                          // by provider orchestrators such as Nitro. Keep the
+                          // standalone artifact's established filename.
+                          input: { index: HANDLER_ID },
+                          output: { entryFileNames: 'server.js' },
+                        },
                       },
                     },
                   },
@@ -965,6 +984,24 @@ export function startServe(
                   ...(env.isSsrBuild ? {} : { builder: {} }),
                 }
             : {
+                ...(!clientMode && !externalServer
+                  ? {
+                      environments: {
+                        ssr: {
+                          consumer: 'server' as const,
+                          build: {
+                            outDir: 'dist/server',
+                            rollupOptions: {
+                              // Expose the same service entry during serve so
+                              // provider runtimes can discover and own it.
+                              input: { index: HANDLER_ID },
+                              output: { entryFileNames: 'server.js' },
+                            },
+                          },
+                        },
+                      },
+                    }
+                  : {}),
                 optimizeDeps: { entries: scanEntries },
               }),
         };

virtual-solid-manifest.d.ts

@@ -43,4 +43,10 @@ declare module "virtual:solid-ssr-handler" {
       serverFunctions?: Record<string, unknown>;
     },
   ): Promise<Response>;
+
+  /** Fetchable entry for runtimes and deployment integrations that use the web-standard convention. */
+  const handler: {
+    fetch(request: Request): Promise<Response>;
+  };
+  export default handler;
 }