trpc-zustand

Zustand bindings for tRPC clients. Manage tRPC queries, mutations and subscriptions as Zustand stores.

trpc-zustand bridges the gap between tRPC and Zustand, allowing you to use Zustand-specific patterns to manage tRPC operations and their state, including middlewares, store slicing, selectors, React integration, and more. Fully typed and compatible with tRPC v11 and Zustand v5.

• Installation
• Setup
• Guides
• API Reference
• Contributing
• License

Installation

Install trpc-zustand and its peer dependencies @trpc/client, @trpc/server, and zustand:

npm install trpc-zustand @trpc/client @trpc/server zustand
yarn add trpc-zustand @trpc/client @trpc/server zustand
bun add trpc-zustand @trpc/client @trpc/server zustand

Setup

Create a tRPC client with createTRPCZustand:

import {
  splitLink,
  unstable_httpBatchStreamLink,
  unstable_httpSubscriptionLink
} from "@trpc/client";
import { createTRPCZustand } from "trpc-zustand";
import { create } from "zustand";
import type { AppRouter } from "./server";

const trpc = createTRPCZustand<AppRouter>({
  links: [
    splitLink({
      condition: op => op.type === "subscription",
      // In case you want subscriptions:
      true: unstable_httpSubscriptionLink({ url: "http://localhost:2022" }),
      false: unstable_httpBatchStreamLink({ url: "http://localhost:2022" })
    })
  ]
});

Then create Zustand stores using the client, one store per tRPC operation. The client returns Zustand state creators (the function that takes set and get) so it works just fine with both React- and vanilla Zustand:

import { create } from "zustand"; // React

export const useTodosStore = create(trpc.todos.getTodos.queryStore());
export const useAddTodoStore = create(trpc.todos.addTodo.mutationStore());

import { createStore } from "zustand"; // Vanilla

export const todosStore = createStore(trpc.todos.getTodos.queryStore());
export const addTodoStore = createStore(trpc.todos.addTodo.mutationStore());

You can pass initialization options to the store creator:

export const useTodosStore = create(
  trpc.todos.getTodos.queryStore({ keepPreviousData: false })
);

export const useAddTodoStore = create(
  trpc.todos.addTodo.mutationStore({ refetchStores: () => [useTodosStore] })
);

Guides

Vanilla demo

Here is an overview of the API that the tRPC stores expose. For an exhaustive list of methods and properties, see the API Reference.

import { createTRPCZustand } from "trpc-zustand";
import { createStore } from "zustand";
import type { AppRouter } from "./server";

const trpc = createTRPCZustand<AppRouter>({
  /* ... */
});

const todosStore = createStore(trpc.todos.getTodos.queryStore());
const addTodoStore = createStore(trpc.todos.addTodo.mutationStore());

// Fetch data
todosStore.getState().query({ listId: "1" });

// Refetch data (last input)
todosStore.getState().refetch();

// Disable/enable/reset a store
todosStore.getState().disable();
todosStore.getState().enable();
todosStore.getState().reset();

// Execute a mutation
addTodoStore.getState().mutate({ listId: "1", title: "Buy milk" });

// Lookup a store's state
const { data, loading, error } = todosStore.getState();
const isAddingTodo = addTodoStore.getState().loading;

// Listen to state changes
const unsubscribe = addTodoStore.subscribe((state, prevState) => {
  if (state.loading && !prevState.loading) {
    console.log("Adding todo...");
  }
});

React demo

Everything that works with vanilla stores works on React stores too. But in addition to that, you can use the store as a hook with or without custom selectors. The component will re-render when the selected store state changes. Note: if you only need methods, there is no need to use it as a hook as the methods never change.

import { createTRPCZustand } from "trpc-zustand";
import { create } from "zustand";
import type { AppRouter } from "./server";

const trpc = createTRPCZustand<AppRouter>({
  /* ... */
});

const useTodosStore = create(trpc.todos.getTodos.queryStore());
const useAddTodoStore = create(trpc.todos.addTodo.mutationStore());

function TodoList({ listId }: { listId: string }) {
  // Use the entire store
  const todos = useTodosStore();

  useEffect(() => {
    // Fetch data
    todos.query({ listId });
  }, [listId]);

  const addTodo = async () => {
    // Execute a mutation
    await useAddTodoStore.getState().mutate({ listId, title: "Buy milk" });
    // Refetch data
    await todos.refetch();
  };

  // Display query states and data
  return (
    <div>
      {todos.loading ? (
        <p>Loading...</p>
      ) : todos.error ? (
        <p>Error: {todos.error.message}</p>
      ) : (
        todos.data && (
          <ul>
            {todos.data.map(todo => (
              <li key={todo.id}>{todo.title}</li>
            ))}
          </ul>
        )
      )}
      <button onClick={addTodo}>Add todo</button>
      <Loader />
    </div>
  );
}

function Loader() {
  // Use custom selectors
  const addTodoLoading = useAddTodoStore(state => state.loading);

  return <p>addTodo is {addTodoLoading ? "loading" : "not loading"}</p>;
}

Zustand middlewares

Zustand middlewares will work like with any other Zustand store. The following example persists the data of the latest getTodos query in localStorage. When you reload the page, the data will be restored without having to refetch it.

import { create } from "zustand";
import { persist } from "zustand/middleware";

const useTodosStore = create(
  persist(trpc.todos.getTodos.queryStore(), {
    name: "todos",
    partialize: ({ data }) => ({ data })
  })
);

Refetch after mutation

You can refetch a store after a mutation by passing a refetchStores option to the mutation store:

const useTodosStore = create(trpc.todos.getTodos.queryStore());

