From fd9e80aebdfde38757f1ff68b7891d84d0ee0a32 Mon Sep 17 00:00:00 2001
From: "Alexis H. Munsayac" <alexis.munsayac@gmail.com>
Date: Wed, 14 Oct 2026 13:18:48 +0800
Subject: [PATCH] feat: add ssr: "data-only"

The app renders on the client without hydration, as with `ssr: false`, but
the server runs the requested page's route preloads and streams their query
results with the HTML shell. The client's queries read those results on the
first render instead of fetching them again.

The server collects the queries with the router's data-only pass, the same
one single-flight mutations use, and streams them through Solid's own
serializer under a `<Hydration>` boundary. On the client, `mount()` points
`sharedConfig.has`/`load` at `_$HY.r` for the first `render()`, which is
where `query` already looks for serialized data.

Also export `getServerFunctionMeta`, `decorateHandler` and
`decorateMiddleware` from the SPA server entry, so SPA apps that import them
build.

Closes #2287

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
---
 .changeset/spa-server-exports.md              |   5 +
 .changeset/ssr-data-only.md                   |   5 +
 packages/start/src/client/spa/index.tsx       |   8 +-
 .../start/src/client/spa/initial-data.spec.ts |  29 +++
 packages/start/src/client/spa/initial-data.ts |  25 +++
 packages/start/src/config/index.ts            |  12 +-
 packages/start/src/env.d.ts                   |   1 +
 packages/start/src/server/handler.ts          |   2 +-
 packages/start/src/server/spa/StartServer.tsx |  17 +-
 packages/start/src/server/spa/handler.ts      |   4 +
 packages/start/src/server/spa/index.tsx       |   3 +
 .../start/src/server/spa/initial-data.spec.ts | 165 ++++++++++++++++++
 packages/start/src/server/spa/initial-data.ts |  95 ++++++++++
 13 files changed, 364 insertions(+), 7 deletions(-)
 create mode 100644 .changeset/spa-server-exports.md
 create mode 100644 .changeset/ssr-data-only.md
 create mode 100644 packages/start/src/client/spa/initial-data.spec.ts
 create mode 100644 packages/start/src/client/spa/initial-data.ts
 create mode 100644 packages/start/src/server/spa/initial-data.spec.ts
 create mode 100644 packages/start/src/server/spa/initial-data.ts

diff --git a/.changeset/spa-server-exports.md b/.changeset/spa-server-exports.md
new file mode 100644
index 000000000..0b93f41f4
--- /dev/null
+++ b/.changeset/spa-server-exports.md
@@ -0,0 +1,5 @@
+---
+"@solidjs/start": patch
+---
+
+Export `getServerFunctionMeta`, `decorateHandler` and `decorateMiddleware` from `@solidjs/start/server` in SPA mode (`ssr: false`), so apps using them build.
diff --git a/.changeset/ssr-data-only.md b/.changeset/ssr-data-only.md
new file mode 100644
index 000000000..6cb06a6f1
--- /dev/null
+++ b/.changeset/ssr-data-only.md
@@ -0,0 +1,5 @@
+---
+"@solidjs/start": minor
+---
+
+Add `ssr: "data-only"`. The app renders on the client without hydration, as with `ssr: false`, but the server runs the requested page's route `preload`s and streams their query results with the HTML shell, so the client doesn't fetch that data again.
diff --git a/packages/start/src/client/spa/index.tsx b/packages/start/src/client/spa/index.tsx
index 77ad443bc..7ec13dc73 100644
--- a/packages/start/src/client/spa/index.tsx
+++ b/packages/start/src/client/spa/index.tsx
@@ -1,9 +1,15 @@
 // @refresh skip
 import type { JSX } from "solid-js";
 import { render, type MountableElement } from "solid-js/web";
+import { seedInitialData } from "./initial-data.ts";
 
 export function mount(fn: () => JSX.Element, el: MountableElement) {
-  render(fn, el);
+  const restore = import.meta.env.START_SSR_DATA ? seedInitialData() : undefined;
+  try {
+    render(fn, el);
+  } finally {
+    restore?.();
+  }
 }
 
 export { StartClient } from "../StartClient.tsx";
