From 6004e2fba6b543108ba817a18864205ac5a8ae30 Mon Sep 17 00:00:00 2001
From: Lucas Leung <kayauleung2024@gmail.com>
Date: Tue, 18 Aug 2026 23:46:23 +0800
Subject: [PATCH] Add quick start docs in svelte query

---
 docs/config.json                     |   4 +
 docs/framework/svelte/quick-start.md | 151 +++++++++++++++++++++++++++
 2 files changed, 155 insertions(+)
 create mode 100644 docs/framework/svelte/quick-start.md

diff --git a/docs/config.json b/docs/config.json
index 5e05670425..ad6cae2efd 100644
--- a/docs/config.json
+++ b/docs/config.json
@@ -117,6 +117,10 @@
               "label": "Overview",
               "to": "framework/svelte/overview"
             },
+            {
+              "label": "Quick Start",
+              "to": "framework/svelte/quick-start"
+            },
             {
               "label": "Installation",
               "to": "framework/svelte/installation"
diff --git a/docs/framework/svelte/quick-start.md b/docs/framework/svelte/quick-start.md
new file mode 100644
index 0000000000..afc082f1d0
--- /dev/null
+++ b/docs/framework/svelte/quick-start.md
@@ -0,0 +1,151 @@
+---
+id: quick-start
+title: Quick Start
+---
+
+The `@tanstack/svelte-query` package offers a 1st-class API for using TanStack Query via Svelte.
+
+## Example
+
+```svelte
+<script lang="ts">
+  import { QueryClient, QueryClientProvider } from '@tanstack/svelte-query'
+  import Example from './lib/Example.svelte'
+
+  const queryClient = new QueryClient()
+</script>
+
+<QueryClientProvider client={queryClient}>
+  <Example />
+</QueryClientProvider>
+```
+
+Then call any function (e.g. createQuery) from any component:
+
+```svelte
+<script lang="ts">
+  import { createQuery } from '@tanstack/svelte-query'
+
+  const query = createQuery(() => ({
+    queryKey: ['todos'],
+    queryFn: () => fetchTodos(),
+  }))
+</script>
+
+<div>
+  {#if query.isPending}
+    <p>Loading...</p>
+  {: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}
+</div>
+```
+
+## Important Differences between Svelte Query & React Query
+
+Svelte Query offers an API similar to React Query, but there are some key differences to be mindful of.
+
+- Arguments to `svelte-query` primitives (like `createQuery`, `createMutation`, `useIsFetching`) are functions, so that they can be tracked in a reactive scope.
+
+```ts
+// ❌ react version
+useQuery({
+  queryKey: ['todos', todo],
+  queryFn: fetchTodos,
+})
+
+// ✅ svelte version
+createQuery(() => ({
+  queryKey: ['todos', todo],
+  queryFn: fetchTodos,
+}))
+```
+
+- Svelte Query primitives do not support destructuring. The return value from these functions is a store, and their properties are only tracked in a reactive context.
+
+```svelte
+<script lang="ts">
+  import { createQuery } from '@tanstack/svelte-query'
+
+  const query = createQuery(() => ({
+    queryKey: ['repoData'],
+    queryFn: () =>
+      fetch('https://api.github.com/repos/tannerlinsley/react-query').then(
+        (res) => res.json(),
+      ),
+  }))
+</script>
+
+  <!-- ❌ react version -- supports destructing outside reactive context
+  const { isPending, error, data } = useQuery({
+    queryKey: ['repoData'],
+    queryFn: () =>
+      fetch('https://api.github.com/repos/tannerlinsley/react-query').then(
+        (res) => res.json(),
+      ),
+  }) -->
+
+<!-- ✅ access query properties in svelte reactive context -->
+<div>
+  {#if query.isPending}
+    <p>Loading...</p>
+  {:else if query.isError}
+    <p>Error: {query.error.message}</p>
+  {:else if query.isSuccess}
+  <div>
+    <h1>{query.data.name}</h1>
+    <p>{query.data.description}</p>
+    <strong>👀 {query.data.subscribers_count}</strong>
+    <strong>✨ {query.data.stargazers_count}</strong>
+    <strong>🍴 {query.data.forks_count}</strong>
+  </div>
+  {/if}
+</div>
+```
+
+- Runes values can be passed in directly to function arguments. Svelte Query will update the query automatically.
+
+```svelte
+<script lang="ts">
+  import { createQuery } from '@tanstack/svelte-query'
+
+  let enabled = $state(false);
+  let todoCount = $state(0);
+
+  // ✅ passing a rune directly is safe and observers update
+  // automatically when the value of a rune changes
+  const todosQuery = createQuery(() => ({
+    queryKey: ['todos'],
+    queryFn: () => fetchTodos(),
+    enabled: enabled,
+  }))
+
+  const todoDetailsQuery = createQuery(() => ({
+    queryKey: ['todo', todoCount],
+    queryFn: fetchTodo,
+    enabled: todoCount > 0,
+  }))
+</script>
+
+<div>
+  {#if todosQuery.isPending}
+    <p>Loading...</p>
+  {:else if todosQuery.isError}
+    <p>Error: {todosQuery.error.message}</p>
+  {:else if todosQuery.isSuccess}
+    {#each todosQuery.data as todo}
+      <button onClick={() => (todoCount = todo.id)}>{todo.title}</button>
+    {/each}    
+  {/if}
+  <button onClick={() => (enabled = !enabled)}>Toggle enabled</button>
+</div>
+```
+
+- Errors can be caught and reset using Svelte's native `<svelte:boundary>` component.
+  Set `throwOnError` option to `true` to make sure errors are thrown to the `<svelte:boundary>` component.
+
+- Since Property tracking is handled through Svelte's fine grained reactivity, options like `notifyOnChangeProps` are not needed