Generate a TypeScript client
The octopus gen command reads your services' API specs and generates artifacts
from them: an intermediate Octopus schema, optional Octopus config fragments, and
a TypeScript client with a namespace-chained API and
TanStack Query hooks. This guide produces a typed
client from a service's OpenAPI document.
octopus gen is driven entirely by a octopus-gen.yaml file (not your gateway
config). See the CLI overview for the full command set.
Describe the service in octopus-gen.yaml01
Create octopus-gen.yaml. At minimum it lists services; each service has a
name, a type (openapi, asyncapi, or farp), a spec source (spec for a
file/URL or endpoint for a live spec), and an upstream (host + port).
output_dir: ./generated
services:
- name: orders
type: openapi
spec: ./specs/orders.openapi.json # local file or URL
prefix: /orders
upstream:
host: orders.internal
port: 8080Turn on the TypeScript client02
Add a client block and set enabled: true. Enable TanStack Query hooks and
pick the major version (4 or 5), and configure how the generated client sends
auth.
client:
enabled: true
output_dir: ./generated/client
package_name: "@myorg/api-client"
tanstack_query:
enabled: true
version: 5
auth:
default_strategy: bearer
header: Authorization
prefix: "Bearer "Defaults if you omit fields: output_dir ./generated/client, package_name
@octopus/api-client, TanStack Query version 5, auth header Authorization
with prefix Bearer . The client can also emit WebSocket and SSE clients
(websocket, sse) when the source spec includes those channels.
(Optional) Also emit Octopus config fragments03
The same run can generate Octopus route/upstream config fragments and the intermediate schema, so the gateway config and the client stay in sync with the spec.
config:
format: yaml
split: true # one config file per service
schema:
output: octopus-schema.jsonRun the generator04
octopus gen defaults to reading octopus-gen.yaml in the working directory;
pass -c to point elsewhere.
# uses ./octopus-gen.yaml
octopus gen
# explicit path
octopus gen -c ./codegen/octopus-gen.yamlThe complete octopus-gen.yaml for this guide:
output_dir: ./generated
config:
format: yaml
split: true
schema:
output: octopus-schema.json
client:
enabled: true
output_dir: ./generated/client
package_name: "@myorg/api-client"
tanstack_query:
enabled: true
version: 5
auth:
default_strategy: bearer
header: Authorization
prefix: "Bearer "
services:
- name: orders
type: openapi
spec: ./specs/orders.openapi.json
prefix: /orders
upstream:
host: orders.internal
port: 8080Use the generated client05
The output lands under output_dir (the client under its own output_dir). The
client exposes a namespace-chained API and, with TanStack Query enabled, ready-to-use
query/mutation hooks. Install it as a local package or wire it into your frontend
build, and configure the base URL to point at your gateway.
import { createClient } from "@myorg/api-client";
const api = createClient({
baseUrl: "https://gateway.example.com",
// bearer token applied via the configured Authorization header
getToken: () => localStorage.getItem("access_token") ?? "",
});
const order = await api.orders.getOrder({ id: "42" });The generated client targets the gateway, so it pairs naturally with
JWT-secured routes: the auth block above sends
the bearer token the gateway validates.
See also06
CLI —
octopus serve,validate,gen,crd, and configuration loading.Auto-discover services with FARP — the
farpservice type generates from live discovery.Secure an API with JWT — securing the routes the client calls.