From fe5be7bdeae75f3546aa22b5f346022335f4ae9e Mon Sep 17 00:00:00 2001
From: "Alexis H. Munsayac" <alexis.munsayac@gmail.com>
Date: Mon, 19 Oct 2026 11:20:35 +0800
Subject: [PATCH] feat(start): add start.clientSetup to run client code before
 hydrate

- The generated client entry imports the configured module ahead of the
  app, so it runs before hydrate() in SSR mode and before render() in
  client mode.
- A top-level await in the module delays hydrate()/render() until it
  settles.
- It is a static import, so the app stays in the entry chunk and the
  server still preloads its chunks and links its CSS.
- The module joins the dep-scan entries.
- An authored entry-client together with the option is a config error.
- The README start options list now also names `instrument`.

Closes #419.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
---
 .changeset/start-client-setup.md          |   7 +
 README.md                                 |  36 ++-
 examples/start-ssr/src/ClientSetupApp.tsx |  16 ++
 examples/start-ssr/src/client-setup.ts    |  32 +++
 examples/start-ssr/test/run.mjs           | 277 +++++++++++++++++++++-
 examples/start-ssr/vite.config.ts         |   9 +
 src/ssr/index.ts                          |  59 ++++-
 7 files changed, 433 insertions(+), 3 deletions(-)
 create mode 100644 .changeset/start-client-setup.md
 create mode 100644 examples/start-ssr/src/ClientSetupApp.tsx
 create mode 100644 examples/start-ssr/src/client-setup.ts

diff --git a/.changeset/start-client-setup.md b/.changeset/start-client-setup.md
new file mode 100644
index 0000000..3e203da
--- /dev/null
+++ b/.changeset/start-client-setup.md
@@ -0,0 +1,7 @@
+---
+'@solidjs/vite-plugin': patch
+---
+
+New `start.clientSetup` option: a client module the generated client entry runs before it hydrates or mounts the app. Use it to install a server-function transport wrapper, a `vite:preloadError` listener, or an error reporter before the first render, without writing your own `entry-client` / `entry-server` pair. The module may use top-level `await`, and `hydrate()` / `render()` waits for it. Combining it with an authored `entry-client` is a config error.
+
+The start options list in the README now also names `instrument`.
diff --git a/README.md b/README.md
index 74508fc..c3fdfea 100644
--- a/README.md
+++ b/README.md
@@ -230,7 +230,8 @@ same server functions.
 The object form carries the options (`start: true` is pure sugar for
 `start: {}` — both mean the identical start mode with defaults, and
 `false`/absent means off): `app`, `document`, `entryServer`, `entryClient`,
-`middleware`, `setup`, `renderMode`, `env`, `devtools`, `errorBoundary`,
+`middleware`, `setup`, `instrument`, `clientSetup`, `renderMode`, `env`,
+`devtools`, `errorBoundary`,
 `css`, `external`, `node`, all documented below.
 
 Install `@solidjs/start-devtools` as a development dependency to add the
