Solid Query

Purpose and Scope

Solid Query is the Solid framework adapter for TanStack Query, the server-state manager that gives asynchronous data a cache, lifecycle, and declarative API. In a Solid application, the adapter lets components declare remote data requirements while the shared query client coordinates caching, deduplication, freshness, background refetching, retries, mutations, and observation. The official docs navigation treats Solid as a first-class framework alongside React, Vue, Svelte, Angular, and Lit, with its own Overview, Quick Start, Installation, Devtools, and TypeScript pages rather than a single generic adapter page.

Sources: docs/config.json

Use this page when you already understand the core Query vocabulary but need to orient yourself in the Solid-specific surface. The most important mental model is that Solid Query adapts the same promise-based query engine to Solid’s reactive component model. Query keys still identify cached resources, query functions still return promises, and a QueryClient still owns the cache. The Solid adapter is responsible for making those concepts ergonomic in Solid components, including provider setup, reactive query results, suspense-friendly reads, and development tooling.

Sources: docs/config.json, docs/framework/angular/angular-httpclient-and-other-data-fetching-clients.md

Relevant Source Files

• docs/config.json - Defines the first-party docs structure and shows the Solid framework section with Overview, Quick Start, Installation, Devtools, and TypeScript pages.
• docs/framework/angular/reference/functions/provideTanStackQuery.md - Documents an adapter provider pattern built around a QueryClient, optional features, and devtools, which is useful context for how framework adapters wire the shared client into an application.
• docs/community-resources.md - Lists community learning resources and utilities that apply to Query concepts across framework adapters, including query key utilities and generated clients.
• docs/framework/angular/angular-httpclient-and-other-data-fetching-clients.md - States the adapter-agnostic fetching rule: TanStack Query fetchers are promise-based and can wrap clients such as native fetch, GraphQL clients, or framework HTTP clients.
• docs/framework/angular/devtools.md - Shows how framework devtools are positioned: they inspect queries and mutations, can be loaded conditionally, and have browser-extension alternatives.
• docs/framework/angular/guides/background-fetching-indicators.md - Demonstrates the state distinction between initial loading and background fetching, a core Query behavior that Solid users should account for in UI design.

Core Primitives

The core primitives to look for in Solid Query are the same concepts used throughout TanStack Query. A QueryClient is the long-lived object that owns caches and default options. A provider makes that client available to component-level query APIs. A query describes a read operation with a queryKey and a promise-returning queryFn. Mutations describe writes and are usually followed by cache updates or invalidations. Devtools inspect the resulting cache, observers, mutations, freshness, errors, and fetching activity so developers can see what the runtime is doing.

Sources: docs/framework/angular/reference/functions/provideTanStackQuery.md, docs/framework/angular/devtools.md

Solid users should pay special attention to the provider boundary. The Angular adapter documentation shows this pattern explicitly through provideTanStackQuery(queryClient, ...features), which sets up providers for a configured QueryClient and optional features such as devtools. Solid uses its own framework-native provider API rather than Angular providers, but the architectural requirement is the same: create a client once for an application boundary and make it available to query consumers below that boundary. Recreating clients inside frequently rendered components defeats cache sharing and makes background behavior harder to reason about.

Sources: docs/framework/angular/reference/functions/provideTanStackQuery.md

Fetching is deliberately backend-agnostic. The Angular data-fetching guide states that TanStack Query is built on promises and can use native fetch, graphql-request, or other asynchronous clients. That rule transfers directly to Solid Query: the adapter does not require a special transport layer. If a client returns an observable or another non-promise primitive, convert it to a promise before returning it from the query function. This keeps retry, cancellation, background refresh, stale-state tracking, and error handling aligned with the core query lifecycle.

Sources: docs/framework/angular/angular-httpclient-and-other-data-fetching-clients.md

Solid Usage Flow

A typical Solid Query setup starts by installing the Solid adapter, creating a QueryClient, and rendering the application inside the adapter’s provider. Inside components, declare reads with Solid’s query creation API and supply a stable key plus an async function. The query result should drive UI states such as pending, error, success, stale, and fetching. Treat the key as the cache contract: it should include the resource name and any variables that affect the returned data, because invalidation, refetching, prefetching, and devtools all use that identity.

Sources: docs/config.json

import { QueryClient, QueryClientProvider, createQuery } from '@tanstack/solid-query'
 
const queryClient = new QueryClient()
 
function Todos() {
  const todosQuery = createQuery(() => ({
    queryKey: ['todos'],
    queryFn: fetchTodos,
  }))
 
  return (
    <Show when={todosQuery.isSuccess} fallback="Loading...">
      <For each={todosQuery.data}>{(todo) => <Todo todo={todo} />}</For>
    </Show>
  )
}
 
render(
  () => (
    <QueryClientProvider client={queryClient}>
      <Todos />
    </QueryClientProvider>
  ),
  document.getElementById('root')!,
)

The important state distinction is initial loading versus background fetching. The background-fetching guide shows a component that renders a loading state while a query is pending, then renders existing data while displaying a refreshing indicator when isFetching is true. Solid Query users should preserve that UX distinction instead of replacing useful cached data with a spinner on every refetch. A global indicator can also be useful for route transitions or layouts, because the query cache can know when any matching query is fetching in the background.

Sources: docs/framework/angular/guides/background-fetching-indicators.md

Suspense, Devtools, and TypeScript

Solid’s rendering model makes suspense an important part of the adapter story. At a high level, suspense-friendly query APIs let a component suspend while data is not ready and then continue rendering once the promise resolves. Use suspense when the surrounding UI has an intentional fallback boundary and when pending data should block that subtree. Use non-suspense query state when you need to show stale data, partial screens, retry controls, or background-refresh indicators. Both styles still rely on the same QueryClient, keys, promise-returning functions, and cache lifecycle.

Sources: docs/config.json, docs/framework/angular/guides/background-fetching-indicators.md

Devtools are part of the Solid documentation section, and the shared devtools documentation explains why they matter: they help inspect queries and mutations during development. The Angular devtools page also documents browser extensions for Chrome, Firefox, and Edge, plus adapter-specific package integration that can be conditionally loaded. For Solid applications, the practical workflow is to enable the Solid devtools during development, inspect query keys and observer counts, verify that refetching happens when expected, and confirm that mutations invalidate or update the intended cache entries.

Sources: docs/config.json, docs/framework/angular/devtools.md

TypeScript support belongs in the Solid docs navigation, which signals that Solid users should not treat types as an afterthought. Prefer typed fetch functions and let query result types flow from the promise result. Centralized option factories are useful when several components share a key and query function, because they reduce accidental key drift and make invalidation more reliable. Community utilities listed in the repository docs, such as query key factories, generated GraphQL/OpenAPI clients, and reusable Query kits, can complement this pattern when an application needs stricter conventions across many resources.

Sources: docs/config.json, docs/community-resources.md

System-to-Code Mapping

Next Steps

Start with the Solid Quick Start in the official docs, then add devtools before debugging cache behavior. Build the first screen around one stable query key and one promise-returning fetcher, then verify the pending, success, error, and background-fetching states in the UI. Once the provider and basic query are working, move to TypeScript conventions, query key organization, mutations, invalidation, and suspense boundaries. If your team uses generated GraphQL or OpenAPI clients, connect them at the query-function layer rather than bypassing Query’s cache lifecycle.

Sources: docs/config.json, docs/community-resources.md