diff --git a/packages/start/src/client/spa/initial-data.spec.ts b/packages/start/src/client/spa/initial-data.spec.ts
new file mode 100644
index 000000000..abd491678
--- /dev/null
+++ b/packages/start/src/client/spa/initial-data.spec.ts
@@ -0,0 +1,29 @@
+import { sharedConfig } from "solid-js";
+import { afterEach, describe, expect, it } from "vitest";
+
+import { seedInitialData } from "./initial-data.ts";
+
+describe("seedInitialData", () => {
+  afterEach(() => {
+    delete (globalThis as any)._$HY;
+  });
+
+  it("does nothing without streamed data", () => {
+    expect(seedInitialData()).toBeUndefined();
+    expect(sharedConfig.has).toBeUndefined();
+  });
+
+  it("lets the first render read the streamed data, then puts sharedConfig back", () => {
+    const value = Promise.resolve({ id: 1 });
+    (globalThis as any)._$HY = { r: { 'user["1"]': value } };
+
+    const restore = seedInitialData()!;
+    expect(sharedConfig.has!('user["1"]')).toBe(true);
+    expect(sharedConfig.has!("other[]")).toBe(false);
+    expect(sharedConfig.load!('user["1"]')).toBe(value);
+
+    restore();
+    expect(sharedConfig.has).toBeUndefined();
+    expect(sharedConfig.load).toBeUndefined();
+  });
+});
diff --git a/packages/start/src/client/spa/initial-data.ts b/packages/start/src/client/spa/initial-data.ts
new file mode 100644
index 000000000..e1a60e8c4
--- /dev/null
+++ b/packages/start/src/client/spa/initial-data.ts
@@ -0,0 +1,25 @@
+import { sharedConfig } from "solid-js";
+
+/**
+ * With `ssr: "data-only"`, the HTML shell streams the query results of the
+ * requested page into `_$HY.r`, which is where hydration keeps serialized
+ * data. The router's `query` already reads that through `sharedConfig.has` and
+ * `sharedConfig.load` on a cache miss, but those are only set while
+ * hydrating. Set them for the first render so the queries take the streamed
+ * results instead of fetching them again.
+ *
+ * Returns a function that puts `sharedConfig` back once the first render has
+ * made its queries.
+ */
+export function seedInitialData(): (() => void) | undefined {
+  const records = (globalThis as { _$HY?: { r?: Record<string, unknown> } })._$HY?.r;
+  if (!records) return;
+
+  const { has, load } = sharedConfig;
+  sharedConfig.has = key => key in records;
+  sharedConfig.load = key => records[key];
+  return () => {
+    sharedConfig.has = has;
+    sharedConfig.load = load;
+  };
+}
diff --git a/packages/start/src/config/index.ts b/packages/start/src/config/index.ts
index 658391c81..e3da30ddc 100644
--- a/packages/start/src/config/index.ts
+++ b/packages/start/src/config/index.ts
@@ -55,10 +55,13 @@ export interface SolidStartOptions {
    *
    * - `true` — SSR (default)
    * - `false` — client-side rendering only (SPA mode)
+   * - `"data-only"` — SPA mode, but the server runs the route `preload`s for the
+   *   requested page and sends their query results with the HTML shell. The
+   *   client renders without hydrating and without fetching that data again.
    *
    * @default true
    */
-  ssr?: boolean;
+  ssr?: boolean | "data-only";
 
   /**
    * Show the SolidStart development overlay (error overlay, etc.) in development.
@@ -347,7 +350,7 @@ export function solidStart(options?: SolidStartOptions): Array<PluginOption> {
           resolve: {
             alias: {
               "@solidjs/start/server/entry": handlers.server,
-              ...(!start.ssr
+              ...(start.ssr !== true
                 ? {
                     "@solidjs/start/server": "@solidjs/start/server/spa",
                     "@solidjs/start/client": "@solidjs/start/client/spa",
@@ -367,7 +370,8 @@ export function solidStart(options?: SolidStartOptions): Array<PluginOption> {
           },
           define: {
             "import.meta.env.MANIFEST": `globalThis.MANIFEST`,
-            "import.meta.env.START_SSR": JSON.stringify(start.ssr),
+            "import.meta.env.START_SSR": JSON.stringify(start.ssr === true),
+            "import.meta.env.START_SSR_DATA": JSON.stringify(start.ssr === "data-only"),
             // Use JSON.stringify so backslashes on Windows are escaped and
             // esbuild receives a valid JS string literal for the define value
             "import.meta.env.START_APP_ENTRY": JSON.stringify(appEntryPath),
@@ -404,7 +408,7 @@ export function solidStart(options?: SolidStartOptions): Array<PluginOption> {
         ssr: new SolidStartServerFileRouter({
           dir: absolute(routeDir, root),
           extensions,
-          dataOnly: !start.ssr,
+          dataOnly: start.ssr !== true,
         }),
       },
     }),
diff --git a/packages/start/src/env.d.ts b/packages/start/src/env.d.ts
index da45f74d6..3d32bc363 100644
--- a/packages/start/src/env.d.ts
+++ b/packages/start/src/env.d.ts
@@ -9,6 +9,7 @@ interface ImportMetaEnv extends SolidStartMetaEnv {}
 
 interface SolidStartMetaEnv {
   START_SSR: boolean;
+  START_SSR_DATA: boolean;
   START_APP_ENTRY: string;
   START_CLIENT_ENTRY: string;
   START_CLIENT_ENTRY_URL: string;
diff --git a/packages/start/src/server/handler.ts b/packages/start/src/server/handler.ts
index 550785857..1b2a4831b 100644
--- a/packages/start/src/server/handler.ts
+++ b/packages/start/src/server/handler.ts
@@ -64,7 +64,7 @@ export function createBaseHandler(
       const mode = resolvedOptions.mode || "stream";
       if (resolvedOptions.nonce) context.nonce = resolvedOptions.nonce;
 
-      if (mode === "sync" || !import.meta.env.START_SSR) {
+      if (mode === "sync" || (!import.meta.env.START_SSR && !import.meta.env.START_SSR_DATA)) {
         const html = renderToString(() => {
           (sharedConfig.context as any).event = context;
           return fn(context);
diff --git a/packages/start/src/server/spa/StartServer.tsx b/packages/start/src/server/spa/StartServer.tsx
index 17d7bfb8b..db0148108 100644
--- a/packages/start/src/server/spa/StartServer.tsx
+++ b/packages/start/src/server/spa/StartServer.tsx
@@ -1,12 +1,13 @@
 // @refresh skip
 // @ts-ignore
 import type { Component } from "solid-js";
-import { NoHydration, getRequestEvent, ssr } from "solid-js/web";
+import { Hydration, HydrationScript, NoHydration, getRequestEvent, ssr } from "solid-js/web";
 import { getSsrManifest } from "../manifest/ssr-manifest.ts";
 
 import { TopErrorBoundary } from "../../shared/ErrorBoundary.tsx";
 import { useAssets } from "../assets/index.ts";
 import PatchVirtualDevStyles from "../assets/PatchVirtualDevStyles.tsx";
+import { InitialData } from "./initial-data.ts";
 import type { DocumentComponentProps, PageEvent } from "../types.ts";
 
 const docType = ssr("<!DOCTYPE html>");
@@ -26,9 +27,23 @@ export function StartServer(props: { document: Component<DocumentComponentProps>
       {docType as unknown as any}
       <TopErrorBoundary>
         <props.document
+          assets={
+            import.meta.env.START_SSR_DATA ? (
+              // Defines `_$HY.r` for the streamed data. Nothing hydrates, so it
+              // doesn't need to capture events for replay. The client types
+              // don't list `eventNames`, the server implementation takes it.
+              // @ts-expect-error
+              <HydrationScript eventNames={[]} />
+            ) : undefined
+          }
           scripts={
             <>
               <PatchVirtualDevStyles nonce={nonce} />
+              {import.meta.env.START_SSR_DATA && (
+                <Hydration>
+                  <InitialData />
+                </Hydration>
+              )}
               <script
                 type="module"
                 nonce={nonce}
diff --git a/packages/start/src/server/spa/handler.ts b/packages/start/src/server/spa/handler.ts
index 6cc10f172..67e14055f 100644
--- a/packages/start/src/server/spa/handler.ts
+++ b/packages/start/src/server/spa/handler.ts
@@ -3,6 +3,7 @@ import type { JSX } from "solid-js";
 import { createBaseHandler } from "../handler.ts";
 import { getSsrManifest } from "../manifest/ssr-manifest.ts";
 import type { FetchEvent, HandlerOptions, PageEvent, StartHandler } from "../types.ts";
+import { loadInitialData } from "./initial-data.ts";
 
 /**
  *
@@ -17,6 +18,7 @@ export function createHandler(
 }
 
 async function createPageEvent(ctx: FetchEvent) {
+  ctx.response.headers.set("Content-Type", "text/html");
   const manifest = getSsrManifest("ssr");
   const pageEvent: PageEvent = Object.assign(ctx, {
     manifest: "json" in manifest ? await manifest.json() : {},
@@ -26,5 +28,7 @@ async function createPageEvent(ctx: FetchEvent) {
     $islands: new Set<string>(),
   });
 
+  if (import.meta.env.START_SSR_DATA) await loadInitialData(pageEvent);
+
   return pageEvent;
 }
diff --git a/packages/start/src/server/spa/index.tsx b/packages/start/src/server/spa/index.tsx
index dc738f686..f52cca5fc 100644
--- a/packages/start/src/server/spa/index.tsx
+++ b/packages/start/src/server/spa/index.tsx
@@ -1,5 +1,8 @@
 // @refresh skip
 export { default as lazy } from "../../shared/lazy.ts";
+export { getServerFunctionMeta } from "../../shared/serverFunction.ts";
 export * from "../types.ts";
 export { StartServer } from "./StartServer.tsx";
+export { decorateHandler, decorateMiddleware } from "../fetchEvent.ts";
 export { createHandler } from "./handler.ts";
+export type { ServerFunctionErrorHandler } from "../../fns/error-handler.ts";
diff --git a/packages/start/src/server/spa/initial-data.spec.ts b/packages/start/src/server/spa/initial-data.spec.ts
new file mode 100644
index 000000000..4078d468f
--- /dev/null
+++ b/packages/start/src/server/spa/initial-data.spec.ts
@@ -0,0 +1,165 @@
+import { sharedConfig } from "solid-js";
+import { getRequestEvent } from "solid-js/web";
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+import type { PageEvent } from "../types.ts";
+import { InitialData, loadInitialData } from "./initial-data.ts";
+
+vi.mock("solid-js/web", async () => {
+  const { sharedConfig } = await import("solid-js");
+  return {
+    renderToString: (fn: () => unknown) => {
+      sharedConfig.context = {} as any;
+      try {
+        return fn();
+      } finally {
+        sharedConfig.context = undefined;
+      }
+    },
+    getRequestEvent: vi.fn(),
+  };
+});
+
+vi.mock("../../router.tsx", () => ({
+  createRoutes: () => [],
+}));
+
+// Stands in for the router: in data-only mode it records each query call in
+// `event.router.data`, the way `query` does.
+let queries: Record<string, () => unknown> = {};
+let currentEvent: PageEvent;
+vi.mock("solid-start:app", () => ({
+  default: () => {
+    const router = (currentEvent as any).router;
+    if (!router.dataOnly) return;
+    router.data ||= {};
+    for (const key in queries) router.data[key] = queries[key]!();
+  },
+}));
+
+function createEvent(): PageEvent {
+  return {
+    request: new Request("http://localhost/page"),
+    response: { headers: new Headers() },
+  } as unknown as PageEvent;
+}
+
+function serializeInitialData(event: PageEvent, async = true) {
+  const serialize = vi.fn();
+  vi.mocked(getRequestEvent).mockReturnValue(event);
+  sharedConfig.context = { async, serialize } as any;
+  try {
+    InitialData();
+  } finally {
+    sharedConfig.context = undefined;
+  }
+  return Object.fromEntries(
+    serialize.mock.calls.map(([key, value]) => [key, value as Promise<unknown>]),
+  );
+}
+
+describe("ssr: data-only initial data", () => {
+  beforeEach(() => {
+    queries = {};
+    currentEvent = createEvent();
+  });
+
+  it("streams the result of each query the page's preloads made", async () => {
+    queries = {
+      'user["1"]': () => Promise.resolve({ id: 1 }),
+      "list[]": () => Promise.resolve([1, 2]),
+    };
+    await loadInitialData(currentEvent);
+
+    const data = serializeInitialData(currentEvent);
+    expect(Object.keys(data)).toEqual(['user["1"]', "list[]"]);
+    await expect(data['user["1"]']).resolves.toEqual({ id: 1 });
+    await expect(data["list[]"]).resolves.toEqual([1, 2]);
+  });
+
+  it("leaves the router out of data-only mode afterwards", async () => {
+    queries = { "a[]": () => Promise.resolve(1) };
+    await loadInitialData(currentEvent);
+    expect((currentEvent as any).router.dataOnly).toBeUndefined();
+    expect((currentEvent as any).router.data).toBeUndefined();
+  });
+
+  it("skips queries the router left out", async () => {
+    queries = { "a[]": () => undefined, "b[]": () => Promise.resolve(2) };
+    await loadInitialData(currentEvent);
+    expect(Object.keys(serializeInitialData(currentEvent))).toEqual(["b[]"]);
+  });
+
+  it("sends the body of a json() response and keeps its headers except the body ones", async () => {
+    queries = {
+      "a[]": () => {
+        const response = new Response(null, {
+          headers: {
+            "content-type": "application/json",
+            "set-cookie": "a=1",
+            "x-custom": "yes",
+          },
+        });
+        (response as any).customBody = () => ({ ok: true });
+        return Promise.resolve(response);
+      },
+    };
+    currentEvent.response.headers.set("content-type", "text/html");
+    currentEvent.response.headers.append("set-cookie", "b=2");
+    await loadInitialData(currentEvent);
+
+    await expect(serializeInitialData(currentEvent)["a[]"]).resolves.toEqual({ ok: true });
+    expect(currentEvent.response.headers.get("content-type")).toBe("text/html");
+    expect(currentEvent.response.headers.getSetCookie()).toEqual(["b=2", "a=1"]);
+    expect(currentEvent.response.headers.get("x-custom")).toBe("yes");
+  });
+
+  it("turns a returned redirect into a redirect of the page", async () => {
+    queries = {
+      "a[]": () =>
+        Promise.resolve(new Response(null, { status: 307, headers: { Location: "/login" } })),
+    };
+    await loadInitialData(currentEvent);
+
+    await expect(serializeInitialData(currentEvent)["a[]"]).resolves.toBeUndefined();
+    expect(currentEvent.response.headers.get("Location")).toBe("/login");
+    expect(currentEvent.response.status).toBe(307);
+  });
+
+  it("does not report a thrown redirect as an error", async () => {
+    queries = {
+      "a[]": () => Promise.reject(new Response(null, { status: 302, headers: { Location: "/" } })),
+    };
+    await loadInitialData(currentEvent);
+
+    await expect(serializeInitialData(currentEvent)["a[]"]).resolves.toBeUndefined();
+    expect(currentEvent.response.headers.get("Location")).toBe("/");
+  });
+
+  it("streams a failed query as a rejection", async () => {
+    const error = new Error("boom");
+    queries = { "a[]": () => Promise.reject(error) };
+    await loadInitialData(currentEvent);
+
+    await expect(serializeInitialData(currentEvent)["a[]"]).rejects.toBe(error);
+  });
+
+  it("sends nothing from a render that can't stream", async () => {
+    queries = { "a[]": () => Promise.resolve(1) };
+    await loadInitialData(currentEvent);
+    expect(serializeInitialData(currentEvent, false)).toEqual({});
+  });
+
+  it("sends nothing when the root can't render on the server", async () => {
+    const consoleError = vi.spyOn(console, "error").mockImplementation(() => {});
+    queries = {
+      "a[]": () => {
+        throw new Error("window is not defined");
+      },
+    };
+    await loadInitialData(currentEvent);
+
+    expect(consoleError).toHaveBeenCalled();
+    expect(serializeInitialData(currentEvent)).toEqual({});
+  });
+});
diff --git a/packages/start/src/server/spa/initial-data.ts b/packages/start/src/server/spa/initial-data.ts
new file mode 100644
index 000000000..9f92eb99d
--- /dev/null
+++ b/packages/start/src/server/spa/initial-data.ts
@@ -0,0 +1,95 @@
+import { sharedConfig } from "solid-js";
+import { getRequestEvent, renderToString } from "solid-js/web";
+
+import { createRoutes } from "../../router.tsx";
+import type { PageEvent } from "../types.ts";
+
+const BODY_HEADERS = new Set(["content-type", "content-length", "content-encoding"]);
+const initialData = new WeakMap<PageEvent, [key: string, value: Promise<unknown>][]>();
+let App: typeof import("solid-start:app").default | undefined;
+
+/**
+ * Runs the route `preload`s for the requested page and keeps the promises of
+ * their queries, so the HTML shell can stream the results to the client.
+ *
+ * This is the same pass single-flight mutations use: with
+ * `event.router.dataOnly` set, the router runs the matched routes' `preload`s
+ * without rendering any page, and `query` stores each call in
+ * `event.router.data`. In SPA builds the server routes have no page components
+ * at all, only their `preload`s.
+ */
+export async function loadInitialData(event: PageEvent): Promise<void> {
+  App ||= (await import("solid-start:app")).default;
+  const router = ((event as any).router ||= {});
+  event.routes = createRoutes();
+  router.dataOnly = true;
+  try {
+    renderToString(() => {
+      (sharedConfig.context as any).event = event;
+      return App!({});
+    });
+  } catch (error) {
+    // The root is written for the browser in SPA mode. If it can't render on
+    // the server, the client fetches its data as usual.
+    console.error(error);
+  }
+  const data: Record<string, unknown> | undefined = router.data;
+  delete router.dataOnly;
+  delete router.data;
+  if (!data) return;
+
+  const entries: [string, Promise<unknown>][] = [];
+  for (const key in data) {
+    if (data[key] === undefined) continue;
+    const promise = Promise.resolve(data[key]).then(
+      value => handleResponse(event, value),
+      async error => {
+        const value = await handleResponse(event, error);
+        // A thrown redirect ends the page, so there is no error to show.
+        if (!event.response.headers.has("Location")) throw value;
+      },
+    );
+    // Serialization reads the rejection; until the shell renders, nothing does.
+    promise.catch(() => {});
+    entries.push([key, promise]);
+  }
+  initialData.set(event, entries);
+}
+
+/**
+ * Streams the query results collected by `loadInitialData` into `_$HY.r`,
+ * where the router's `query` looks for serialized data. It has to render under
+ * `<Hydration>`, because Solid skips serialization inside `<NoHydration>`.
+ */
+export function InitialData() {
+  const context = sharedConfig.context as any;
+  // Only a streamed render can send results that settle after the shell.
+  if (!context?.async) return null;
+  const entries = initialData.get(getRequestEvent() as PageEvent);
+  if (entries) {
+    for (const [key, value] of entries) context.serialize(key, value);
+  }
+  return null;
+}
+
+/**
+ * `query` normally applies a returned `Response` itself, but it skips that in
+ * data-only mode. Apply it here the same way: copy its headers to the page
+ * response, turn a `Location` into a redirect of the page, and send the body
+ * of a `json()` response instead of the response. The body headers describe
+ * the query's response, not the page, so they stay behind.
+ */
+async function handleResponse(event: PageEvent, value: unknown): Promise<unknown> {
+  if (!(value instanceof Response)) return value;
+  for (const [key, header] of value.headers) {
+    if (BODY_HEADERS.has(key)) continue;
+    if (key === "set-cookie") event.response.headers.append(key, header);
+    else event.response.headers.set(key, header);
+  }
+  if (value.headers.has("Location")) {
+    event.response.status = value.status;
+    return undefined;
+  }
+  const customBody = (value as Response & { customBody?: () => unknown }).customBody;
+  return customBody ? await customBody() : value;
+}