diff --git a/README.md b/README.md index 3ed1c6d..f5655f0 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: 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 | +|---|---|---|---|---|---| +| 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` },