@reno-stack/hono-react-query v0.0.3

@reno-stack/hono-react-query

A utility library for integrating Hono RPC endpoints with React Query in your React applications.

Features

• Type-safe: Leverages Hono and React Query types for full type safety.
• Simple API: Easily create query and mutation options from your Hono endpoints.

Installation

npm install @reno-stack/hono-react-query
pnpm install @reno-stack/hono-react-query
yarn add @reno-stack/hono-react-query

Usage

React Query has a feature called QueryOptions which is basically for creating reusable queryFn and queryKeys. By taking advantage of this. This utility gives you two functions called createHonoQueryOptions and createHonoMutationOptions. Here's how you'd use them:

For each route of our application, we'll create a {route}.queries.ts under a folder named queries in our web application (these naming conventions are arbitrary and can be changed to anything that you'd like)

Let's say we have a notes route and we want to create a query and a mutation for it. In notes.queries.ts, you would have something like this:

import { client } from "../utils/hono-client";

import {
  createHonoMutationOptions,
  createHonoQueryOptions,
} from "@reno-stack/hono-react-query";

export const notesQueryOptions = createHonoQueryOptions(
  ["notes"],
  client.notes.$get
);

export const noteByIdQueryOptions = createHonoQueryOptions(
  ({ param: { id } }) => ["notes", id],
  client.notes[":id"].$get
);

export const createNoteMutationOptions = createHonoMutationOptions(
  client.notes.$post
);

We only need to pass the endpoint returned from our Hono RPC's client and the rest is handled by the utility. This utility takes cares of the problems mentioned above and here's how we would use them:

Queries

For an endpoint that doesn't take any parameters, you can just do:

const notesQuery = useQuery(notesQueryOptions());

Simple as that! and when it's time to invalidate any of these queries, you could do something like:

await queryClient.invalidateQueries({
  queryKey: notesQueryOptions().queryKey,
});

However if your endpoint takes parameters, you can do:

const noteByIdQuery = useQuery(
  noteByIdQueryOptions({ param: { id } }, { enabled: !!id })
);

As you can see, the first argument (which is required) is the parameters for the endpoint and the second argument is the options for the query.

Mutations

Here's how you'd use the createNoteMutationOptions function defined earlier:

const createNoteMutation = useMutation(createNoteMutationOptions());

And when it's time for mutating, you can do:

createNoteMutation.mutate({ title: "New Note", content: "This is a new note" });

Note: By default, this utility prioritizes the json property for the body of the request. If your endpoint doesn't have a json property, you can pass whatever is in the body of the request as the first argument. However, let's say your endpoint takes a form property, then you can do:

createNoteMutation.mutate({
  form: { title: "New Note", content: "This is a new note" },
});

What problem does this utility solve?

Let's say we have a notes router and we want to use Hono RPC alongside React Query, this is the simplest approach that could get us started:

const notesQuery = useQuery({
  queryKey: ["notes"],
  queryFn: () => client.notes.$get(),
});

Simple enough, right? Except the fetch API (which Hono RPC uses under the hood) doesn't handle errors by default, so we'd need some sort of fetch wrapper that takes care of errors, okay...

// Let's say you made a general purpose and type-safe wrapper around fetch
const fetchWrapper = (endpoint: ...) => {...}

const  notesQuery = useQuery({
queryKey: ["notes"],
queryFn: () => fetchWrapper(client.notes.$get)
});

Now this may seem like it's fully type-safe, but it can get annoying. What if some of our endpoints occasionally return errors? We'd have to do something like InferResponseType<typeof client.notes.$get, 200> to get the success payload type. Not to mention you'd have to do the same for mutations and their error types.

This will result in a lot of repetition in the long run, fetchWrapper is repeated every time and perhaps the worst of all, our queryKey is a magical array. If we want to invalidate it somewhere else, we have no safe way of accessing it, unless we create a central file for keeping the keys.

As explained above in the Usage section, this utility solves all of these problems by providing a simple and type-safe API.