@mihail_nica/zustand-query

Provider-free React Query wrapper with Zustand subscriptions — React 17+, full TypeScript generics, DevTools, SSR.

Note: Published as @mihail_nica/zustand-query. Create the @yebichu npm scope to use as @yebichu/zustand-query.

Why

React Query normally requires a <QueryClientProvider>. This library lets you use React Query without any Provider — state lives in a Zustand store that you control.

Features

• No Provider required — Zustand store holds all query/mutation state
• React 17+ via use-sync-external-store/shim
• Full TypeScript generics on all APIs
• DevTools integration — React Query DevTools panel via Zustand devtools middleware
• SSR ready — createServerQueryClient() for server-side rendering
• Zustand native — works with all Zustand middleware (persist, devtools, immer, etc.)

Install

npm install @yebichu/zustand-query @tanstack/query-core zustand use-sync-external-store

Quick Start

import { createQueryClient, getQueryStore, useQuery, useMutation } from "@yebichu/zustand-query";

// 1. Create and set the QueryClient
const client = createQueryClient();
getQueryStore().setClient(client);

// 2. Use in components
function useTodos() {
  return useQuery({
    queryKey: ["todos"],
    queryFn: () => fetch("/api/todos").then((r) => r.json()),
  });
}

function useAddTodo() {
  return useMutation({
    mutationFn: (text: string) =>
      fetch("/api/todos", { method: "POST", body: JSON.stringify({ text }) }).then((r) => r.json()),
  });
}

API

createQueryClient(options?)

Creates a TanStack Query QueryClient instance.

createQueryStore(client?)

Creates a Zustand vanilla store with React Query integration.

getQueryStore()

Returns the singleton query store. Use setClient() to initialize.

useQuery(options)

React hook for queries. Supports all TanStack Query options.

useMutation(options)

React hook for mutations. Returns mutate, mutateAsync, reset.

useQueryClient()

Returns the current QueryClient instance.

useQueryClientActions()

Returns store actions: invalidateQueries, resetQueries, cancelQueries, setQueryData.

createServerQueryClient(options?)

Creates a QueryClient configured for SSR (staleTime: 0, gcTime: 5min).

DevTools

import { createQueryDevToolsPlugin } from "@yebichu/zustand-query/devtools";

const store = createQueryStore();
const devToolsPlugin = createQueryDevToolsPlugin(client);

License

MIT