@@ -556,6 +557,39 @@ instrument.mjs` dance. The module may be async and needs no exports; the
 server build must keep code splitting on (the default), since inlining
 dynamic imports would hoist the handler graph back above the instrument.
 
+**`clientSetup`** points at a client module that the generated client entry
+runs before it hydrates (SSR mode) or mounts (client mode) the app. Use it
+for browser setup that must be in place before the first render:
+
+- a server-function transport wrapper or request-header hook,
+- a `vite:preloadError` listener,
+- an error reporter's `init()`.
+
+```ts
+// vite.config.ts
+solid({ start: { clientSetup: './src/client-setup.ts' }, ssr: true });
+
+// src/client-setup.ts
+window.addEventListener('vite:preloadError', () => window.location.reload());
+```
+
+How it runs:
+
+- The generated entry imports the module for its side effects, ahead of the
+  app. A synchronous module finishes before the app's modules evaluate.
+- The module may use top-level `await`. `hydrate()` / `render()` waits for
+  it to settle. The app's modules may evaluate while it waits, but nothing
+  renders.
+- Because it can wait, it can read a global that a classic `<script>` in
+  `<body>` defines: await `DOMContentLoaded` first.
+- It stays in the entry's static module graph, so the build preloads the
+  app's chunks and links its stylesheets as before.
+- Editing it in dev reloads the page.
+
+The module needs no exports. It only applies to a generated client entry.
+An authored `entry-client` can run its own code before `hydrate()`, so
+configuring both is an error.
+
 **`renderMode`** — how a page render becomes a response body: `'stream'`
 (the default) or `'async'`.
 
diff --git a/examples/start-ssr/src/ClientSetupApp.tsx b/examples/start-ssr/src/ClientSetupApp.tsx
new file mode 100644
index 0000000..e833b12
--- /dev/null
+++ b/examples/start-ssr/src/ClientSetupApp.tsx
@@ -0,0 +1,16 @@
+// App root for the client-setup mode (SSR_CLIENT_SETUP=1): wraps the real
+// App and records, in the register src/client-setup.ts creates, when this
+// module evaluated and whether the setup module had settled by the time the
+// app rendered during hydration.
+import { isServer } from '@solidjs/web';
+import App from './App';
+
+if (!isServer) globalThis.__solidClientSetup?.order.push('app:module');
+
+export default function ClientSetupApp() {
+  if (!isServer) {
+    const state = globalThis.__solidClientSetup;
+    state?.order.push(`app:render(setupDone:${state.done})`);
+  }
+  return <App />;
+}
diff --git a/examples/start-ssr/src/client-setup.ts b/examples/start-ssr/src/client-setup.ts
new file mode 100644
index 0000000..21c03de
--- /dev/null
+++ b/examples/start-ssr/src/client-setup.ts
@@ -0,0 +1,32 @@
+// `start.clientSetup` (SSR_CLIENT_SETUP=1, client-setup mode): the module
+// the generated client entry runs before `hydrate()`. This fake proves the
+// contract without a real transport wrapper:
+// - it starts FIRST: the ordering register it creates is empty, so nothing
+//   from the app graph (src/ClientSetupApp.tsx appends at its module top
+//   level) has evaluated yet,
+// - `hydrate()` waits for it: real async work here (a timer) finishes
+//   before the app renders, so ClientSetupApp finds `done` true when it
+//   renders during hydration,
+// - `marker` is what the HMR check edits on disk: the module has no accept
+//   boundary, so an edit must reload the page with the new value.
+declare global {
+  // eslint-disable-next-line no-var
+  var __solidClientSetup:
+    | { order: string[]; done: boolean; evaluations: number; marker: string }
+    | undefined;
+}
+
+const state = (globalThis.__solidClientSetup ??= {
+  order: [],
+  done: false,
+  evaluations: 0,
+  marker: '',
+});
+state.evaluations++;
+state.marker = 'client-setup-v1';
+state.order.push(`setup:start(before:${state.order.length})`);
+await new Promise((resolve) => setTimeout(resolve, 50));
+state.order.push('setup:done');
+state.done = true;
+
+export {};
diff --git a/examples/start-ssr/test/run.mjs b/examples/start-ssr/test/run.mjs
index d20091a..3fc7cd7 100644
--- a/examples/start-ssr/test/run.mjs
+++ b/examples/start-ssr/test/run.mjs
@@ -156,6 +156,12 @@
 //     everything else through handleRequest with `nativeEvent`, PORT/HOST,
 //     the `listener` export mountable — while server.js stays byte-identical
 //     and nothing is emitted without the option (see runNodeMode).
+//   - `start.clientSetup` (client-setup mode, SSR_CLIENT_SETUP=1): the
+//     generated client entry imports src/client-setup.ts ahead of the app
+//     in both start modes, and in dev and prod the browser runs it before
+//     the app graph and finishes its top-level await before hydrate(); an
+//     edit reloads the page; an authored entry-client with the option is a
+//     config error (see runClientSetupMode).
 //   - `performanceTracks` (on by default): under dev serve the generated and
 //     authored client entries import the plugin's virtual module ahead of
 //     everything else, the served module calls enablePerformanceTracks(),
@@ -167,7 +173,7 @@
 //
 // Requires the plugin built (pnpm build at the repo root) and Google Chrome.
 // Usage: node test/run.mjs
-// [dev|prod|document|css-filter|entries|endpoint|configure|no-middleware|middleware|preview|render-mode|nonce|base|builder-order|builder-prepare|extra-input|file-names|babel-hmr|frames|external|observe|perf-tracks|detect|vitest|node]
+// [dev|prod|document|css-filter|entries|endpoint|configure|no-middleware|middleware|preview|render-mode|nonce|base|builder-order|builder-prepare|extra-input|file-names|babel-hmr|frames|external|observe|perf-tracks|detect|vitest|node|client-setup]
 // (default: all)
 
 import { spawn, execSync, execFileSync } from 'node:child_process';
@@ -6825,6 +6831,273 @@ async function runNonceMode() {
   }
 }
 
+// `start.clientSetup` (SSR_CLIENT_SETUP=1, src/client-setup.ts wrapped by
+// src/ClientSetupApp.tsx): the generated client entry runs the setup module
+// before hydrate(), in dev and in a build. What must hold:
+// - codegen: the entry imports the module ahead of the app and of the
+//   hydrate()/render() call, in both start modes, and without the option
+//   the entry carries no such import,
+// - config: an authored entry-client together with the option is an error,
+//   and so is a missing file,
+// - browser (dev and prod): the setup module starts before the app graph
+//   evaluates, hydrate() waits for its top-level await, it runs once, and
+//   hydration stays clean and interactive,
+// - dev: editing the module reloads the page with the new code (it has no
+//   HMR accept boundary, and neither does the entry).
+async function runClientSetupMode() {
+  const mode = 'client-setup';
+  console.log(`\n=== ${mode.toUpperCase()} ===`);
+  const devPort = 3187;
+  const prodPort = 3188;
+  const setupFile = path.join(exampleDir, 'src/client-setup.ts');
+  const setupSource = readFileSync(setupFile, 'utf-8');
+  const env = { ...process.env, SSR_CLIENT_SETUP: '1', SSR_DEVTOOLS: '0' };
+  const ENTRY = 'virtual:solid-ssr-entry-client.tsx';
+  const loadEntry = async (server) => {
+    const loaded = await server.environments.client.pluginContainer.load(ENTRY);
+    return (typeof loaded === 'string' ? loaded : loaded?.code) || '';
+  };
+  const { default: solidPlugin } = await import('@solidjs/vite-plugin');
+  const inlineServer = (options) =>
+    createServer({
+      root: exampleDir,
+      configFile: false,
+      logLevel: 'silent',
+      plugins: [solidPlugin(options)],
+      server: { middlewareMode: true },
+    });
+
+  // ---- Codegen and config validation (in process, no browser) ----------
+  let probe;
+  try {
+    for (const ssr of [true, false]) {
+      const phase = ssr ? 'codegen-ssr' : 'codegen-client';
+      probe = await inlineServer({
+        ssr,
+        start: { clientSetup: './src/client-setup.ts', devtools: false },
+      });
+      const code = await loadEntry(probe);
+      const setupAt = code.indexOf('/src/client-setup.ts');
+      const appAt = code.indexOf('import App from');
+      const callAt = code.indexOf(ssr ? 'hydrate(() =>' : 'render(() =>');
+      record(
+        mode,
+        phase,
+        `generated entry imports the setup module before the app and ${ssr ? 'hydrate' : 'render'}()`,
+        setupAt !== -1 && appAt !== -1 && callAt !== -1 && setupAt < appAt && setupAt < callAt,
+        code.slice(0, 600),
+      );
+      record(
+        mode,
+        phase,
+        'the setup module is a static side-effect import (no dynamic import)',
+        /^import\s+"[^"]*\/src\/client-setup\.ts";$/m.test(code) && !code.includes('import('),
+        code.slice(0, 600),
+      );
+      await probe.close();
+      probe = await inlineServer({ ssr, start: { devtools: false } });
+      const plain = await loadEntry(probe);
+      record(
+        mode,
+        phase,
+        'without the option the entry has no setup import',
+        plain.length > 0 && !plain.includes('client-setup'),
+        plain.slice(0, 400),
+      );
+      await probe.close();
+      probe = undefined;
+    }
+
+    const configError = async (start) => {
+      try {
+        const server = await inlineServer({ ssr: true, start });
+        await server.close();
+        return '';
+      } catch (e) {
+        return String(e?.message ?? e);
+      }
+    };
+    const authored = await configError({
+      clientSetup: './src/client-setup.ts',
+      entryServer: './src/api.ts',
+      entryClient: './src/api.ts',
+    });
+    record(
+      mode,
+      'config',
+      'an authored entry-client together with clientSetup is an error',
+      authored.includes('start.clientSetup only applies to a generated client entry'),
+      authored || 'no error',
+    );
+    const missing = await configError({ clientSetup: './src/no-such-setup.ts' });
+    record(
+      mode,
+      'config',
+      'a missing clientSetup file is an error',
+      missing.includes('start.clientSetup does not exist'),
+      missing || 'no error',
+    );
+  } catch (e) {
+    record(mode, 'codegen', 'codegen checks completed', false, String(e?.stack ?? e));
+  } finally {
+    await probe?.close();
+  }
+
+  // ---- Browser: dev, then the build -------------------------------------
+  const browserChecks = async (phase, cdp, origin) => {
+    cdp.exceptions.length = 0;
+    await cdp.send('Page.navigate', { url: origin + '/' });
+    await cdp.waitFor('document.readyState === "complete"');
+    await cdp.waitFor('window.__solidClientSetup?.order.some((s) => s.startsWith("app:render"))');
+    await new Promise((r) => setTimeout(r, 500));
+    const state = await cdp.evalJs('JSON.stringify(window.__solidClientSetup ?? null)');
+    const parsed = state ? JSON.parse(state) : null;
+    const order = parsed?.order ?? [];
+    record(
+      mode,
+      phase,
+      'setup module starts before the app graph evaluates',
+      order[0] === 'setup:start(before:0)' &&
+        order.indexOf('app:module') > order.indexOf('setup:start(before:0)'),
+      state,
+    );
+    const doneAt = order.indexOf('setup:done');
+    const renderAt = order.findIndex((s) => s.startsWith('app:render'));
+    record(
+      mode,
+      phase,
+      'hydrate() waits for the setup module (async top-level await settled first)',
+      doneAt !== -1 &&
+        renderAt > doneAt &&
+        order.every((s) => !s.startsWith('app:render') || s === 'app:render(setupDone:true)'),
+      state,
+    );
+    record(mode, phase, 'setup module evaluated once', parsed?.evaluations === 1, state);
+    const hydrationErrs = cdp.exceptions.filter((e) => /hydrat|mismatch/i.test(e));
+    record(
+      mode,
+      phase,
+      'clean hydration (no hydration console errors)',
+      hydrationErrs.length === 0,
+      hydrationErrs.join(' | '),
+    );
+    await cdp.evalJs('document.querySelector("#increment").click()');
+    record(
+      mode,
+      phase,
+      'hydrated app is interactive (counter)',
+      await cdp.waitFor('document.querySelector("#count")?.textContent === "1"'),
+    );
+  };
+
+  const withChrome = async (run) => {
+    const chrome = startProcess(CHROME, [
+      '--headless=new',
+      `--remote-debugging-port=${CDP_PORT}`,
+      `--user-data-dir=/tmp/start-ssr-chrome-${mode}`,
+      '--no-first-run',
+      '--disable-extensions',
+      'about:blank',
+    ]);
+    const cdp = await connectChrome();
+    try {
+      await run(cdp);
+    } finally {
+      cdp.close();
+      const exited = new Promise((r) => chrome.once('exit', r));
+      try {
+        process.kill(-chrome.pid, 'SIGTERM');
+      } catch {}
+      await Promise.race([exited, new Promise((r) => setTimeout(r, 3000))]);
+      try {
+        rmSync(`/tmp/start-ssr-chrome-${mode}`, { recursive: true, force: true, maxRetries: 5 });
+      } catch {}
+    }
+  };
+
+  let server;
+  let serverLog = '';
+  const captureLog = (child) => {
+    child.stdout.on('data', (d) => (serverLog += d));
+    child.stderr.on('data', (d) => (serverLog += d));
+  };
+  try {
+    const devOrigin = `http://localhost:${devPort}`;
+    server = startProcess('pnpm', ['exec', 'vite', '--port', String(devPort), '--strictPort'], {
+      cwd: exampleDir,
+      env,
+    });
+    captureLog(server);
+    await waitForHttp(devOrigin + '/src/api.ts', 30000);
+    await withChrome(async (cdp) => {
+      await browserChecks('dev', cdp, devOrigin);
+      // The module has no accept boundary and neither has the generated
+      // entry, so an edit must reload the page and run the new code.
+      writeFileSync(setupFile, setupSource.replace("'client-setup-v1'", "'client-setup-v2'"));
+      const reloaded = await cdp.waitFor(
+        'window.__solidClientSetup?.marker === "client-setup-v2" && window.__solidClientSetup.done',
+        15000,
+      );
+      const after = await cdp.evalJs('JSON.stringify(window.__solidClientSetup ?? null)');
+      record(
+        mode,
+        'dev',
+        'editing the setup module reloads the page with the new code (setup runs again first)',
+        // evaluations === 1: a fresh page, not a hot update into the old
+        // one (whose global register would count a second evaluation).
+        reloaded &&
+          JSON.parse(after)?.evaluations === 1 &&
+          JSON.parse(after)?.order[0] === 'setup:start(before:0)' &&
+          JSON.parse(after)?.order.includes('app:render(setupDone:true)'),
+        after,
+      );
+    });
+    writeFileSync(setupFile, setupSource);
+    try {
+      process.kill(-server.pid, 'SIGTERM');
+    } catch {}
+    server = undefined;
+
+    console.log('  building…');
+    execSync('pnpm run build', { cwd: exampleDir, stdio: 'pipe', env });
+    const prodOrigin = `http://localhost:${prodPort}`;
+    server = startProcess('node', ['server.js'], {
+      cwd: exampleDir,
+      env: { ...env, PORT: String(prodPort), NODE_ENV: 'production' },
+    });
+    captureLog(server);
+    await waitForHttp(prodOrigin + '/', 30000, { headers: { accept: 'text/html' } });
+    const { html } = await fetchStreamed(prodOrigin + '/');
+    record(
+      mode,
+      'prod',
+      "the app's stylesheet is still linked (the app stays in the entry's static graph)",
+      /<link[^>]+rel="stylesheet"[^>]+\.css"/.test(html),
+      html.slice(0, 800),
+    );
+    await withChrome((cdp) => browserChecks('prod', cdp, prodOrigin));
+  } catch (e) {
+    record(
+      mode,
+      'run',
+      'mode completed',
+      false,
+      String(e) + (serverLog ? `\nserver: ${serverLog.slice(-2000)}` : ''),
+    );
+  } finally {
+    writeFileSync(setupFile, setupSource);
+    if (server) {
+      try {
+        process.kill(-server.pid, 'SIGTERM');
+      } catch {}
+    }
+    // Leave dist in the standard state for anyone poking at it.
+    try {
+      execSync('pnpm run build', { cwd: exampleDir, stdio: 'pipe' });
+    } catch {}
+  }
+}
+
 const ALL_MODES = [
   'dev',
   'prod',
@@ -6851,6 +7124,7 @@ const ALL_MODES = [
   'detect',
   'vitest',
   'node',
+  'client-setup',
 ];
 const arg = process.argv[2];
 const modes = ALL_MODES.includes(arg) ? [arg] : ALL_MODES;
@@ -6879,6 +7153,7 @@ for (const mode of modes) {
   else if (mode === 'perf-tracks') await runPerfTracksMode();
   else if (mode === 'vitest') await runVitestMode();
   else if (mode === 'node') await runNodeMode();
+  else if (mode === 'client-setup') await runClientSetupMode();
   else await runDetectMode();
 }
 
diff --git a/examples/start-ssr/vite.config.ts b/examples/start-ssr/vite.config.ts
index 789d671..a0d01fb 100644
--- a/examples/start-ssr/vite.config.ts
+++ b/examples/start-ssr/vite.config.ts
@@ -31,6 +31,9 @@ import solidPlugin from '@solidjs/vite-plugin';
 //   (middleware mode): the module awaited to completion before the handler
 //   graph loads — the APM/OpenTelemetry seam; middleware.ts reports what it
 //   saw at its own load in an `x-instrument` header.
+// - SSR_CLIENT_SETUP=1 wires src/client-setup.ts through `start.clientSetup`
+//   (client-setup mode) and wraps App in src/ClientSetupApp.tsx, which
+//   records whether the setup module settled before hydration rendered.
 // - SOLID_OBSERVE=1 (observe mode) turns on `observe`: the `observe` export
 //   condition everywhere and the compiler's `sourceNames` for both
 //   postures, so the built server AND client bundles carry component labels.
@@ -231,6 +234,12 @@ export default defineConfig({
               // component to render (the TanStack-style async router seam).
               ...(process.env.SSR_SETUP ? { setup: './src/setup.tsx' } : {}),
               ...(process.env.SSR_INSTRUMENT ? { instrument: './src/instrument.ts' } : {}),
+              // SSR_CLIENT_SETUP=1 (client-setup mode): src/client-setup.ts
+              // runs in the browser before the generated entry hydrates;
+              // src/ClientSetupApp.tsx wraps App to record the order.
+              ...(process.env.SSR_CLIENT_SETUP
+                ? { clientSetup: './src/client-setup.ts', app: './src/ClientSetupApp.tsx' }
+                : {}),
               // SSR_RENDER_MODE (render-mode mode): `middleware` → the
               // per-request policy in src/middleware.ts (`event.renderMode`);
               // anything else verbatim (`async`, or an invalid value / a
diff --git a/src/ssr/index.ts b/src/ssr/index.ts
index 6c8a026..b4edb51 100644
--- a/src/ssr/index.ts
+++ b/src/ssr/index.ts
@@ -232,6 +232,31 @@ export interface StartOptions {
    * @default undefined
    */
   setup?: string;
+  /**
+   * Path to a client module (resolved relative to the Vite root) that the
+   * generated client entry runs before it hydrates (SSR mode) or mounts
+   * (client mode) the app. The browser-side seam for setup that must be in
+   * place before the first render: a server-function transport wrapper or
+   * request-header hook, a `vite:preloadError` listener, an error reporter's
+   * `init()`.
+   *
+   * How: the generated entry imports the module for its side effects ahead
+   * of the app, so a synchronous module finishes before the app's own
+   * modules evaluate. The module may be async (top-level `await` is
+   * honored): `hydrate()` / `render()` waits for it to settle, which lets it
+   * wait for the DOM, for example for a global that a classic `<script>` in
+   * `<body>` defines. While it awaits, the app's modules may already
+   * evaluate, but nothing renders. No exports are needed. The module stays
+   * in the entry's static graph, so the build preloads it and the app's
+   * chunks and stylesheets as before. Editing it reloads the page.
+   *
+   * Only meaningful with a generated client entry: an authored
+   * `entry-client` runs its own code before `hydrate()` already, so
+   * configuring both is an error. Applies to both start modes.
+   *
+   * @default undefined
+   */
+  clientSetup?: string;
   /**
    * How the generated handler turns a page render into a response body.
    *
@@ -723,6 +748,8 @@ export function startServe(
   let instrumentPath: string | null = null;
   /** Absolute path of the per-request setup module, when configured (server mode). */
   let setupPath: string | null = null;
+  /** Absolute path of the client setup module run before hydrate/render, when configured. */
+  let clientSetupPath: string | null = null;
   /**
    * `start.renderMode`, resolved at config time: the static mode baked into
    * the handler (server mode only — a documented no-op in client mode,
@@ -1020,6 +1047,15 @@ export function startServe(
       performanceTracks && !isBuild
         ? [`import ${JSON.stringify(PERFORMANCE_TRACKS_CLIENT_ID)};`]
         : [];
+    // `start.clientSetup`: imported for its side effects ahead of the app,
+    // after the dev-only tooling above so its failures reach the overlay.
+    // A static import, not `await import()` like `start.instrument`: a
+    // dynamic import would move the app into a separate chunk the server
+    // neither preloads nor links CSS for. The entry body (hydrate/render)
+    // still waits for an async module's top-level await to settle.
+    const clientSetupImport = clientSetupPath
+      ? [`import ${JSON.stringify(clientSetupPath)};`]
+      : [];
     if (clientMode) {
       // render(), not hydrate(): the shell's body is empty, the app mounts
       // fresh. Client code compiles non-hydratable in client mode, so the
@@ -1029,6 +1065,7 @@ export function startServe(
       return [
         ...performanceTracksImport,
         ...diagnosticsImport,
+        ...clientSetupImport,
         `import { render } from '@solidjs/web';`,
         ...errorBoundaryImport(),
         ...(toolbar ? [`import { DevToolbar } from ${JSON.stringify(DEVTOOLS_PACKAGE)};`] : []),
@@ -1046,6 +1083,7 @@ export function startServe(
     return [
       ...performanceTracksImport,
       ...diagnosticsImport,
+      ...clientSetupImport,
       `import { hydrate } from '@solidjs/web';`,
       ...(toolbar ? [`import { DevToolbar } from ${JSON.stringify(DEVTOOLS_PACKAGE)};`] : []),
       ...(serverComponents
@@ -1711,6 +1749,19 @@ export function startServe(
               `(remove start.setup or the authored entry): ${options.setup}`,
           );
         }
+        // Both modes: the generated client entry hydrates or mounts, and
+        // the setup module runs ahead of either.
+        clientSetupPath = options.clientSetup
+          ? path.resolve(root, normalizeUserPath(root, options.clientSetup, 'clientSetup'))
+          : null;
+        if (clientSetupPath && entries.entryClient !== ENTRY_CLIENT_ID) {
+          // An authored entry-client runs its own code before hydrate().
+          throw new Error(
+            '[@solidjs/vite-plugin] start.clientSetup only applies to a generated client entry: ' +
+              'your entry-client runs before hydrate() already, so import your setup module ' +
+              `there instead (remove start.clientSetup or the authored entry): ${options.clientSetup}`,
+          );
+        }
         // Server-mode only as well: the client-mode shell renders no app,
         // so there is nothing to settle. Validated in every mode though —
         // a typo should not hide behind the `ssr` boolean.
@@ -1759,7 +1810,13 @@ export function startServe(
         // even with an authored client entry; in SSR mode authored entries
         // own the whole graph.)
         const scanEntries = entries.generated
-          ? [entries.app!, ...(entries.document ? [entries.document] : [])]
+          ? [
+              entries.app!,
+              ...(entries.document ? [entries.document] : []),
+              // Its dependencies pre-bundle with the app's, so the first
+              // page load does not trigger a re-optimize and a reload.
+              ...(clientSetupPath ? [clientSetupPath] : []),
+            ]
           : [
               path.resolve(root, entries.entryClient),
               ...(clientMode && entries.document ? [entries.document] : []),