Installing Solid Query

Install and configure TanStack Solid Query in your SolidJS application

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

npm install @tanstack/solid-query

pnpm add @tanstack/solid-query

yarn add @tanstack/solid-query

bun add @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:

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.

Option	Type	Default	Description
staleTime	number	0	Time in milliseconds before data is considered stale
gcTime	number	5 * 60 * 1000	Time before inactive queries are garbage collected
refetchOnWindowFocus	boolean	true	Refetch queries when window regains focus
refetchOnReconnect	boolean	true	Refetch queries when network reconnects
retry	number | boolean	3	Number of retry attempts for failed queries
retryDelay	function	exponential	Delay 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

npm install @tanstack/solid-query-devtools

pnpm add @tanstack/solid-query-devtools

yarn add @tanstack/solid-query-devtools

bun add @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