feat!(svelte-query): rewrite Svelte adapter to use runes (#9694)

* WIP: Svelte 5 adapter (#6981)

* feat(svelte-query): Improve svelte runes API (#8852)

* feat: Draft proposal

* chore: Improve reactive containers

* ci: apply automated fixes

* oops

* fix: Update API, add a bunch of tests

* merge main

* fix: use const

* more tests

* feat: More tests, back to thunks, fixed svelte-query-persist-client

* feat: More tests and examples!

* lockfile

* fixes

* Fix current CI errors

* More small fixes/tweaks

* Remove test.only

* ci: apply automated fixes

* Fix pnpm-lock, fix import order

* update main docs

* feat: More tests

* ci: apply automated fixes

* add back old tests

* Cleanup

* Fix persist client

* Fix useMutationState

---------

Co-authored-by: autofix-ci[bot] <114827586+autofix-ci[bot]@users.noreply.github.com>
Co-authored-by: Lachlan Collins <[email protected]>

* Use sleep from query-test-utils

* Simplify test reset logic

* Fix some merge conflicts

* More fixes

* A few more fixes

* Fix useMutationState

* Add changeset

* Add migration docs

* Replace Set with SvelteSet

* Update minimum svelte version

* Bump svelte-eslint-parser

* Unwrap createQuery test

* fix(svelte-query): `state_unsafe_mutation` error with `useIs...` (#9493)

* fix(svelte-query): don't wrap observers in derived to avoid state_unsafe_mutation

fixes useIsFetching and useIsMutating in svelte 5 adapter

* test(svelte-query): wrap (useIs...) tests in QueryClientProvider to test non colocated query

* fix(svelte-query): update observers when passed in query client changes

* fix(svelte-query): simplify creatMutation sub/unsub

* Refactor result handling in createMutation.svelte.ts

Replace derived state with direct state and add watchChanges for result updates.

---------

Co-authored-by: Lachlan Collins <[email protected]>

* chore(svelte-query): fix eslint config (#9699)

* chore(svelte-query): fix eslint config

* Use @typescript-eslint/parser directly

* ci: apply automated fixes

* Fix sherif

* Update docs and changeset

* Update keywords

---------

Co-authored-by: Zhiheng Zhang <[email protected]>
Co-authored-by: Elliott Johnson <[email protected]>
Co-authored-by: autofix-ci[bot] <114827586+autofix-ci[bot]@users.noreply.github.com>
Co-authored-by: David <[email protected]>

Author: 5 people

.changeset/pink-pots-jam.md

@@ -0,0 +1,7 @@
+---
+'@tanstack/svelte-query-persist-client': major
+'@tanstack/svelte-query-devtools': major
+'@tanstack/svelte-query': major
+---
+
+BREAKING: Migrate to svelte runes (signals). Requires [Svelte v5.25.0](https://github.com/sveltejs/svelte/releases/tag/svelte%405.25.0) or newer. Please see the [migration guide](https://tanstack.com/query/latest/docs/framework/svelte/migrate-from-v5-to-v6).

docs/config.json

@@ -129,8 +129,8 @@
               "to": "framework/svelte/ssr"
             },
             {
-              "label": "Reactivity",
-              "to": "framework/svelte/reactivity"
+              "label": "Migrate from v5 to v6",
+              "to": "framework/svelte/migrate-from-v5-to-v6"
             }
           ]
         },

docs/framework/svelte/installation.md

@@ -5,8 +5,6 @@ title: Installation
 
 You can install Svelte Query via [NPM](https://npmjs.com).
 
-> v5 is currently available as a release-candidate. We don't anticipate any major API changes from here on out. We encourage you to try it out and report any issues you find.
-
 ### NPM
 
 ```bash

docs/framework/svelte/migrate-from-v5-to-v6.md

@@ -0,0 +1,77 @@
+## Overview
+
+While Svelte v5 has legacy compatibility with the stores syntax from Svelte v3/v4, it has been somewhat buggy and unreliable for this adapter. The `@tanstack/svelte-query` v6 adapter fully migrates to the runes syntax, which relies on signals. This rewrite should also simplify the code required to ensure your query inputs remain reactive.
+
+## Installation
+
+Please ensure your project has [Svelte v5.25.0](https://github.com/sveltejs/svelte/releases/tag/svelte%405.25.0) or newer.
+
+Run `pnpm add @tanstack/svelte-query@latest` (or your package manager's equivalent).
+
+> Note that `@tanstack/svelte-query` v6 depends on `@tanstack/query-core` v5.
+
+## Thunks
+
+Like the Solid adapter, most functions for the Svelte adapter now require options to be provided as a "thunk" (`() => options`) to provide reactivity.
+
+```diff
+-const query = createQuery({
++const query = createQuery(() => ({
+  queryKey: ['todos'],
+  queryFn: () => fetchTodos(),
+-})
++}))
+```
+
+## Accessing Properties
+
+Given the adapter no longer uses stores, it is no longer necessary to prefix with `$`.
+
+```diff
+-{#if $todos.isSuccess}
++{#if todos.isSuccess}
+  <ul>
+-    {#each $todos.data.items as item}
++    {#each todos.data.items as item}
+      <li>{item}</li>
+    {/each}
+  </ul>
+{/if}
+```
+
+## Reactivity
+
+You previously needed to do some funky things with stores to achieve reactivity for inputs. This is no longer the case! You don't even need to wrap your query in a `$derived`.
+
+```diff
+-const intervalMs = writable(1000)
++let intervalMs = $state(1000)
+
+-const query = createQuery(derived(intervalMs, ($intervalMs) => ({
++const query = createQuery(() => ({
+  queryKey: ['refetch'],
+  queryFn: async () => await fetch('/api/data').then((r) => r.json()),
+  refetchInterval: $intervalMs,
+-})))
++}))
+```
+
+## Disabling Legacy Mode
+
+If your component has any stores, it might not properly switch to runes mode. You can ensure your application is using runes in two ways:
+
+### On a per-file basis
+
+In each `.svelte` file, once you have migrated to runes, add `<svelte:options runes={true} />`. This is better for large applications requiring gradual migration.
+
+### On an project-wide basis
+
+In your `svelte.config.js`, add the following to config:
+
+```json
+  compilerOptions: {
+    runes: true,
+  },
+```
+
+This can be added once you've 100% eradicated stores syntax from your app.

docs/framework/svelte/overview.md

@@ -5,6 +5,8 @@ title: Overview
 
 The `@tanstack/svelte-query` package offers a 1st-class API for using TanStack Query via Svelte.
 
+> Migrating from stores to the runes syntax? See the [migration guide](../migrate-from-v5-to-v6).
+
 ## Example
 
 Include the QueryClientProvider near the root of your project:
@@ -28,19 +30,19 @@ Then call any function (e.g. createQuery) from any component:
 <script lang="ts">
   import { createQuery } from '@tanstack/svelte-query'
 
-  const query = createQuery({
+  const query = createQuery(() => ({
     queryKey: ['todos'],
     queryFn: () => fetchTodos(),
-  })
+  }))
 </script>
 
 <div>
-  {#if $query.isLoading}
+  {#if query.isLoading}
     <p>Loading...</p>
-  {:else if $query.isError}
-    <p>Error: {$query.error.message}</p>
-  {:else if $query.isSuccess}
-    {#each $query.data as todo}
+  {:else if query.isError}
+    <p>Error: {query.error.message}</p>
+  {:else if query.isSuccess}
+    {#each query.data as todo}
       <p>{todo.title}</p>
     {/each}
   {/if}
@@ -62,6 +64,8 @@ Svelte Query offers useful functions and components that will make managing serv
 - `useQueryClient`
 - `useIsFetching`
 - `useIsMutating`
+- `useMutationState`
+- `useIsRestoring`
 - `useHydrate`
 - `<QueryClientProvider>`
 - `<HydrationBoundary>`
@@ -70,5 +74,4 @@ Svelte Query offers useful functions and components that will make managing serv
 
 Svelte Query offers an API similar to React Query, but there are some key differences to be mindful of.
 
-- Many of the functions in Svelte Query return a Svelte store. To access values on these stores reactively, you need to prefix the store with a `$`. You can learn more about Svelte stores [here](https://learn.svelte.dev/tutorial/writable-stores).
-- If your query or mutation depends on variables, you must use a store for the options. You can read more about this [here](../reactivity).
+- The arguments to the `create*` functions must be wrapped in a function to preserve reactivity.

docs/framework/svelte/reactivity.md

@@ -58,11 +58,11 @@ export async function load() {
 
   export let data: PageData
 
-  const query = createQuery({
+  const query = createQuery(() => ({
     queryKey: ['posts'],
     queryFn: getPosts,
     initialData: data.posts,
-  })
+  }))
 </script>
 ```
 
@@ -136,10 +136,10 @@ export async function load({ parent, fetch }) {
   import { createQuery } from '@tanstack/svelte-query'
 
   // This data is cached by prefetchQuery in +page.ts so no fetch actually happens here
-  const query = createQuery({
+  const query = createQuery(() => ({
     queryKey: ['posts'],
     queryFn: async () => (await fetch('/api/posts')).json(),
-  })
+  }))
 </script>
 ```
 

docs/framework/svelte/ssr.md

@@ -44,6 +44,7 @@ export default [
       '@typescript-eslint/no-empty-function': 'off',
       '@typescript-eslint/no-unsafe-function-type': 'off',
       'no-case-declarations': 'off',
+      'prefer-const': 'off',
     },
   },
   {

eslint.config.js

@@ -4,6 +4,8 @@
   import { QueryClientProvider, QueryClient } from '@tanstack/svelte-query'
   import { SvelteQueryDevtools } from '@tanstack/svelte-query-devtools'
 
+  const { children } = $props()
+
   const queryClient = new QueryClient({
     defaultOptions: {
       queries: {
@@ -15,7 +17,7 @@
 
 <QueryClientProvider client={queryClient}>
   <main>
-    <slot />
+    {@render children()}
   </main>
   <SvelteQueryDevtools />
 </QueryClientProvider>

examples/svelte/auto-refetching/src/routes/+layout.svelte

@@ -5,32 +5,32 @@
     createMutation,
   } from '@tanstack/svelte-query'
 
-  let intervalMs = 1000
-  let value = ''
+  let intervalMs = $state(1000)
+  let value = $state<string>('')
 
   const client = useQueryClient()
 
   const endpoint = '/api/data'
 
-  $: todos = createQuery<{ items: string[] }>({
+  const todos = createQuery<{ items: string[] }>(() => ({
     queryKey: ['refetch'],
     queryFn: async () => await fetch(endpoint).then((r) => r.json()),
     // Refetch the data every second
     refetchInterval: intervalMs,
-  })
+  }))
 
-  const addMutation = createMutation({
+  const addMutation = createMutation(() => ({
     mutationFn: (value: string) =>
       fetch(`${endpoint}?add=${encodeURIComponent(value)}`).then((r) =>
         r.json(),
       ),
     onSuccess: () => client.invalidateQueries({ queryKey: ['refetch'] }),
-  })
+  }))
 
-  const clearMutation = createMutation({
+  const clearMutation = createMutation(() => ({
     mutationFn: () => fetch(`${endpoint}?clear=1`).then((r) => r.json()),
     onSuccess: () => client.invalidateQueries({ queryKey: ['refetch'] }),
-  })
+  }))
 </script>
 
 <h1>Auto Refetch with stale-time set to {intervalMs}ms</h1>
@@ -51,53 +51,59 @@
           margin-left:.5rem;
           width:.75rem;
           height:.75rem; 
-          background: {$todos.isFetching ? 'green' : 'transparent'};
-          transition: {!$todos.isFetching ? 'all .3s ease' : 'none'};
+          background: {todos.isFetching ? 'green' : 'transparent'};
+          transition: {!todos.isFetching ? 'all .3s ease' : 'none'};
           border-radius: 100%;
           transform: scale(1.5)"
     ></span>
   </div>
 </label>
 <h2>Todo List</h2>
 <form
-  on:submit={(e) => {
+  onsubmit={(e) => {
     e.preventDefault()
     e.stopPropagation()
-    $addMutation.mutate(value, {
+    addMutation.mutate(value, {
       onSuccess: () => (value = ''),
     })
   }}
 >
   <input placeholder="enter something" bind:value />
 </form>
 
-{#if $todos.isPending}
+{#if todos.isPending}
   Loading...
 {/if}
-{#if $todos.error}
+{#if todos.error}
   An error has occurred:
-  {$todos.error.message}
+  {todos.error.message}
 {/if}
-{#if $todos.isSuccess}
+{#if todos.isSuccess}
   <ul>
-    {#each $todos.data.items as item}
+    {#each todos.data.items as item}
       <li>{item}</li>
     {/each}
   </ul>
   <div>
-    <button on:click={() => $clearMutation.mutate(undefined)}>
-      Clear All
-    </button>
-  </div>
-{/if}
-{#if $todos.isFetching}
-  <div style="color:darkgreen; font-weight:700">
-    'Background Updating...' : ' '
+    <button onclick={() => clearMutation.mutate(undefined)}> Clear All </button>
   </div>
 {/if}
 
+<pre
+  class={['updating-text', todos.isFetching && 'on']}
+  style="font-weight:700">Background Updating...</pre>
+
 <style>
   li {
     text-align: left;
   }
+
+  .updating-text {
+    color: transparent;
+    transition: all 0.3s ease;
+  }
+  .updating-text.on {
+    color: green;
+    transition: none;
+  }
 </style>