Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
91 changes: 85 additions & 6 deletions docs/astro.config.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -2,10 +2,27 @@ import { satteri } from "@astrojs/markdown-satteri";
import starlight from "@astrojs/starlight";
// @ts-check
import { defineConfig } from "astro/config";
import starlightLlmsTxt from "starlight-llms-txt";

const site = "https://orqc.7nohe.dev";
const ogUrl = new URL("og.jpg", site).href;
const ogImageAlt = "OpenAPI React Query Codegen";
const repo = "https://github.com/7nohe/openapi-react-query-codegen";

// What a model reads first in /llms.txt, before it decides which of the
// documentation sets below to fetch.
const llmsDescription =
"`@7nohe/openapi-react-query-codegen` is a CLI (`orqc`; `openapi-rq` also works) that generates TanStack Query v5 (React Query) hooks from an OpenAPI 3.0/3.1 specification. It generates a TypeScript HTTP client (fetch or axios) in `<output>/requests/`, then generates typed `useQuery`, `useSuspenseQuery`, `useInfiniteQuery` and `useMutation` hooks, `queryOptions` factories, `prefetchQuery` / `ensureQueryData` helpers and query key functions in `<output>/queries/`.";

const llmsDetails = `Key facts for agents:

- Install: \`npm install -D @7nohe/openapi-react-query-codegen@beta\` (v4 is in beta; without \`@beta\` npm installs v3) and \`npm install @tanstack/react-query\`. Only the scoped package belongs to this project.
- Run: \`orqc -i ./openapi.yaml -o ./src/openapi\`. Keep the flags in a package.json script and always pass the same ones.
- Do not edit generated files. Change the spec or the flags and regenerate.
- \`--check\` changes no existing file and exits 1 when the committed output is out of date, which makes it a CI drift check.
- \`--json\` prints failures as one line of JSON on stderr: \`{"code","message","details"}\`. Exit codes: 0 ok, 1 out of date, 2 error.
- The npm package ships an \`AGENTS.md\` with the full flag table, the generated layout, naming conventions and error codes.
- Every page of the documentation is also served as Markdown: drop the trailing slash of its address and add \`.md\`, as in https://orqc.7nohe.dev/guides/usage.md.`;

