add experimental server function compilation hoisted from solid-start

Hoists the "use server" directive compiler from SolidStart 2.0 alpha into
src/server-functions, exposed via the serverFunctions option on the main
plugin (which now returns Plugin[]) or the standalone serverFunctions()
export for meta-frameworks that manage plugin ordering. The runtime ABI is
bring-your-own through options.runtime module specifiers; a plain-Vite
fixture (examples/server-functions) proves the compiler standalone with a
minimal runtime built on @solidjs/web/serialization. Client-only referenced
modules are fed to the server manifest across two-invocation builds via
dist/client/.vite/solid-server-functions.json, and function IDs hash
project-relative paths for reproducible builds.

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

Author: ryansolid

.changeset/server-functions-compiler.md

@@ -0,0 +1,36 @@
+---
+'vite-plugin-solid': patch
+---
+
+`"use server"` server function compilation (experimental), hoisted from
+SolidStart 2.0 alpha's directive compiler. Enable it through the new
+`serverFunctions` option on the main plugin, or compose the standalone
+`serverFunctions(options)` export for full control over plugin ordering
+(e.g. relative to a file-system router). To support emitting the transform
+sub-plugins, `solid()` now returns `Plugin[]` instead of a single `Plugin` —
+transparent at the Vite config level, where plugin arrays flatten.
+
+- Both directive forms are supported: function-level (first statement of a
+  function body) and module-level (every export becomes a server function).
+  Server builds register the original function via `createServerReference`
+  and reference it with `cloneServerReference`; client builds compile to
+  ID-only references with the function bodies — and everything only they
+  used, including module-level server-only code — removed.
+- The runtime is bring-your-own: compiled output imports the two reference
+  functions from the module specifiers in `options.runtime.{server,client}`,
+  so SolidStart's runtime, or a minimal custom one (see the
+  `examples/server-functions` fixture built on `@solidjs/web/serialization`), can
+  satisfy the ABI. Works identically under the Babel and native compiler
+  backends since the transform runs as its own pre-pass (server functions
+  live in plain `.ts`/`.js` files the JSX pass never sees).
+- A virtual manifest module (default `virtual:solid-server-function-manifest`)
+  imports every module containing server functions; import it for side
+  effects in the server entry so registrations exist before dispatch. Server
+  functions referenced only from client-side code (e.g. event handlers,
+  which the SSR JSX compile drops) are discovered by the client transform
+  and fed into the server manifest — across the classic two-invocation build
+  via `dist/client/.vite/solid-server-functions.json`.
+- Divergences from the SolidStart source: function IDs hash the
+  project-relative path (reproducible across machines while still agreeing
+  between the client and server builds) and modules without the directive
+  substring skip the Babel parse entirely.

examples/server-functions/package.json

@@ -0,0 +1,21 @@
+{
+  "name": "example-server-functions",
+  "private": "true",
+  "type": "module",
+  "scripts": {
+    "dev": "node server.js",
+    "build": "npm run build:client && npm run build:server",
+    "build:client": "vite build --outDir dist/client",
+    "build:server": "vite build --ssr src/entry-server.tsx --outDir dist/server",
+    "serve": "NODE_ENV=production node server.js",
+    "test": "node test/run.mjs"
+  },
+  "devDependencies": {
+    "vite": "^7.0.0",
+    "vite-plugin-solid": "workspace:*"
+  },
+  "dependencies": {
+    "solid-js": "catalog:",
+    "@solidjs/web": "catalog:"
+  }
+}

examples/server-functions/server.js

