Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
15 changes: 0 additions & 15 deletions .changeset/convexload-hydration-single-subscription.md

This file was deleted.

19 changes: 0 additions & 19 deletions .changeset/route-scoped-convex-load.md

This file was deleted.

28 changes: 28 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
@@ -1,5 +1,33 @@
# convex-svelte

## 0.15.0

### Minor Changes

- e8d95bc: ### Fixes

- **With the new `convexLoadHydration` handle, `convexLoad` in `+page.ts` no longer queries without auth during hydration** - SvelteKit re-runs universal load functions in the browser during hydration, before `setupAuth()` has authenticated the client. `convexLoad` / `convexLoadPaginated` therefore queried Convex unauthenticated, replacing the server-rendered data with anonymous results (or failing the load for auth-protected queries). With the opt-in `convexLoadHydration` handle, the server embeds its results in the HTML and hydration reuses them: the live subscription starts after auth, and the page becomes interactive without waiting for the WebSocket. Without the handle, hydration still queries as before.
- **One subscription per `convexLoad`** - on client-side navigation, `convexLoad` ran a one-shot query and then subscribed again (Add → Remove → Add on the WebSocket), executing the query twice. It now opens the live subscription and awaits its first value. `convexLoadPaginated` no longer fetches the first page twice.
- **No loading flash for paginated SSR data** - with SSR `initialData`, `convexLoadPaginated` (and `usePaginatedQuery` with `initialData`) briefly reported `isLoading: true` / `LoadingFirstPage` right after hydration, so pages rendered their loading state over the server-rendered results. The initial args and the subscription's first empty snapshot now keep the SSR results visible and not loading.

### Features
- **`convexLoadHydration`** - new SvelteKit `handle` exported from the new entry point `convex-svelte/sveltekit/server/hydration` (requires SvelteKit 2.56 or later). Add it to `hooks.server.ts` (combine with your own handle via `sequence()`) and put a `%convex.hydration%` placeholder in the `<head>` of `src/app.html` to embed `convexLoad` results of universal loads in the SSR HTML. Without the placeholder nothing is embedded, and a dev warning says so. Everything `convexLoad` fetches while a universal load runs is embedded, including calls in helpers it invokes, but not inside remote functions. Server loads (`+page.server.ts`) never contribute, not even results they use internally, and the ones they return reach the browser through the transport. Universal loads and remote functions are detected via SvelteKit's internal `is_in_universal_load` and `is_in_remote_function` request-store flags (also used by SvelteKit's remote functions). If they can't be read, nothing is embedded and a warning is logged. Pages without results (e.g. `ssr = false`) get no payload and no dev warnings. An unreadable payload is ignored, so the load queries instead. It's a separate entry point so that `convex-svelte/sveltekit/server` keeps working on older SvelteKit versions. A streamed (not awaited) `convexLoad` result is only embedded if it finished before the page HTML was generated; in development, a warning points out loads that miss the payload during hydration.
- **`hydrate: false`** - `convexLoad` / `convexLoadPaginated` option to leave a result out of the SSR payload, e.g. a large one. That load then queries Convex during hydration, before `setupAuth()`, as it did without the handle.

- d7cb157: ### Breaking

- **`convex-svelte/sveltekit` requires SvelteKit 2.12 or later**, because it now imports `$app/state`. It can no longer be imported outside a SvelteKit app, e.g. to use `createConvexHttpClient` in a Node script; use `ConvexHttpClient` from `convex/browser` there. `@sveltejs/kit@^2.12.0` is declared as an optional peer dependency.

### Fixes
- **`convexLoad` / `convexLoadPaginated` subscriptions are released after leaving a route** ([#57](https://github.com/get-convex/convex-svelte/issues/57)) - previously every query created through `convexLoad`, `convexLoadPaginated`, or the SvelteKit transport stayed subscribed for the life of the tab, so bandwidth and function calls grew with every visited page (including hover preloads and `invalidate()` re-runs). These queries are now route-scoped: they stay subscribed while they are reachable from `page.data` (all layouts plus the current page) or rendered by a component, and are released afterwards. A released query resubscribes automatically when it is used again.
- **Unclaimed queries are closed after 5 s** - a query that no route ever uses (a hover preload the user doesn't click, a superseded navigation) is closed after 5 s and never takes a slot in the idle buffer, so hovering over many links can't push out pages you visited. A late click resubscribes.

### Features
- **Idle buffer for released queries** - released queries stay subscribed in a small buffer, so revisiting a page reuses the live subscription instead of subscribing again. A revisit replaces its idle copy instead of taking another slot. Configure it via `initConvex(url, { queryCache: { maxIdleEntries, expiration } })` (default `{ maxIdleEntries: 10, expiration: 60_000 }`), or pass `queryCache: false` to unsubscribe immediately. The option names match convex-helpers' `ConvexQueryCacheProvider`; when the buffer is full, the query idle the longest is evicted. `closeConvex()` disposes all of these queries.
- **Per-query `keepAlive`** - `convexLoad(query, args, { keepAlive: false })` and `convexLoadPaginated(query, args, { initialNumItems, keepAlive: false })` skip the idle buffer for that query.
- **`dispose()`** - results of `convexLoad`, `convexLoadPaginated`, `createDetachedQuery`, and `createDetachedPaginatedQuery` expose `dispose()` to stop the subscription explicitly. After `dispose()`, `loadMore()` returns `false`. `createDetachedQuery` / `createDetachedPaginatedQuery` accept `{ scope: 'route' }` to opt into route-scoped release.
- **`isStale` on `convexLoad` results** - now `true` while a released query shows its last known data.

## 0.14.0

### Minor Changes
Expand Down
2 changes: 1 addition & 1 deletion package.json
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@
"Convex, Inc. <no-reply@convex.dev>",
"Micha Mailaender"
],
"version": "0.14.0",
"version": "0.15.0",
"license": "Apache-2.0",
"homepage": "https://convex.dev",
"repository": {
Expand Down