const useAddTodoStore = create(
  trpc.todos.addTodo.mutationStore({ refetchStores: () => [useTodosStore] })
);

// Will refetch the todos store after the mutation is successful
useAddTodoStore.getState().mutate({ listId: "1", title: "Buy milk" });

refetchStores is a function that is called after the mutation is successful. Thus you can have arbitrary control over which stores are refetched and when:

const useAddTodoStore = create(
  trpc.todos.addTodo.mutationStore({
    refetchStores: () => {
      if (
        useAddTodoStore.getState().input?.listId ===
        useTodosStore.getState().input?.listId
      ) {
        return [useTodosStore];
      }
    }
  })
);

If you want to refetch after specific mutation calls only and not as a general rule, just use promise patterns:

const addTodo = async () => {
  await useAddTodoStore.getState().mutate({ listId: "1", title: "Buy milk" });
  await useTodosStore.getState().refetch();
};

Store slicing

You can compose a tRPC store with other Zustand stores using the slice pattern, as long as the properties don't conflict.

import { create, StateCreator } from "zustand";
import { createTRPCZustand, InferStore } from "trpc-zustand";
import type { AppRouter } from "./server";

const trpc = createTRPCZustand<AppRouter>({
  /* ... */
});

// Use the InferStore utility to get the store's exact state type
type DeleteTodoSlice = InferStore<typeof deleteTodoSlice>;

type AdditionalSlice = {
  foo: string;
  resetFoo: () => void;
};

const deleteTodoSlice = trpc.todos.deleteTodo.mutationStore();

const additionalSlice: StateCreator<
  DeleteTodoSlice & AdditionalSlice,
  [],
  [],
  AdditionalSlice
> = (set, get) => ({
  foo: "bar",
  resetFoo: () => set({ foo: get().loading ? "bar" : "baz" })
});

export const useDeleteTodoStore = create<DeleteTodoSlice & AdditionalSlice>(
  (...a) => ({
    ...deleteTodoSlice(...a),
    ...additionalSlice(...a)
  })
);

Subscriptions

You can use the subscribe method to start a subscription. It returns a cancellation function.

const streamTodosStore = createStore(
  trpc.todos.streamTodos.subscriptionStore()
);

// Start a tRPC subscription
const stop = streamTodosStore.getState().subscribe(
  { listId },
  {
    onData: data => {
      console.log("New todo:", data);
    },
    onError: error => {
      console.error("Error:", error);
    }
  }
);

// Stop the subscription
stop();

React-style:

const useStreamTodosStore = create(trpc.todos.streamTodos.subscriptionStore());

function TodoStream({ listId }: { listId: string }) {
  const { status, data, error, subscribe } = useStreamTodosStore();

  useEffect(() => {
    // Start a tRPC subscription
    // Note: returns the cancellation function as cleanup
    return subscribe({ listId });
  }, [listId]);

  return (
    <div>
      {error && <p>Error: {error.message}</p>}
      <p>
        ({status}) Latest todo: {data?.title}
      </p>
    </div>
  );
}

API Reference

Queries

Initialization options

Property	Type	Description
enabled	boolean	Initially enable/disable the store. Optional. Defaults to true.
keepPreviousData	boolean	Keep the previous data while a new query is being fetched. Optional. Defaults to true.

Store

Property	Type	Description
enabled	boolean	Tracks the store's enabled state.
keepPreviousData	boolean	Tracks if the previous data should be kept while a new query is being fetched.
input	TInput | undefined	The input of the last query.
loading	boolean	Tracks the query's loading state.
data	TData | undefined	The data returned by the last query.
error	TRPCClientError | undefined	The error thrown by the last query.
enable	() => void	Enables the store.
disable	() => void	Disables the store.
toggle	() => void	Toggles the store's enabled state.
reset	() => void	Resets the store.
query	(input, opts?) => Promise	Fires a query. If there is an ongoing query, it is stopped and the new one is started.
refetch	(opts?) => Promise	Refetches the last query. If there is an ongoing query, it is stopped and the new one is started.

Mutations

Initialization options

Property	Type	Description
enabled	boolean	Initially enable/disable the store. Optional. Defaults to true.
refetchStores	() => StoreApi[]	Calls the refetch method on the stores after the mutation is successful. Optional.

Store

Property	Type	Description
enabled	boolean	Tracks the store's enabled state.
input	TInput | undefined	The input of the last mutation.
loading	boolean	Tracks the mutation's loading state.
data	TData | undefined	The data returned by the last mutation.
error	TRPCClientError | undefined	The error thrown by the last mutation.
enable	() => void	Enables the store.
disable	() => void	Disables the store.
toggle	() => void	Toggles the store's enabled state.
reset	() => void	Resets the store.
mutate	(input, opts?) => Promise	Fires a mutation. If there is an ongoing mutation, it is stopped and the new one is started.

Subscriptions

Initialization options

Property	Type	Description
enabled	boolean	Initially enable/disable the store. Optional. Defaults to true.

Store

Property	Type	Description
enabled	boolean	Tracks the store's enabled state.
input	TInput | undefined	The input of the last subscription.
status	"idle" | "connecting" | "pending" | "error"	Tracks the subscription's status.
data	TData | undefined	The last data returned by the subscription.
error	TRPCClientError | undefined	The last error thrown by the subscription.
enable	() => void	Enables the store.
disable	() => void	Disables the store.
toggle	() => void	Toggles the store's enabled state.
reset	() => void	Resets the store.
subscribe	(input, opts?) => () => void	Subscribes to the last subscription. Returns a cancellation function.

Contributing

Contributions are welcome! Please open an issue or submit a pull request for any features, bug fixes, or improvements.

License

MIT