Skip to Content

useApiClient

Hook that returns a typed client for your app’s own API, generated from the handler files. Each function returns exactly what the handler returned.

Usage

app/orders/[id]/page.tsx
import { useParams } from "react-router-dom"; import { useApiClient } from "app/api"; import { useRequest } from "app/hooks"; export default function OrderPage() { const { id } = useParams(); const api = useApiClient(); const { data: order } = useRequest(() => api.orders.detail(Number(id)), { refreshDeps: [id] }); return <h1>Order {order?.id}</h1>; }

useApiClient is a hook: call it at the top of a component, not inside an event handler or a loop.

Signature

app/api.ts
export type ApiClient = ReturnType<typeof buildClient>; export function useApiClient(): ApiClient;

manh.run regenerates app/api.ts on every build. Don’t edit it.

Parameters

None.

Returns

An object with one function per handler file. Function names come from the file path:

  • app/orders/get.ts → api.orders.list(params?)
  • app/orders/post.ts → api.orders.create(body)
  • app/orders/[id:int]/get.ts → api.orders.detail(id)
  • app/orders/[id:int]/patch.ts or put.ts → api.orders.update(id, body)
  • app/orders/[id:int]/delete.ts → api.orders.remove(id)
  • app/orders/[id:int]/approve/post.ts → api.orders.approve(id, body)
  • app/classes/[id:int]/attendance-export/get.ts declaring schema = { query } → api.classes.attendanceExport(id, params?)
  • app/reports/sales/get.ts → api.reports.sales(params?)
  • Every static folder after the resource is a group, and path params become arguments in order: app/courses/[id:int]/assistants/[instructorId:int]/delete.ts → api.courses.assistants.remove(id, instructorId). Add app/courses/[id:int]/assistants/post.ts and it joins the same group: api.courses.assistants.post(id, body)
  • Dashed folders become camelCase: app/chat-messages/get.ts → api.chatMessages.list()
  • put, patch and delete without an id keep the method name: app/settings/put.ts → api.settings.put(body)
  • A sub-folder with several handlers becomes a group, each handler under its CRUD name: app/me/prefs/get.ts + app/me/prefs/patch.ts → api.me.prefs.list() + api.me.prefs.patch(body)
  • Two handlers that still want one name ([id:int]/put.ts + [id:int]/patch.ts) are a check error, code.api-name-collision, naming both files. Keep one, or move one into its own sub-folder (app/orders/[id:int]/reprice/patch.ts → api.orders.reprice(id, body)).

Path parameters accept string | number. GET and DELETE functions without an id take params (the query string); with an id they take params after the id when the handler declares query in its schema; POST, PUT and PATCH take body. Every write (POST, PUT, PATCH, DELETE) takes an optional last argument opts?: ApiCallOptions, which holds idempotencyKey for now.

Each function returns a Promise of exactly what the handler returned: list handlers return { data, total }, detail, create and update handlers return the row. Don’t add .data.

When the server answers with an error, the promise rejects with an axios error; the error body is at e.response.data as { error, message, code }. manh.run’s busy answers add retryable, retryAfterSeconds and requestId (see Error codes).

Examples

Feeding the client to a hand-written ProTable:

app/orders/page.tsx
<ProTable<Order> rowKey="id" columns={orderColumns} request={tableRequest(api.orders.list)} />

tableRequest turns the table’s paging, sorting, filters and search box into the list endpoint’s query.

  • After signIn, every call sends Authorization: Bearer <token>. Don’t add the header yourself.
  • Calling a function that isn’t in the client is a check error. Read app/api.ts for the real names.
  • The client runs on the same axios instance as useApi, so reads that get a busy answer retry and an expired session goes back to /login here too.
  • Writes retry only with an idempotencyKey. Keep one key per submit (also when the user clicks again on a slow network), and change it once the call went through:
app/orders/order-form.tsx
const key = useRef(crypto.randomUUID()); await api.orders.create(values, { idempotencyKey: key.current }); key.current = crypto.randomUUID(); // sent: the next submit is a new order

The key reaches the handler as the Idempotency-Key header. A handler that must never write twice stores the key with the row (a unique column) and returns the existing row when the key comes back.

Next steps

  • API handlers: what the handler returns is what the client gets.
  • useRequest: call the client when the page opens and keep data, loading.
  • submit: send forms through the client.
Last updated