@@ -0,0 +1,139 @@
+import { createServer as createHttpServer } from 'node:http';
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import path from 'node:path';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const isProduction = process.env.NODE_ENV === 'production';
+const port = process.env.PORT || 3000;
+
+function getClientEntry() {
+  if (!isProduction) return '/src/entry-client.tsx';
+  const manifest = JSON.parse(
+    readFileSync(path.resolve(__dirname, 'dist/client/.vite/manifest.json'), 'utf-8'),
+  );
+  const entry = manifest['src/entry-client.tsx'];
+  return '/' + entry.file;
+}
+
+function readBody(req) {
+  return new Promise((resolve, reject) => {
+    const chunks = [];
+    req.on('data', (chunk) => chunks.push(chunk));
+    req.on('end', () => resolve(Buffer.concat(chunks)));
+    req.on('error', reject);
+  });
+}
+
+async function start() {
+  let vite;
+  let devHeadInjection = '';
+
+  const loadEntryServer = () =>
+    isProduction
+      ? import('./dist/server/entry-server.js')
+      : vite.ssrLoadModule('/src/entry-server.tsx');
+
+  const server = createHttpServer(async (req, res) => {
+    const url = req.url || '/';
+
+    try {
+      // Server function endpoint: adapt the node request to a web Request and
+      // hand it to the runtime's handler inside the SSR module graph (so it
+      // shares the registry with the rendered app).
+      if (url.startsWith('/_server')) {
+        const { handleServerFunction } = await loadEntryServer();
+        const body = await readBody(req);
+        const request = new Request(`http://localhost:${port}${url}`, {
+          method: req.method,
+          headers: req.headers,
+          body: req.method === 'GET' || req.method === 'HEAD' ? undefined : body,
+        });
+        const response = await handleServerFunction(request);
+        res.statusCode = response.status;
+        response.headers.forEach((value, key) => res.setHeader(key, value));
+        res.end(await response.text());
+        return;
+      }
+
+      if (!isProduction) {
+        const handled = await new Promise((resolve) => {
+          vite.middlewares(req, res, () => resolve(false));
+        });
+        if (handled !== false) return;
+        if (!req.headers.accept?.includes('text/html')) {
+          if (!res.headersSent) {
+            res.statusCode = 404;
+            res.end();
+          }
+          return;
+        }
+      }
+
+      if (isProduction && url !== '/') {
+        const filePath = path.resolve(__dirname, 'dist/client' + url);
+        try {
+          const content = readFileSync(filePath);
+          const ext = path.extname(url);
+          const types = {
+            '.js': 'application/javascript',
+            '.css': 'text/css',
+            '.html': 'text/html',
+            '.json': 'application/json',
+          };
+          res.setHeader('Content-Type', types[ext] || 'application/octet-stream');
+          res.end(content);
+          return;
+        } catch {
+          // Fall through to SSR
+        }
+      }
+
+      const { render } = await loadEntryServer();
+      const stream = render();
+      const clientEntry = getClientEntry();
+
+      res.setHeader('Content-Type', 'text/html');
+      res.write('<!DOCTYPE html>');
+
+      stream.pipe({
+        write(chunk) {
+          let html = chunk;
+          if (!isProduction && html.includes('</head>')) {
+            html = html.replace('</head>', devHeadInjection + '</head>');
+          }
+          if (isProduction && html.includes('/src/entry-client.tsx')) {
+            html = html.replace('/src/entry-client.tsx', clientEntry);
+          }
+          return res.write(html);
+        },
+        end() {
+          res.end();
+        },
+      });
+    } catch (e) {
+      if (!isProduction) vite.ssrFixStacktrace(e);
+      console.error(e);
+      res.statusCode = 500;
+      res.end(e.message);
+    }
+  });
+
+  if (!isProduction) {
+    const { createServer } = await import('vite');
+    vite = await createServer({
+      server: { middlewareMode: true, hmr: { server } },
+      appType: 'custom',
+    });
+    const { devStylePatch } = await import('vite-plugin-solid');
+    devHeadInjection =
+      `<script>${devStylePatch}</script>` +
+      '<script type="module" src="/@vite/client"></script>';
+  }
+
+  server.listen(port, () => {
+    console.log(`Server running at http://localhost:${port}`);
+  });
+}
+
+start();

examples/server-functions/src/App.tsx

@@ -0,0 +1,49 @@
+import { createSignal } from 'solid-js';
+import { HydrationScript } from '@solidjs/web';
+import { getServerMessage, hasSecret, requestMethod } from './api';
+
+export default function App() {
+  const [message, setMessage] = createSignal('');
+  const [doubled, setDoubled] = createSignal('');
+  const [method, setMethod] = createSignal('');
+  const [secret, setSecret] = createSignal('');
+
+  // Function-level directive inside a component: the compiler hoists the body
+  // to a module-level registration on the server and swaps in a reference on
+  // the client. (Bodies must not close over component scope.)
+  const double = async (n: number) => {
+    'use server';
+    return n * 2;
+  };
+
+  return (
+    <html lang="en">
+      <head>
+        <meta charset="UTF-8" />
+        <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+        <title>Server Functions</title>
+        <HydrationScript />
+      </head>
+      <body>
+        <h1>Server Functions</h1>
+        <button id="call-message" onClick={async () => setMessage(await getServerMessage('client'))}>
+          message
+        </button>
+        <button id="call-double" onClick={async () => setDoubled(String(await double(21)))}>
+          double
+        </button>
+        <button id="call-method" onClick={async () => setMethod(await requestMethod())}>
+          method
+        </button>
+        <button id="call-secret" onClick={async () => setSecret(String(await hasSecret()))}>
+          secret
+        </button>
+        <p id="message">{message()}</p>
+        <p id="doubled">{doubled()}</p>
+        <p id="method">{method()}</p>
+        <p id="secret">{secret()}</p>
+        <script type="module" src="/src/entry-client.tsx" async />
+      </body>
+    </html>
+  );
+}

examples/server-functions/src/api.ts

