Skip to main content
Get started with Svelte Query by installing the package and setting up your application.

​
Requirements

Svelte Query requires:
  • Svelte 5.25.0 or higher - Uses modern Svelte 5 runes ($state, $derived, $effect)
  • TypeScript 4.7+ (recommended) - For full type safety
  • Node.js 18+ - For development
Svelte Query is built specifically for Svelte 5 and uses runes. It will not work with Svelte 3 or 4. For older versions of Svelte, use a different data fetching solution.

​
Installation

1

Install the package

Install @tanstack/svelte-query using your preferred package manager:
npm install @tanstack/svelte-query
This will install @tanstack/svelte-query version 6.0.18 or higher, which includes:
  • Core query functionality
  • TypeScript type definitions
  • Svelte 5 rune-based reactivity
2

Set up the QueryClientProvider

Create a QueryClient and wrap your application with QueryClientProvider in your root layout:
+layout.svelte
<script lang="ts">
import { QueryClient, QueryClientProvider } from '@tanstack/svelte-query'

const queryClient = new QueryClient({
  defaultOptions: {
    queries: {
      staleTime: 60 * 1000, // 1 minute
    },
  },
})

const { children } = $props()
</script>

<QueryClientProvider client={queryClient}>
  {@render children()}
</QueryClientProvider>
In SvelteKit applications, place this in your root +layout.svelte file to make the QueryClient available throughout your app.
3

Start using queries

You can now use Svelte Query hooks in any component:
+page.svelte
<script lang="ts">
import { createQuery } from '@tanstack/svelte-query'

const query = createQuery(() => ({
  queryKey: ['todos'],
  queryFn: async () => {
    const response = await fetch('/api/todos')
    return response.json()
  },
}))
</script>

{#if query.isPending}
  <p>Loading...</p>
{:else if query.isError}
  <p>Error: {query.error.message}</p>
{:else}
  <ul>
    {#each query.data as todo}
      <li>{todo.title}</li>
    {/each}
  </ul>
{/if}

​
Configuration Options

The QueryClient accepts various configuration options to customize its behavior: 
const queryClient = new QueryClient({
  defaultOptions: {
    queries: {
      // How long data stays fresh (ms)
      staleTime: 60 * 1000,
      
      // How long inactive data stays in cache (ms)
      gcTime: 5 * 60 * 1000,
      
      // Retry failed requests
      retry: 3,
      
      // Refetch on window focus
      refetchOnWindowFocus: true,
      
      // Refetch on component mount
      refetchOnMount: true,
      
      // Refetch on network reconnect
      refetchOnReconnect: true,
    },
    mutations: {
      // Retry failed mutations
      retry: 1,
    },
  },
})

​
Common Configuration Patterns

const queryClient = new QueryClient({
  defaultOptions: {
    queries: {
      staleTime: 10 * 60 * 1000, // 10 minutes
      gcTime: 15 * 60 * 1000,    // 15 minutes
      refetchOnWindowFocus: false,
      retry: 1,
    },
  },
})

​
SvelteKit Integration

For SvelteKit applications, you may want to handle browser-specific features:
+layout.svelte
<script lang="ts">
import { browser } from '$app/environment'
import { QueryClient, QueryClientProvider } from '@tanstack/svelte-query'

const queryClient = new QueryClient({
  defaultOptions: {
    queries: {
      // Only run queries in the browser
      enabled: browser,
      staleTime: 60 * 1000,
    },
  },
})

const { children } = $props()
</script>

<QueryClientProvider client={queryClient}>
  {@render children()}
</QueryClientProvider>
Setting enabled: browser prevents queries from running during server-side rendering, which is useful for client-only data fetching.

​
Optional: Install DevTools

For development, install the Svelte Query DevTools to visualize and debug your queries: 
npm install -D @tanstack/svelte-query-devtools
Then add it to your layout:
+layout.svelte
<script lang="ts">
import { QueryClient, QueryClientProvider } from '@tanstack/svelte-query'
import { SvelteQueryDevtools } from '@tanstack/svelte-query-devtools'

const queryClient = new QueryClient()
const { children } = $props()
</script>

<QueryClientProvider client={queryClient}>
  {@render children()}
  <SvelteQueryDevtools />
</QueryClientProvider>
The DevTools only render in development mode and are automatically tree-shaken from production builds.

​
Package Dependencies

Svelte Query has a minimal dependency footprint:
package.json
{
  "dependencies": {
    "@tanstack/query-core": "workspace:*"
  },
  "peerDependencies": {
    "svelte": "^5.25.0"
  }
}
  • @tanstack/query-core - Framework-agnostic core query logic
  • svelte - Required peer dependency (version 5.25.0+)

​
Troubleshooting

​
Error: “Svelte version 5.25.0 or higher is required”

Ensure you have Svelte 5.25.0+ installed: 
npm install svelte@latest

​
Error: “Cannot find QueryClient in context”

Make sure you’ve wrapped your app with QueryClientProvider: 
<QueryClientProvider client={queryClient}>
  <!-- Your app here -->
</QueryClientProvider>

​
TypeScript errors with runes

Ensure your tsconfig.json is configured for Svelte 5:
tsconfig.json
{
  "extends": "./.svelte-kit/tsconfig.json",
  "compilerOptions": {
    "strict": true,
    "module": "ESNext",
    "target": "ESNext"
  }
}

​
Next Steps

1

Quick Start Guide

Learn the basics with a step-by-step tutorial.Quick Start →
2

TypeScript Configuration

Set up TypeScript for maximum type safety.TypeScript Guide →
3

Configure DevTools

Learn how to use the Svelte Query DevTools.DevTools Setup →

Build docs developers (and LLMs) love

Get started for freeTalk to us