// https://astro.build/config
export default defineConfig({
Expand All @@ -22,6 +39,7 @@ export default defineConfig({
integrations: [
starlight({
title: "OpenAPI React Query Codegen",
routeMiddleware: "./src/routeData.ts",
customCss: [
"@fontsource-variable/ibm-plex-sans/wght.css",
"@fontsource/ibm-plex-mono/400.css",
Expand All @@ -32,12 +50,71 @@ export default defineConfig({
Banner: "./src/components/Banner.astro",
Hero: "./src/components/Hero.astro",
},
social: [
{
icon: "github",
label: "GitHub",
href: "https://github.com/7nohe/openapi-react-query-codegen",
},
social: [{ icon: "github", label: "GitHub", href: repo }],
plugins: [
// Builds /llms.txt, /llms-full.txt and /llms-small.txt from the pages,
// so they cannot fall behind the documentation.
starlightLlmsTxt({
description: llmsDescription,
details: llmsDetails,
customSets: [
{
label: "Getting started and usage",
description:
"install, first run, the generated layout, using the generated hooks and queryOptions factories, every CLI option, mock data and MSW handlers, CI checks and coding agents",
paths: [
"guides/introduction",
"guides/usage",
"guides/cli-options",
"guides/mocking",
"guides/ci-and-agents",
],
},
{
label: "Examples",
description:
"Vite + React, Next.js, TanStack Router and React Router",
paths: ["examples/**"],
},
{
label: "Migration guides",
description:
"from v2 to v3, from v3 to v4, and from openapi-typescript + openapi-react-query",
paths: ["guides/migrating-*"],
},
{
label: "Benchmarks",
description:
"generation time, install size and type errors compared with other generators, and what a coding agent spends",
paths: ["guides/benchmarks"],
},
],
promote: [
"index*",
"guides/introduction",
"guides/usage",
"guides/cli-options",
"guides/mocking",
"guides/ci-and-agents",
],
demote: ["guides/migrating-to-v3", "contributing", "license"],
exclude: ["guides/migrating-to-v3", "contributing", "license"],
// The link Starlight puts next to every heading.
customSelectors: { all: [".sl-anchor-link"] },
optionalLinks: [
{
label: "AGENTS.md",
url: `${repo}/blob/main/AGENTS.md`,
description:
"agent guide, also at `node_modules/@7nohe/openapi-react-query-codegen/AGENTS.md`",
},
{ label: "Source code", url: repo },
{
label: "npm package",
url: "https://www.npmjs.com/package/@7nohe/openapi-react-query-codegen",
},
],
}),
],
head: [
{
Expand All @@ -48,6 +125,8 @@ export default defineConfig({
tag: "meta",
attrs: { property: "og:image:alt", content: ogImageAlt },
},
{ tag: "meta", attrs: { property: "og:image:width", content: "1415" } },
{ tag: "meta", attrs: { property: "og:image:height", content: "743" } },
],
sidebar: [
{
Expand Down
1 change: 1 addition & 0 deletions docs/package.json
Original file line number Diff line number Diff line change
Expand Up @@ -17,6 +17,7 @@
"@fontsource/ibm-plex-mono": "5.3.0",
"astro": "~7.4.5",
"sharp": "^0.35.5",
"starlight-llms-txt": "0.12.0",
"typescript": "^5.6.3"
}
}
36 changes: 0 additions & 36 deletions docs/public/llms.txt

This file was deleted.

4 changes: 4 additions & 0 deletions docs/public/robots.txt
Original file line number Diff line number Diff line change
@@ -0,0 +1,4 @@
User-agent: *
Allow: /

Sitemap: https://orqc.7nohe.dev/sitemap-index.xml
2 changes: 1 addition & 1 deletion docs/src/content/docs/examples/nextjs.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
---
title: Next.js Example
description: A simple example of using Next.js with OpenAPI React Query Codegen.
description: A Next.js App Router example that prefetches on the server and hydrates TanStack Query hooks generated from an OpenAPI document.
---

Example of using Next.js can be found in the [`examples/nextjs-app`](https://github.com/7nohe/openapi-react-query-codegen/tree/main/examples/nextjs-app) directory of the repository.
2 changes: 1 addition & 1 deletion docs/src/content/docs/examples/react-router.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
---
title: React Router Example
description: A simple example of using React Router 8 (framework mode) with OpenAPI React Query Codegen.
description: A React Router 8 (framework mode) example that loads data with TanStack Query code generated from an OpenAPI document.
---

Example of using React Router 8 in framework mode can be found in the [`examples/react-router-app`](https://github.com/7nohe/openapi-react-query-codegen/tree/main/examples/react-router-app) directory of the repository.
Expand Down
2 changes: 1 addition & 1 deletion docs/src/content/docs/examples/tanstack-router.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
---
title: TanStack Router Example
description: Using TanStack Router with OpenAPI React Query Codegen for data loading and prefetching.
description: Use TanStack Router loaders with the generated ensureQueryData and prefetch functions to load and prefetch data from an OpenAPI API.
---

Example of using TanStack Router can be found in the [`examples/tanstack-router-app`](https://github.com/7nohe/openapi-react-query-codegen/tree/main/examples/tanstack-router-app) directory of the repository.
Expand Down
2 changes: 1 addition & 1 deletion docs/src/content/docs/examples/vite-react.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
---
title: Vite + React Example
description: A simple example of using Vite with React.
description: A Vite + React example app that calls an API through TanStack Query hooks generated from an OpenAPI document.
---

Example of using Vite with React can be found in the [`examples/react-app`](https://github.com/7nohe/openapi-react-query-codegen/tree/main/examples/react-app) directory of the repository.
2 changes: 1 addition & 1 deletion docs/src/content/docs/guides/ci-and-agents.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -128,4 +128,4 @@ The block goes into the instructions file at the root because that is what an ag
## Coding agents: AGENTS.md and llms.txt

- The npm package ships an [`AGENTS.md`](https://github.com/7nohe/openapi-react-query-codegen/blob/main/AGENTS.md). After installing, it is at `node_modules/@7nohe/openapi-react-query-codegen/AGENTS.md`. It covers installation, every CLI flag, the generated file layout, naming conventions for the generated hooks, and the error codes above. You can point your project's own `AGENTS.md` or `CLAUDE.md` at it.
- This site serves an [`llms.txt`](/llms.txt) with a short project summary and links to these docs.
- This site serves an [`llms.txt`](/llms.txt) with a short project summary, and the whole documentation as Markdown in one file: [`llms-full.txt`](/llms-full.txt), or [`llms-small.txt`](/llms-small.txt) without the pages few projects need. Every page is also served as Markdown at its own address with `.md` in place of the trailing slash, such as [`/guides/usage.md`](/guides/usage.md).
4 changes: 2 additions & 2 deletions docs/src/content/docs/guides/cli-options.mdx
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
---
title: CLI Options
description: CLI options for OpenAPI React Query Codegen.
description: "Every orqc command line option with its default: input and output, infinite query pagination, fetch or axios client, enums, dates, schemas, --mock, --check, --json, --agentsMd and the exit codes."
---

## Options
Expand All @@ -21,7 +21,7 @@ Name of the query parameter used for pagination (infinite query). The default va

Name of the response parameter used for next page. The default value is `nextPage`.

## --initialPageParam \<value\>
### --initialPageParam \<value\>

Initial page value to infinite query. The default value is `1`.

Expand Down
2 changes: 1 addition & 1 deletion docs/src/content/docs/guides/introduction.mdx
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
---
title: Introduction
description: OpenAPI React Query Codegen is a code generator for creating React Query (also known as TanStack Query) hooks based on your OpenAPI schema.
description: Install OpenAPI React Query Codegen, generate TanStack Query (React Query) hooks and a typed fetch or axios client from an OpenAPI 3 (Swagger) document, and call your first endpoint.
---
import { Code, Tabs, TabItem, FileTree } from '@astrojs/starlight/components';

Expand Down
2 changes: 1 addition & 1 deletion docs/src/content/docs/guides/migrating-to-v3.mdx
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
---
title: Migrating to v3
description: Migration guide from v2 to v3 of OpenAPI React Query Codegen.
description: "Upgrade OpenAPI React Query Codegen from v2 to v3: queryOptions factories, error responses that reject, and the breaking changes to infinite queries."
---

v3 is a full rewrite of the code generator on top of a ts-morph pipeline, but the generated output is intentionally kept compatible with v2. For most projects, migrating means updating the package and regenerating — no code changes.
Expand Down
2 changes: 1 addition & 1 deletion docs/src/content/docs/guides/migrating-to-v4.mdx
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
---
title: Migrating to v4
description: Migration guide from v3 to v4 of OpenAPI React Query Codegen.
description: "Upgrade OpenAPI React Query Codegen from v3 to v4: the generator's own TypeScript client replaces @hey-api/openapi-ts, with what changes in naming, types, dates and dependencies."
---

v4 replaces `@hey-api/openapi-ts` with a client generator that ships inside this package. The generated **hooks are unchanged** — same names, same signatures, same query keys — so for most projects migrating means updating the package, regenerating, and checking the handful of differences below.
Expand Down
2 changes: 1 addition & 1 deletion docs/src/content/docs/guides/usage.mdx
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
---
title: Usage
description: Usage of OpenAPI React Query Codegen.
description: How to use the generated useQuery, useSuspenseQuery, useMutation and useInfiniteQuery hooks, the queryOptions factories and the query keys in a React app.
---

After generating the React Query hooks and functions, you can start using them in your React application.
Expand Down
13 changes: 12 additions & 1 deletion docs/src/content/docs/index.mdx
Original file line number Diff line number Diff line change
@@ -1,7 +1,18 @@
---
title: OpenAPI React Query Codegen
description: Generate TanStack Query hooks, query options and a typed client from an OpenAPI document with one command.
description: Generate TanStack Query (React Query) hooks, queryOptions factories and a typed fetch or axios client from an OpenAPI document with one command.
template: splash
head:
- tag: title
content: "OpenAPI React Query Codegen (orqc): TanStack Query hooks from OpenAPI"
- tag: meta
attrs:
property: og:type
content: website
- tag: script
attrs:
type: application/ld+json
content: '{"@context":"https://schema.org","@graph":[{"@type":"WebSite","@id":"https://orqc.7nohe.dev/#website","url":"https://orqc.7nohe.dev/","name":"OpenAPI React Query Codegen","alternateName":"orqc"},{"@type":"SoftwareApplication","@id":"https://orqc.7nohe.dev/#software","name":"OpenAPI React Query Codegen","alternateName":["orqc","@7nohe/openapi-react-query-codegen"],"description":"Generate TanStack Query (React Query) hooks, queryOptions factories and a typed fetch or axios client from an OpenAPI document with one command.","url":"https://orqc.7nohe.dev/","applicationCategory":"DeveloperApplication","operatingSystem":"Node.js","license":"https://opensource.org/license/mit","isAccessibleForFree":true,"offers":{"@type":"Offer","price":"0","priceCurrency":"USD"},"downloadUrl":"https://www.npmjs.com/package/@7nohe/openapi-react-query-codegen","author":{"@type":"Person","name":"Daiki Urata","url":"https://github.com/7nohe"},"sameAs":["https://github.com/7nohe/openapi-react-query-codegen","https://www.npmjs.com/package/@7nohe/openapi-react-query-codegen"]}]}'
hero:
title: Your OpenAPI document, as TanStack Query hooks
tagline: One command turns every operation into typed hooks, query options and prefetch helpers, together with the client they call.
Expand Down
27 changes: 27 additions & 0 deletions docs/src/pages/[...slug].md.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,27 @@
import { type CollectionEntry, getCollection } from "astro:content";
import type { APIRoute, GetStaticPaths } from "astro";
// The plugin does not export its page-to-Markdown conversion, and it is the
// same one that builds /llms-full.txt. The plugin version is pinned, so a
// release that moves this file fails the build instead of changing the output.
import { entryToSimpleMarkdown } from "../../node_modules/starlight-llms-txt/entryToSimpleMarkdown";

export const prerender = true;

/** Every page as Markdown at its own address plus `.md`, for agents. */
export const getStaticPaths: GetStaticPaths = async () => {
const docs = await getCollection("docs", (doc) => !doc.data.draft);
return docs.map((doc) => ({ params: { slug: doc.id }, props: { doc } }));
};

export const GET: APIRoute<{ doc: CollectionEntry<"docs"> }> = async (
context,
) => {
const { doc } = context.props;
const segments = [`# ${doc.data.hero?.title || doc.data.title}`];
const description = doc.data.hero?.tagline || doc.data.description;
if (description) segments.push(`> ${description}`);
segments.push(await entryToSimpleMarkdown(doc, context, false));
return new Response(`${segments.join("\n\n")}\n`, {
headers: { "Content-Type": "text/markdown; charset=utf-8" },
});
};
57 changes: 57 additions & 0 deletions docs/src/routeData.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,57 @@
import { defineRouteMiddleware } from "@astrojs/starlight/route-data";

const siteName = "OpenAPI React Query Codegen";

/**
* Adds to every page a link to its Markdown version and, except on the home
* page (which describes the software in its frontmatter), structured data
* that says which site the page belongs to.
*/
export const onRequest = defineRouteMiddleware((context) => {
const { entry, head } = context.locals.starlightRoute;
const site = context.site;
// The 404 page has no Markdown version and nothing to describe.
if (!site || entry.id === "404") return;

// Starlight gives the home page an empty id.
const id = entry.id || "index";
const isHome = id === "index";
const page = new URL(isHome ? "/" : `/${id}/`, site).href;
head.push({
tag: "link",
attrs: {
rel: "alternate",
type: "text/markdown",
href: new URL(`/${id}.md`, site).href,
},
});
if (isHome) return;

const home = new URL("/", site).href;
head.push({
tag: "script",
attrs: { type: "application/ld+json" },
content: JSON.stringify({
"@context": "https://schema.org",
"@graph": [
{
"@type": "TechArticle",
"@id": `${page}#article`,
headline: entry.data.title,
description: entry.data.description,
url: page,
inLanguage: "en",
isPartOf: { "@id": `${home}#website` },
about: { "@id": `${home}#software` },
},
{
"@type": "BreadcrumbList",
itemListElement: [
{ "@type": "ListItem", position: 1, name: siteName, item: home },
{ "@type": "ListItem", position: 2, name: entry.data.title },
],
},
],
}),
});
});
21 changes: 21 additions & 0 deletions docs/vercel.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,21 @@
{
"$schema": "https://openapi.vercel.sh/vercel.json",
"headers": [
{
"source": "/(.*)\\.md",
"headers": [{ "key": "X-Robots-Tag", "value": "noindex" }]
},
{
"source": "/llms-full\\.txt",
"headers": [{ "key": "X-Robots-Tag", "value": "noindex" }]
},
{
"source": "/llms-small\\.txt",
"headers": [{ "key": "X-Robots-Tag", "value": "noindex" }]
},
{
"source": "/_llms-txt/(.*)",
"headers": [{ "key": "X-Robots-Tag", "value": "noindex" }]
}
]
}
Loading
Loading