@@ -0,0 +1,21 @@
+'use server';
+// Module-level directive: every export becomes a server function. The client
+// build of this module is replaced entirely by references — the secret below
+// (and the @solidjs/web import) must never appear in any client asset, which
+// test/run.mjs asserts.
+import { getRequestEvent } from '@solidjs/web';
+
+const SERVER_ONLY_SECRET = 'SERVER-ONLY-SECRET-c81d';
+
+export async function getServerMessage(name: string) {
+  return `hello ${name} from the server`;
+}
+
+export async function hasSecret() {
+  return SERVER_ONLY_SECRET.length > 0;
+}
+
+export async function requestMethod() {
+  const event = getRequestEvent();
+  return event ? event.request.method : 'no-event';
+}

examples/server-functions/src/entry-client.tsx

@@ -0,0 +1,4 @@
+import { hydrate } from '@solidjs/web';
+import App from './App';
+
+hydrate(() => <App />, document);

examples/server-functions/src/entry-server.tsx

@@ -0,0 +1,46 @@
+import { renderToStream } from '@solidjs/web';
+import { provideRequestEvent } from '@solidjs/web/storage';
+import manifest from 'virtual:solid-manifest';
+// Side-effect import: pulls in every module containing server functions so
+// their registrations exist before any /_server request is dispatched (e.g.
+// functions in modules the SSR render itself never imports).
+import 'virtual:solid-server-function-manifest';
+import App from './App';
+import { getServerFunction } from './runtime/server';
+import { deserializeFromText, serializeToText } from './runtime/shared';
+
+export function render() {
+  return renderToStream(() => <App />, { manifest });
+}
+
+/** HTTP endpoint for the prototype runtime: dispatches /_server requests. */
+export async function handleServerFunction(request: Request): Promise<Response> {
+  const id = request.headers.get('x-server-function');
+  if (!id) {
+    return new Response('missing x-server-function header', { status: 400 });
+  }
+
+  let fn: (...args: unknown[]) => unknown;
+  try {
+    fn = getServerFunction(id);
+  } catch (error) {
+    return new Response(String(error), { status: 404 });
+  }
+
+  const body = await request.text();
+  const args = body ? deserializeFromText<unknown[]>(body) : [];
+
+  const event = { request, locals: {} };
+  try {
+    const result = await provideRequestEvent(event as any, () => fn(...args));
+    return new Response(await serializeToText(result), {
+      status: 200,
+      headers: { 'content-type': 'text/plain' },
+    });
+  } catch (error) {
+    return new Response(await serializeToText(error), {
+      status: 500,
+      headers: { 'content-type': 'text/plain', 'x-error': '1' },
+    });
+  }
+}

examples/server-functions/src/runtime/client.ts

@@ -0,0 +1,29 @@
+// Client half of the prototype runtime ABI. The compiled client build calls
+// `cloneServerReference(id)` where a server function was referenced; the
+// function body never reaches this bundle. Calls POST the serialized
+// arguments to the /_server endpoint handled in server.js.
+import { deserializeFromText, serializeToText } from './shared.js';
+
+export function cloneServerReference(id: string) {
+  return async (...args: unknown[]) => {
+    const response = await fetch('/_server', {
+      method: 'POST',
+      headers: {
+        'content-type': 'text/plain',
+        'x-server-function': id,
+      },
+      body: await serializeToText(args),
+    });
+    const result = deserializeFromText<unknown>(await response.text());
+    if (!response.ok) {
+      throw result;
+    }
+    return result;
+  };
+}
+
+// Only ever referenced by server-mode output; present so a misconfigured
+// build fails loudly instead of with a missing-export error.
+export function createServerReference(): never {
+  throw new Error('createServerReference must not be called in the client build');
+}

examples/server-functions/src/runtime/server.ts

@@ -0,0 +1,35 @@
+// Server half of the prototype runtime ABI. The compiled server build calls
+// `createServerReference(id, fn)` for every server function (registering it
+// for HTTP dispatch) and `cloneServerReference(ref)` where the function was
+// referenced — during SSR the original function runs in-process.
+
+export interface ServerFunctionReference {
+  id: string;
+  fn: (...args: any[]) => any;
+}
+
+const registry = new Map<string, ServerFunctionReference['fn']>();
+
+export function createServerReference(
+  id: string,
+  fn: ServerFunctionReference['fn'],
+): ServerFunctionReference {
+  registry.set(id, fn);
+  return { id, fn };
+}
+
+export function cloneServerReference({ id, fn }: ServerFunctionReference) {
+  if (typeof fn !== 'function') {
+    throw new Error(`Export "${id}" from a 'use server' module must be a function`);
+  }
+  return fn;
+}
+
+/** Used by the HTTP handler to dispatch incoming server function calls. */
+export function getServerFunction(id: string): ServerFunctionReference['fn'] {
+  const fn = registry.get(id);
+  if (!fn) {
+    throw new Error(`Unknown server function: ${id}`);
+  }
+  return fn;
+}