kubb-react-query

Stand up a fully-typed React Query data layer from an OpenAPI/Swagger spec using the Kubb CLI. A separate API server emits a vendored spec; Kubb generates types, zod schemas, a fetch client, and TanStack Query hooks into a dedicated packages/<svc>-api package; the app lists and mutates data only through those generated hooks.

Inputs

• A service name (e.g. crm, billing) → becomes packages/<svc>-api.
• A path to the API server's OpenAPI/Swagger JSON to vendor as the spec.
• The monorepo's package scope (e.g. @acme).
• Which seam packages to depend on: shared @cogs/* or locally-generated.

What it does

• Scaffolds packages/<svc>-api/ (config, package.json with subpath exports, tsconfig, spec placeholder) via bin/add-api-client.mjs.
• Encodes the 9 invariants that keep every repo's setup identical (see SKILL.md): vendored spec, one package per service, two seam packages, tag grouping, name transformers, idempotent codemod, hook-only consumption, CI drift check.
• Ships reference templates and the seam implementations (@cogs/fetch-client, @cogs/react-query).

Scaffold directly

node bin/add-api-client.mjs crm \
  --scope @acme \
  --spec ../../apps/api/openapi.json \
  --seams cogs

Add --dry-run to preview. It refuses to overwrite an existing package.

Install globally

Symlink into your global skills the same way as the other next-starters skills:

skills add [email protected]:catesandrew/next-starters.git \
  --skill skills/kubb-react-query -g

Layout

kubb-react-query/
  SKILL.md                     the 9 invariants + decision procedure
  metadata.json
  agents/openai.yaml
  references/
    kubb.config.ts             canonical annotated config
    api-client.package.json    package manifest + exports map
    tsconfig.json
    consumption.md             list + mutate + invalidate examples
    ci-drift-check.md          the regeneration drift job
    ARCHITECTURE.md            full rationale for each invariant

The scaffolder lives at next-starters/bin/add-api-client.mjs.