Skip to content

Report ignored client options, never connect on the server - #62

Merged
mmailaender merged 1 commit into
mainfrom
fix/client-options
Oct 14, 2026
Merged

mmailaender merged 1 commit into
mainfrom
fix/client-options

Conversation

@mmailaender

@mmailaender mmailaender commented Oct 12, 2026 •

Copy link
Copy Markdown
Collaborator

Summary

  • Ignored client options are reported. Client options only apply where the shared client is created, like the ConvexReactClient constructor. When setupConvex() or a repeated initConvex() passes options the existing client was not created with, a dev warning now names them. Before, they were dropped silently.
  • No WebSocket during server rendering. The client is always disabled on the server, even if a caller passes disabled: false, and that is decided at runtime instead of by how the bundler resolves esm-env.
  • No API change.
  • Verified: 211 unit tests, svelte-check, lint, and the e2e suite pass (the chat demo tests skip without PUBLIC_CONVEX_URL). The new server-guard test fails against the old initConvex.

Before / after (user code)

// src/hooks.ts
initConvex(PUBLIC_CONVEX_URL);

// src/routes/+layout.svelte
setupConvex(PUBLIC_CONVEX_URL, { expectAuth: true });
// Before: expectAuth silently does nothing.
// After: dev warning, "setupConvex(): the Convex client already exists, so these
// options are ignored: expectAuth. Client options only take effect where the
// client is created, e.g. initConvex(url, options) in src/hooks.ts."

The fix in user code is to pass the options where the client is created: initConvex(PUBLIC_CONVEX_URL, { expectAuth: true }).

Why

Silent option dropping. convex-svelte creates the shared client in two places:

  • initConvex(), needed in hooks.ts before loads and transport decoding run
  • setupConvex(), in the root layout

The second call reuses the client and dropped its options without a word. This happens in practice: wrappers like @mmailaender/convex-better-auth-svelte pass client options through to setupConvex(), and the get-convex/better-auth SvelteKit guide recommended createSvelteAuthClient({ options: { expectAuth: true } }). In apps that also call initConvex(), that had no effect.

React avoids the problem by design: the user creates the client once with all options and the provider only receives it. Svelte can't simply copy that, because SvelteKit loads need the client before any component exists. Reporting the conflict keeps the same rule ("options apply where the client is created") without an API change.

WebSocket on the server. setupConvex() computed { disabled: !BROWSER, ...options }. Two problems:

  • A caller's disabled: false won. @mmailaender/convex-better-auth-svelte passed exactly that, so in apps without initConvex() the client it created during SSR opened a WebSocket on the server that lived as long as the process. Measured in SvelteKit 2 and 3 dev and production builds; fixed in the wrapper in fix(svelte): stop forcing the Convex client on during SSR mmailaender/convex-better-auth-svelte#52.
  • BROWSER is fixed at build time from package export conditions. initConvex() already used a runtime check (typeof document); now both do.

What

  • internal/client_options.ts (new):
    • withServerDisabled(options) always sets disabled: true on the server.
    • differingOptions(created, requested) compares only primitive values and ignores disabled. Functions and objects such as logger or webSocketConstructor get a new identity on every hot reload, so comparing them would only produce noise.
    • warnIgnoredOptions() only warns in dev and in the browser, where the options matter. On the server it would log on every request.
  • internal/singleton.ts: setSingleton(url, client, options) stores the creation options. getSingletonOptions() returns them, and they reset with the client.
  • setupConvex() / initConvex(): create the client with withServerDisabled(), store the options, and warn when an existing client is reused with different ones.

How

  • Comparison: only keys present in the later call are compared against the creation options. setupConvex(url) with no options never warns, and neither does hot reload with unchanged options.
  • Tests:
    • client_options.spec.ts: server vs browser disabled, which options count as different, and that warnings appear only in dev in the browser.
    • sveltekit/client.spec.ts: initConvex(url, { disabled: false }) on the server still creates a disabled client. This test fails against the old code.
  • Docs: Svelte docs: convexLoad lifecycle, hydration handle and client setup convex-backend#571 explains where client options go, plus the expectAuth limitations.

- setupConvex() / initConvex() create the client with disabled forced on
  the server (typeof document at runtime), even if a caller passes
  disabled: false. Previously setupConvex derived it from esm-env's
  build-time BROWSER and let callers override it, so a caller passing
  disabled: false opened a WebSocket during server rendering.
- The singleton remembers the options it was created with. When
  setupConvex() or a repeated initConvex() passes different primitive
  options (e.g. expectAuth in the layout while initConvex() in hooks.ts
  created the client), a dev warning in the browser names them instead
  of dropping them silently. Like the ConvexReactClient constructor,
  options only apply where the client is created.
@mmailaender
mmailaender force-pushed the fix/convexload-single-subscription branch from c784afb to 5afe992 Compare October 12, 2026 15:27
@vercel

vercel Bot commented Oct 12, 2026 •

Copy link
Copy Markdown

The latest updates on your projects. Learn more about Vercel for GitHub.

Project Deployment Actions Updated
convex-svelte Ready Ready Preview Oct 12, 2026 3:59pm UTC

Request Review

@mikecann mikecann left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks Micha, looks good! Really nice that the server client can never open a WebSocket now.

@pkg-pr-new

pkg-pr-new Bot commented Oct 14, 2026

Copy link
Copy Markdown

commit: b80b627

@mmailaender
mmailaender merged commit d57d7ee into main Oct 14, 2026
5 checks passed

This branch was successfully deployed

1 active deployment
Preview — 77fe5054 Deployed Oct 12, 2026 by vercel[bot]
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants