From 7026fec6cd2be62b2970d65d4d94d3e5f981107b Mon Sep 17 00:00:00 2001 From: Urata Daiki <7nohe@users.noreply.github.com> Date: Sun, 15 Nov 2026 13:05:51 +0900 Subject: [PATCH 1/2] docs: show when each page was last updated, and align the README comparison - Every docs page shows "Last updated", and its TechArticle JSON-LD carries dateModified, both from git. They are off in a shallow clone, like the sitemap dates, which would otherwise date most pages to the oldest commit fetched. - The README comparison table now matches the Comparison page: Kubb is in it, suspense, prefetch and ensureQueryData are rows of their own, and the release line, configuration and CI check are listed. The "hierarchical keys / tags" row is gone, as nothing on the Comparison page backs it. The footnote dates the measured rows and the feature rows separately, and the scope note points non-React users to Orval, Kubb or Hey API. --- README.md | 40 +++++++++++++++++++++++---------------- docs/astro.config.mjs | 5 ++++- docs/src/lastModified.mjs | 3 ++- docs/src/routeData.ts | 3 ++- 4 files changed, 32 insertions(+), 19 deletions(-) diff --git a/README.md b/README.md index 3ed1c6d..889e5fe 100644 --- a/README.md +++ b/README.md @@ -80,22 +80,30 @@ See the [documentation](https://orqc.7nohe.dev) for [CLI options](https://orqc.7 ## How it compares -| | This library | @hey-api tanstack-query plugin | Orval | openapi-react-query | -|---|---|---|---|---| -| `queryOptions` / `infiniteQueryOptions` factories (TanStack v5 pattern) | ✅ | ✅ | ✅ (`getXxxQueryOptions`) | ✅ (`$api.queryOptions`) | -| Ready-to-use hooks (`useQuery` / suspense / infinite variants) | ✅ generated per operation | ❌ (options only) | ✅ | ✅ runtime wrapper (method + path strings) | -| SSR helpers (`prefetchQuery` / `prefetchInfiniteQuery` / `ensureQueryData`) | ✅ | ❌ | Partial (`usePrefetch`) | Not provided (use `queryOptions`) | -| Hierarchical query keys for granular invalidation | ✅ | ✅ (tags) | Partial | Not documented | -| Stable release line | ✅ SemVer | pre-1.0, frequent breaking changes | ✅ | ⚠️ upstream openapi-typescript is in [maintenance mode](https://github.com/openapi-ts/openapi-typescript/issues/2874) | -| MSW mock generation | ✅ (`--mock msw`, fixed values) | ❌ | ✅ (random values with Faker) | ❌ | -| Vue / Solid / Svelte / Angular | ❌ React-focused | ✅ | ✅ | ❌ | -| Generation time, GitHub REST API (1,272 operations)¹ | **0.46 s** | 2.98 s | 4.31 s | 2.10 s | -| Packages added by installing the generator¹ | **9** (2.1 MB) | 51 (10.8 MB) | 89 (101.5 MB) | 35 (20.5 MB) | -| Type errors in the generated code, Stripe / GitHub APIs¹ | **0 / 0** | 274 / 0 | 219 / 1 | 0 / 0 | - -¹ Measured on 2026-11-13 on an Apple M2 with Node.js 24 (generation time is the median wall-clock time of the CLI), with 4.0.0-beta.4, `@hey-api/openapi-ts` 0.99.0, Orval 8.46.0 and openapi-typescript 7.13.0 + openapi-react-query 0.5.4. Methods, the other specifications and type-checking times are on the [Benchmarks](https://orqc.7nohe.dev/guides/benchmarks/) page; the scripts are in [`benchmarks/`](./benchmarks). The [Comparison](https://orqc.7nohe.dev/guides/comparison/) page covers Kubb too, and what each tool generates in more detail. - -**Scope**: this library is deliberately React-focused — use the hey-api plugin if you need non-React frameworks. Its [MSW mocks](https://orqc.7nohe.dev/guides/mocking/) answer with fixed values taken from the spec and keep no state; use Orval if you want randomly generated mock data. +Built only for React and TanStack Query v5: every operation gets its hooks, suspense hooks, `queryOptions` factory, prefetch and `ensureQueryData` functions from one command, with no configuration file. The [Comparison](https://orqc.7nohe.dev/guides/comparison/) page has the details and when another tool fits better. + +| | This library | Orval | Kubb | Hey API | openapi-react-query | +|---|---|---|---|---|---| +| Hooks per operation (`useQuery`, `useMutation`) | ✅ always | ✅ | With `hooks: true` | ❌ (documented output is options factories) | Runtime wrapper (`$api.useQuery("get", "/pets")`) | +| Suspense hooks | ✅ always | With `useSuspenseQuery` | With `suspense` | ❌ | ✅ (`$api.useSuspenseQuery`) | +| Prefetch functions | ✅ always | With `usePrefetch` | ❌ | ❌ | ❌ | +| `ensureQueryData` functions | ✅ always | ❌ | ❌ | ❌ | ❌ | +| `queryOptions` factories (TanStack v5 pattern) | ✅ | ✅ (`getXxxQueryOptions`) | ✅ | ✅ | ✅ (`$api.queryOptions`) | +| Query key functions | ✅ | ✅ | ✅ | ✅ | ❌ | +| Check for stale output in CI | ✅ `--check` | ✅ `--outdated` | `--dry-run` shows planned changes | ❌ | ✅ `--check` | +| Configuration | CLI flags | `orval.config.ts` | `kubb.config.ts` | `openapi-ts.config.ts` | CLI flags | +| Release line | ✅ SemVer | ✅ v8 | ✅ v5 | Before 1.0 | ⚠️ [maintenance mode](https://github.com/openapi-ts/openapi-typescript/issues/2874) | +| MSW mocks | ✅ fixed values (`--mock msw`) | ✅ random values (Faker) | ✅ random values (Faker) | In progress | ❌ | +| Vue / Svelte / Solid / Angular | ❌ React only | ✅ | Vue | ✅ | ❌ | +| Generation time, GitHub REST API (1,272 operations)¹ | **0.46 s** | 4.31 s | 2.98 s | 2.98 s | 2.10 s | +| Packages added by installing the generator¹ | **9** (2.1 MB) | 89 (101.5 MB) | 91 (37.4 MB) | 51 (10.8 MB) | 35 (20.5 MB) | +| Type errors in the generated code, Stripe / GitHub APIs¹ | **0 / 0** | 219 / 1 | 0 / 0 | 274 / 0 | 0 / 0 | + +The feature rows were checked against each tool's documentation on 2026-11-15 (Orval 8.48.0, Kubb 5.20.1 with `@kubb/plugin-react-query` 5.10.3, `@hey-api/openapi-ts` 0.99.0, openapi-react-query 0.5.4). + +¹ Measured on 2026-11-13 on an Apple M2 with Node.js 24 (generation time is the median wall-clock time of the CLI), with 4.0.0-beta.4, Orval 8.46.0, Kubb 5.15.4 with `@kubb/plugin-react-query` 5.9.0, `@hey-api/openapi-ts` 0.99.0 and openapi-typescript 7.13.0 + openapi-react-query 0.5.4. Methods, the other specifications and type-checking times are on the [Benchmarks](https://orqc.7nohe.dev/guides/benchmarks/) page; the scripts are in [`benchmarks/`](./benchmarks). + +**Scope**: this library is deliberately React-focused — use Orval, Kubb or Hey API if you need another framework. Its [MSW mocks](https://orqc.7nohe.dev/guides/mocking/) answer with fixed values taken from the spec and keep no state; use Orval or Kubb if you want randomly generated mock data. **Coming from openapi-typescript / openapi-fetch / openapi-react-query?** See the [migration guide](https://orqc.7nohe.dev/guides/migrating-from-openapi-react-query/). diff --git a/docs/astro.config.mjs b/docs/astro.config.mjs index 0992d10..5a60c0b 100644 --- a/docs/astro.config.mjs +++ b/docs/astro.config.mjs @@ -4,7 +4,7 @@ import starlight from "@astrojs/starlight"; // @ts-check import { defineConfig } from "astro/config"; import starlightLlmsTxt from "starlight-llms-txt"; -import { lastModified } from "./src/lastModified.mjs"; +import { hasHistory, lastModified } from "./src/lastModified.mjs"; const site = "https://orqc.7nohe.dev"; const ogUrl = new URL("og.jpg", site).href; @@ -50,6 +50,9 @@ export default defineConfig({ starlight({ title: "OpenAPI React Query Codegen", routeMiddleware: "./src/routeData.ts", + // "Last updated" on every page, from git. A shallow clone would date + // most pages to its oldest commit, so the dates are left out there. + lastUpdated: hasHistory, customCss: [ "@fontsource-variable/ibm-plex-sans/wght.css", "@fontsource/ibm-plex-mono/400.css", diff --git a/docs/src/lastModified.mjs b/docs/src/lastModified.mjs index b772263..b07a383 100644 --- a/docs/src/lastModified.mjs +++ b/docs/src/lastModified.mjs @@ -20,7 +20,8 @@ function git(...args) { // the date of the oldest commit that was fetched. No date is better than a // wrong one: the build host has to fetch the full history for these to appear // (on Vercel, the VERCEL_DEEP_CLONE environment variable). -const hasHistory = git("rev-parse", "--is-shallow-repository") === "false"; +export const hasHistory = + git("rev-parse", "--is-shallow-repository") === "false"; /** * When the page at `pathname` was last committed, for the sitemap. diff --git a/docs/src/routeData.ts b/docs/src/routeData.ts index 12b4c21..f8d8a2a 100644 --- a/docs/src/routeData.ts +++ b/docs/src/routeData.ts @@ -8,7 +8,7 @@ const siteName = "OpenAPI React Query Codegen"; * that says which site the page belongs to. */ export const onRequest = defineRouteMiddleware((context) => { - const { entry, head } = context.locals.starlightRoute; + const { entry, head, lastUpdated } = context.locals.starlightRoute; const site = context.site; // The 404 page has no Markdown version and nothing to describe. if (!site || entry.id === "404") return; @@ -39,6 +39,7 @@ export const onRequest = defineRouteMiddleware((context) => { "@id": `${page}#article`, headline: entry.data.title, description: entry.data.description, + ...(lastUpdated && { dateModified: lastUpdated.toISOString() }), url: page, inLanguage: "en", isPartOf: { "@id": `${home}#website` }, From 263a20d9b68f13bc40c14e2acbbf39fb80391da9 Mon Sep 17 00:00:00 2001 From: Urata Daiki <7nohe@users.noreply.github.com> Date: Sun, 15 Nov 2026 13:11:53 +0900 Subject: [PATCH 2/2] docs: say which operations get which helpers in the README intro Suspense hooks, queryOptions factories, prefetch and ensureQueryData functions are generated for GET operations; the others get a mutation hook. --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 889e5fe..f5655f0 100644 --- a/README.md +++ b/README.md @@ -80,7 +80,7 @@ See the [documentation](https://orqc.7nohe.dev) for [CLI options](https://orqc.7 ## How it compares -Built only for React and TanStack Query v5: every operation gets its hooks, suspense hooks, `queryOptions` factory, prefetch and `ensureQueryData` functions from one command, with no configuration file. The [Comparison](https://orqc.7nohe.dev/guides/comparison/) page has the details and when another tool fits better. +Built only for React and TanStack Query v5: one command, with no configuration file, gives every GET operation a query hook, a suspense hook, a `queryOptions` factory, a prefetch function and an `ensureQueryData` function, and every other operation a mutation hook. The [Comparison](https://orqc.7nohe.dev/guides/comparison/) page has the details and when another tool fits better. | | This library | Orval | Kubb | Hey API | openapi-react-query | |---|---|---|---|---|---|