Skip to content

Support installing with SvelteKit 3 - #64

Merged
mmailaender merged 3 commits into
mainfrom
fix/sveltekit-3-peer
Oct 14, 2026
Merged

mmailaender merged 3 commits into
mainfrom
fix/sveltekit-3-peer

Conversation

@mmailaender

@mmailaender mmailaender commented Oct 13, 2026 •

Copy link
Copy Markdown
Collaborator

Summary

  • npm couldn't install convex-svelte 0.15.0 with SvelteKit 3. The new optional peer @sveltejs/kit: ^2.12.0 excluded it, and npm treats that as ERESOLVE. The peer range is now ^2.12.0 || ^3.0.0.
  • convexLoadHydration gets an accurate warning on SvelteKit 3. The behavior is unchanged: it embeds nothing there, fail closed.
  • Verified:
    • Unit tests, lint, svelte-check: 207 unit tests pass; lint and svelte-check are clean.
    • npm with SvelteKit 3: the packed branch installs next to SvelteKit 3 without ERESOLVE.
    • 0.15.0 on SvelteKit 3 otherwise: the SvelteKit 3 demo of @mmailaender/convex-better-auth-svelte, which uses initConvex(), the transport and convexLoad in universal and server loads, passes all 28 e2e tests against 0.15.0.

Before / after (user code)

npm install convex-svelte   # in a SvelteKit 3 app
# Before: npm error ERESOLVE ... peerOptional @sveltejs/kit@"^2.12.0" from convex-svelte@0.15.0
# After: installs

Why

Install. The optional @sveltejs/kit peer was added in 0.15.0 for $app/state, which needs 2.12 or later. SvelteKit 3 came out at the same time, and npm rejects mismatched optional peers that are installed. pnpm only warns, so this went unnoticed.

convexLoadHydration. It needs to know whether convexLoad runs in a universal load. SvelteKit 2.56+ exposes that as is_in_universal_load in its request store. In SvelteKit 3:

  • The flag is gone. Universal loads run with exactly the same request state as server loads (runtime/server/page/load_data.js).
  • Remote functions changed too. They now serialize every top-level awaited query() (is_in_remote_query) instead of checking for universal loads.

So the handle can't tell the two kinds of load apart, and correctly embeds nothing. But its warning asked for "SvelteKit 2.56 or later", which is misleading on SvelteKit 3.

What

  • package.json: "@sveltejs/kit": "^2.12.0 || ^3.0.0" (still optional).
  • hydration-server.ts: if the request state has SvelteKit 3's is_in_remote_query but no universal-load marker, the one-time warning explains that the handle has no effect there, what that means (universal loads re-run in the browser before auth), and the fix: move convexLoad() calls that need auth into +page.server.ts / +layout.server.ts (same code), remove the handle, plus a docs link. It's written so that a developer or an agent reading the console can apply it directly. Older SvelteKit 2 versions keep the existing message.
  • Changeset: patch.

How

  • Test: a SvelteKit 3-shaped request state was added to the fail-closed cases. It checks that nothing is embedded and the SvelteKit 3 message is logged once.
  • Docs: the SvelteKit pages in Svelte docs: convexLoad lifecycle, hydration handle and client setup convex-backend#571 state the SvelteKit 3 limitation of convexLoadHydration.
  • Follow-up: proper SvelteKit 3 support for hydration needs a different mechanism. SvelteKit 3's remote functions handle hydration of universal-load results themselves, and could be the basis for it.

…g there

- Optional peer @sveltejs/kit: ^2.12.0 || ^3.0.0. With ^2.12.0, npm
  refused to install 0.15.0 next to SvelteKit 3 (ERESOLVE).
- SvelteKit 3 no longer sets is_in_universal_load, so convexLoadHydration
  still embeds nothing there (fail closed). Its warning now says that
  SvelteKit 3 isn't supported yet instead of asking for 2.56+.
@vercel

vercel Bot commented Oct 13, 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 14, 2026 5:59am UTC

Request Review

Name the effect (universal loads re-run in the browser before auth), the
fix (move auth-dependent convexLoad calls to +page.server.ts /
+layout.server.ts, same code; remove the handle) and the docs link.
@mmailaender

Copy link
Copy Markdown
Collaborator Author

@mikecann have send you a message on discord which would be great if you could read it first 😊

@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. One small thing my agent spotted tho: runed is still in dependencies but nothing imports it any more, and its peer range (@sveltejs/kit ^2.21.0) still gives an ERESOLVE warning on SvelteKit 3 and fails with --strict-peer-deps. Might be worth dropping it before you merge?

@pkg-pr-new

pkg-pr-new Bot commented Oct 14, 2026

Copy link
Copy Markdown

commit: 0061c45

@mmailaender
mmailaender merged commit dd11783 into main Oct 14, 2026
3 checks passed

This branch was successfully deployed

1 active deployment
Preview — 6690a722 Deployed Oct 14, 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