@koyori-app/openapi-vue-query

Thin TanStack Vue Query helpers built on openapi-fetch. Fully type-safe queries and mutations derived from your OpenAPI schema.

Installation

pnpm add @koyori-app/openapi-vue-query openapi-fetch @tanstack/vue-query

vue, @tanstack/vue-query, openapi-fetch, and openapi-typescript-helpers are peer dependencies. Generate your paths types with openapi-typescript.

Usage

Create a typed fetch client, wrap it once, and reuse the returned client anywhere:

// api.ts
import createFetchClient from "openapi-fetch";
import { createClient } from "@koyori-app/openapi-vue-query";
import type { paths } from "./my-openapi"; // generated by openapi-typescript

const fetchClient = createFetchClient<paths>({ baseUrl: "https://api.example.com" });

export const $api = createClient(fetchClient);

<script setup lang="ts">
import { $api } from "./api";

// Query — path/method/params are all type-checked against the schema.
const { data, isLoading, error } = $api.useQuery("get", "/pets/{petId}", {
  params: { path: { petId: 1 } },
});

// Mutation
const createPet = $api.useMutation("post", "/pets");
</script>

API

• createClient(fetchClient) — wrap an openapi-fetch client and return the helpers below.
• queryOptions(method, path, init?, options?) — build options for useQuery/prefetchQuery.
• useQuery(method, path, init?, options?, queryClient?)
• useSuspenseQuery(method, path, init?, options?, queryClient?) — alias for useQuery; wrap the component in <Suspense> (Vue Query v5 has no dedicated suspense query).
• useInfiniteQuery(method, path, init, options, pageParamName?, queryClient?)
• useMutation(method, path, options?, queryClient?)
• createQueryKey(method, path, init?) — produce the [method, path, init] query key directly.
• OpenApiVueQueryError — error thrown when an openapi-fetch request fails.

Notes

• Query keys follow [method, path, init], matching the documented openapi-react-query shape.
• Errors from openapi-fetch are re-thrown as OpenApiVueQueryError, so Vue Query callers can rely on thrown errors.
• The package is intentionally a thin wrapper and keeps openapi-fetch as the source of request typing.

License

MIT

Acknowledgements

A clean-room implementation modeled on the public API shape of the following projects (no source code was copied). Thanks for the excellent design.

• openapi-react-query — © Martin Paucot, MIT License. The source of the [method, path, init] query key and hooks API shape.
• openapi-fetch / openapi-typescript — © Drew Powers and contributors, MIT License. The request-typing foundation.