Svelte Query

Purpose and Scope

Svelte Query is the Svelte framework entry in the TanStack Query documentation set. The repository docs configuration lists a dedicated svelte framework section alongside React, Solid, Vue, and Lit, and its children point readers to Overview, Installation, Devtools, SSR & SvelteKit, and migration material. That structure is important because Svelte Query is not a separate data model from TanStack Query; it is the Svelte-facing adapter path for the same server-state ideas: query keys, promise-returning query functions, cache lifecycle, background refetching, mutations, and devtools inspection. Sources: docs/config.json

Use this page when you already understand TanStack Query at a high level and need to place the Svelte package in the monorepo’s framework-adapter story. The official product language describes Query as a server-state manager for asynchronous data with a cache, lifecycle, declarative fetching APIs, mutation workflows, and framework adapters that include Svelte. In Svelte projects, that means the adapter should be treated as the framework-native access layer over the common QueryClient and cache behavior, not as a different fetching library with a different cache contract.

The most useful mental model is to separate three concerns. First, TanStack Query core owns cache identity, freshness, retries, invalidation, and observer coordination. Second, each framework adapter exposes those capabilities through the conventions of its UI runtime. Third, application code supplies query keys and query functions that return promises. The supplied Angular docs show this same adapter pattern through providers, injected query functions, devtools features, and background indicators; those examples are Angular-specific, but they are useful evidence of the monorepo’s cross-framework design vocabulary. Sources: docs/framework/angular/reference/functions/provideTanStackQuery.md, docs/framework/angular/angular-httpclient-and-other-data-fetching-clients.md, docs/framework/angular/devtools.md, docs/framework/angular/guides/background-fetching-indicators.md

Relevant Source Files

• docs/config.json - Defines the public docs navigation and shows the svelte framework section with Overview, Installation, Devtools, SSR & SvelteKit, and migration pages.
• docs/framework/angular/reference/functions/provideTanStackQuery.md - Documents the provider-based adapter setup pattern around QueryClient and optional features, which illustrates how framework adapters connect applications to TanStack Query.
• docs/framework/angular/angular-httpclient-and-other-data-fetching-clients.md - Explains that TanStack Query fetching is promise-based and backend-client agnostic, a core concept that applies across framework adapters.
• docs/framework/angular/devtools.md - Shows how framework-specific devtools integrate with a Query adapter and how production or development loading can be controlled.
• docs/framework/angular/guides/background-fetching-indicators.md - Demonstrates adapter-level access to query status and global fetching state, grounding the background-fetching UX concept.
• docs/community-resources.md - Provides the repository’s community resources catalog for learning broader TanStack Query patterns beyond the Svelte-specific docs path.

Documentation Map and Entry Points

The repository’s docs navigation is the clearest source-backed entry point for Svelte readers. Under the Getting Started section, docs/config.json includes a framework entry labeled svelte and maps it to five public pages: framework/svelte/overview, framework/svelte/installation, framework/svelte/devtools, framework/svelte/ssr, and framework/svelte/migrate-from-v5-to-v6. That sequence tells you how the first-party docs expect Svelte users to progress: understand the adapter, install it, add inspection tools, handle SvelteKit server rendering, and then apply migration guidance when moving between major adapter generations. Sources: docs/config.json

That docs spine is also a boundary marker. General TanStack Query concepts such as query keys, query functions, invalidation, retries, and mutations are shared across the project, while framework pages explain how to express those concepts in a specific runtime. For a Svelte application, start with the Svelte Overview and Installation pages, then use the general Query guides for cache behavior and workflow design. When your app uses SvelteKit, move to the SSR & SvelteKit entry before building your loading strategy, because server rendering changes where data is fetched, dehydrated, restored, and observed.

Community resources are useful after the Svelte entry points because many TanStack Query patterns are framework-independent. The repository’s community page includes maintainer-written articles, videos, and utilities such as Query Key Factory, GraphQL Code Generator, Orval, and other ecosystem tools. Some resources use React terminology because React Query was the original adapter, but their advice about cache keys, invalidation, server state, and mutation workflow usually transfers once you translate the framework binding layer. Sources: docs/community-resources.md

Core Primitives

The central primitive is QueryClient, the object that owns the query and mutation caches and exposes operations such as fetching, prefetching, reading cached data, invalidating queries, checking fetching or mutating counts, setting defaults, and clearing state. The supplied Angular provider reference shows a framework adapter receiving a QueryClient and setting up the providers needed to enable TanStack Query functionality in an application. In Svelte, the equivalent architectural requirement is still to make one client available to the component tree or runtime boundary that should share cache state. Sources: docs/framework/angular/reference/functions/provideTanStackQuery.md

