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

.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 (svelte v5+). Please see documentation for migration guide.

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,60 @@
+## Overview
+
+While Svelte v5 has legacy compatibility with the stores syntax from Svelte v3/v4, it has been somewhat buggy and unreliable for this TanStack Query adapter. The `@tanstack/svelte-query` v6 adapter fully migrates to runes syntax.
+
+## 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 maintain 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}
+```
+
+## 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/ssr.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>
 ```
 

eslint.config.js

@@ -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',
     },
   },
   {

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

@@ -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/+page.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>

examples/svelte/auto-refetching/svelte.config.js

@@ -7,6 +7,9 @@ const config = {
   kit: {
     adapter: adapter(),
   },
+  compilerOptions: {
+    runes: true,
+  },
 }
 
 export default config