Skip to main content

​
Installation

Get started with Solid Query by installing the package and setting up your application.

​
Prerequisites

Solid Query requires SolidJS 1.6.0 or higher. 
{
  "peerDependencies": {
    "solid-js": "^1.6.0"
  }
}

​
Package Installation

npm install @tanstack/solid-query
Solid Query follows semantic versioning. The current version is 5.90.23.

​
Basic Setup

After installation, set up the QueryClientProvider in your application root:
1
Create a Query Client
2
Create a QueryClient instance that will manage your queries:
3
import { QueryClient } from '@tanstack/solid-query'

const queryClient = new QueryClient()
4
Wrap Your App
5
Wrap your application with QueryClientProvider:
6
import { render } from 'solid-js/web'
import { QueryClient, QueryClientProvider } from '@tanstack/solid-query'

const queryClient = new QueryClient()

function App() {
  return (
    <QueryClientProvider client={queryClient}>
      <div>
        <h1>My App</h1>
        {/* Your application components */}
      </div>
    </QueryClientProvider>
  )
}

render(() => <App />, document.getElementById('root')!)
7
Start Using Queries
8
Now you can use Solid Query primitives in any component:
9
import { useQuery } from '@tanstack/solid-query'

function TodoList() {
  const todosQuery = useQuery(() => ({
    queryKey: ['todos'],
    queryFn: async () => {
      const response = await fetch('https://api.example.com/todos')
      return response.json()
    },
  }))

  return (
    <div>
      <Show when={todosQuery.data}>
        {(todos) => (
          <For each={todos()}>
            {(todo) => <li>{todo.title}</li>}
          </For>
        )}
      </Show>
    </div>
  )
}

​
Configuration Options

Customize the QueryClient with default options: 
import { QueryClient } from '@tanstack/solid-query'

const queryClient = new QueryClient({
  defaultOptions: {
    queries: {
      // Queries will not refetch on window focus by default
      refetchOnWindowFocus: false,
      // Queries will be considered stale after 5 minutes
      staleTime: 5 * 60 * 1000,
      // Failed queries will retry 3 times before showing an error
      retry: 3,
      // Retry with exponential backoff
      retryDelay: (attemptIndex) => Math.min(1000 * 2 ** attemptIndex, 30000),
    },
    mutations: {
      // Mutations will retry once on failure
      retry: 1,
    },
  },
})

​
Common Configuration Options

These are the most commonly used configuration options. See the full API reference for all available options.
OptionTypeDefaultDescription
staleTimenumber0Time in milliseconds before data is considered stale
gcTimenumber5 * 60 * 1000Time before inactive queries are garbage collected
refetchOnWindowFocusbooleantrueRefetch queries when window regains focus
refetchOnReconnectbooleantrueRefetch queries when network reconnects
retrynumber | boolean3Number of retry attempts for failed queries
retryDelayfunctionexponentialDelay between retry attempts

​
Server-Side Rendering Setup

For SSR applications, create a new QueryClient instance per request: 
import { renderToString } from 'solid-js/web'
import { QueryClient, QueryClientProvider } from '@tanstack/solid-query'

// Server-side handler
export async function handler(req, res) {
  // Create a new client for each request
  const queryClient = new QueryClient({
    defaultOptions: {
      queries: {
        // SSR-specific options are automatically applied
        // retry: false (set automatically on server)
        // throwOnError: true (set automatically on server)
      },
    },
  })

  const html = renderToString(() => (
    <QueryClientProvider client={queryClient}>
      <App />
    </QueryClientProvider>
  ))

  res.send(html)
}
Always create a new QueryClient instance for each request in SSR to prevent data leaking between users.

​
DevTools Installation (Optional)

Install the DevTools package for development debugging: 
npm install @tanstack/solid-query-devtools
Add the DevTools component to your app: 
import { QueryClient, QueryClientProvider } from '@tanstack/solid-query'
import { SolidQueryDevtools } from '@tanstack/solid-query-devtools'

const queryClient = new QueryClient()

function App() {
  return (
    <QueryClientProvider client={queryClient}>
      <YourApp />
      <SolidQueryDevtools />
    </QueryClientProvider>
  )
}
DevTools are automatically excluded from production builds when using the default configuration.

​
TypeScript Setup

Solid Query is written in TypeScript and provides full type safety out of the box. No additional configuration is needed, but you can enhance type inference: 
import { useQuery } from '@tanstack/solid-query'

interface Todo {
  id: number
  title: string
  completed: boolean
}

function TodoList() {
  // TypeScript will infer the return type from queryFn
  const todosQuery = useQuery(() => ({
    queryKey: ['todos'],
    queryFn: async (): Promise<Todo[]> => {
      const response = await fetch('/api/todos')
      return response.json()
    },
  }))

  // todosQuery.data is typed as Todo[] | undefined
  return <div>{todosQuery.data?.length} todos</div>
}

​
Bundle Size

Solid Query is designed to be lightweight:
  • @tanstack/solid-query: ~15kb min+gzip
  • @tanstack/solid-query-devtools: ~25kb min+gzip (dev only)
The exact bundle size depends on your bundler and tree-shaking configuration. The package is fully tree-shakeable.

​
Version Compatibility

Solid Query is tested against multiple TypeScript versions:
  • TypeScript 5.0+
  • TypeScript 5.1+
  • TypeScript 5.2+
  • TypeScript 5.3+
  • TypeScript 5.4+
  • TypeScript 5.5+
  • TypeScript 5.6+
  • TypeScript 5.7+ (latest)

​
Next Steps

Quick Start

Build your first application with Solid Query

Overview

Learn about core concepts and features

Build docs developers (and LLMs) love

Get started for freeTalk to us