The second primitive is the query definition: a stable query key and a query function. The Angular data-fetching guide states that TanStack Query’s fetching mechanisms are built agnostically on promises, so applications can use browser fetch, GraphQL clients, framework HTTP clients, or specialized request libraries. That matters for Svelte because Svelte Query does not require a TanStack-specific transport. You design the key as the cache contract, write a function that returns a promise, and let Query coordinate deduplication, freshness, retries, background refetching, and observers. Sources: docs/framework/angular/angular-httpclient-and-other-data-fetching-clients.md

The third primitive is observable query state. Framework adapters surface whether a query is pending, errored, successful, or currently fetching in the background. The Angular background-fetching guide demonstrates local query state such as isPending, isError, isSuccess, and isFetching, plus a global fetching indicator. Even though the syntax is Angular-specific, the user experience concern is shared: Svelte UIs often need to distinguish the first loading state from a background refresh so existing content can remain visible while a lightweight “refreshing” indicator appears. Sources: docs/framework/angular/guides/background-fetching-indicators.md

Adapter Role in a Svelte Application

Think of the Svelte adapter as the translation layer between Svelte components and the shared TanStack Query cache. The adapter’s job is to expose framework-appropriate APIs while preserving the same lifecycle rules users see in the rest of the documentation. That distinction helps prevent a common mistake: treating Svelte Query as a replacement for every local Svelte store. TanStack Query is for server state: remote, asynchronous, shared, cached, invalidated, and sometimes intentionally stale. Local UI state remains better modeled with Svelte’s own state tools.

A typical Svelte adoption plan begins by creating or configuring a QueryClient, wiring the adapter at the application boundary, and then replacing ad hoc request effects with declarative query definitions. Each query should have a key that encodes the resource and inputs, and each query function should return data through a promise. From there, use invalidation and mutation workflows to keep related cached data synchronized after writes. The supplied docs do not provide Svelte syntax, so the safe source-backed guidance is architectural rather than signature-level: preserve the common Query contract and follow the Svelte docs entries for exact adapter APIs.

For data clients, prefer the tool that fits your backend and runtime. The Angular guide explicitly compares a framework HTTP client, native fetch, and specialized libraries such as graphql-request, while emphasizing promise conversion when needed. The Svelte equivalent decision is similar: use fetch for lightweight HTTP calls, a generated OpenAPI or GraphQL client for typed APIs, or a custom wrapper for authentication and error normalization. Query should receive a promise-returning function and should not need to know whether the underlying request came from REST, GraphQL, or another async source. Sources: docs/framework/angular/angular-httpclient-and-other-data-fetching-clients.md

Devtools, SSR, and Migration Signals

The Svelte docs navigation includes a Devtools page, which indicates that inspection is part of the intended framework workflow. The Angular devtools page explains the general value: devtools help debug and inspect queries and mutations, and framework-specific packages or browser extensions can expose cache state during development. For Svelte users, devtools are especially helpful when validating query keys, checking stale versus fetching states, and confirming that invalidations affect the intended resources rather than unrelated cache entries. Sources: docs/config.json, docs/framework/angular/devtools.md

The Svelte navigation also includes SSR & SvelteKit, which is a strong signal that server rendering is a first-class concern for this adapter. When a SvelteKit route fetches data on the server and the client later hydrates, you need a deliberate Query setup so cached data, freshness, and refetch behavior match the user experience you expect. The supplied Angular data-fetching page mentions that SSR can interact with framework-level HTTP caching and TanStack Query hydration; the transferable lesson is to decide which layer owns request caching and how client-side Query state is restored. Sources: docs/config.json, docs/framework/angular/angular-httpclient-and-other-data-fetching-clients.md

Finally, the Svelte section includes Migrate from v5 to v6, so teams maintaining existing Svelte Query applications should treat the adapter version as a project planning concern. Before upgrading, inventory your QueryClient setup, devtools usage, SSR/SvelteKit integration, and query definitions. Then read the migration page before changing package versions. The repository-wide scripts and generated docs flow are outside this page’s source set, but the docs navigation itself confirms that migration guidance is part of the public Svelte path. Sources: docs/config.json

Practical Next Steps

For a new Svelte project, follow the public docs in the order implied by the repository configuration: start at Svelte Overview, install the Svelte adapter, wire the client at the application boundary, and add devtools early so cache behavior is visible while you build. Then implement one read query with a stable key and promise-returning fetcher before introducing mutations or SSR. This gives you a small working loop where you can observe pending, success, error, stale, and background-fetching behavior before scaling the pattern across routes.

For an existing SvelteKit app, review server-rendered routes separately from purely client-rendered components. Identify which data should be prefetched on navigation or server load, which data can be fetched after mount, and which mutations must invalidate route-level queries. Keep transport choices independent from Query adoption: generated OpenAPI clients, GraphQL clients, and plain fetch can all fit if they return promises and normalize errors consistently. When you need broader examples or best practices, use the community resources page to supplement the Svelte docs with cross-framework cache design material. Sources: docs/community-resources.md