reactive/data-client / .agents/skills/data-client-rest-setup
data-client-rest-setup
VerifiedSet up and migrate to @data-client/rest for REST APIs. Detects existing HTTP patterns (axios, fetch, ky, superagent, got) and migrates them. Creates custom RestEndpoint base class with common behaviors. Use when adopting @data-client/rest in a new or existing project.
REST Protocol Setup & Migration
Setting up @data-client/rest only defines endpoints and schemas, so it needs no Data Client provider: leave how the app loads and stores data alone unless the user asks to change it.
APIs: RestEndpoint, resource. Vue projects: read <name>.vue.md instead of <name>.md when it exists.
Step 1: Install
Install @data-client/rest with the project's package manager. It ships the skills this setup uses next (data-client-rest, and data-client-schema from @data-client/endpoint); link them from the project root:
npx --no data-client-skills # pnpm exec data-client-skills, yarn data-client-skills
- If a skill isn't available by name afterwards, read
.claude/skills/<skill>/SKILL.md. - If the command isn't found, the installed version predates 0.19: run
npx skills add reactive/data-client --skill data-client-rest --skill data-client-schema -yinstead. - Add this line to
AGENTS.md(create it if missing; if aCLAUDE.mdexists, make sure it has an@AGENTS.mdline), with the project's package manager in the command, and commit.agents/skillsand.claude/skills:
After adding, removing or upgrading `@data-client/*` packages, run `npx --no data-client-skills` and commit the skill links.
Step 2: Migrate each HTTP library
Check package.json and imports. Several libraries can coexist: migrate each one's files with its reference. If HTTP calls exist but the library is unclear, ask the user.
| Detected | Follow |
|---|---|
axios | Axios migration, with the steps below |
fetch( calls or wrappers around fetch | Fetch migration |
ky | Ky migration |
superagent | SuperAgent migration |
got | Got migration |
| none | Step 3 |
Axios:
- Check
git statusis clean (commit or ask first), so the codemod's changes can be reviewed on their own. - Run the codemod before any manual edits, on the source folders (never the repo root):
npx @data-client/codemods axios-to-rest src/(it reads TypeScript and skipsnode_modules). It turns each axios call into a call to an endpoint (usually a module-levelconstwhen the call is in a function), turns eachaxios.create()instance into a base endpoint class, and drops.dataunless a response interceptor may have unwrapped it. - The codemod doesn't format its output, so run the fixers the project already uses on the changed files: its
formatorlint --fixscript, or the tool its config names (such asprettier --write,eslint --fixorbiome check --write). - Search the source for
TODO(data-client). Each comment names one thing to finish and links its guide section, which is in the reference under the same heading. Resolve it, then delete the comment. - Follow the reference's remaining steps. Callers keep loading data the way they did; only the call changes.
- Run the type checker and tests. When no
axiosimport orTODO(data-client)comment is left, uninstall axios.
Step 3: Base endpoint class
Put the project's shared request behavior in one RestEndpoint subclass and build every endpoint from it. If a migration made one (the axios codemod does, from axios.create()), add to that class instead of creating another.
import { RestEndpoint, RestGenerics } from '@data-client/rest';
export class BaseEndpoint<O extends RestGenerics = any> extends RestEndpoint<O> {
urlPrefix = 'https://api.example.com';
getHeaders(headers: HeadersInit): HeadersInit {
const token = localStorage.getItem('authToken');
return { ...headers, ...(token && { Authorization: `Bearer ${token}` }) };
}
}
Override only what the app does today:
| Behavior | Override |
|---|---|
Auth, CSRF or other headers (may be async, e.g. token refresh) | getHeaders(headers) |
| Auth token from React context (Okta, Auth0) | hookifyResource(); a base class can't read context |
Cookies (axios withCredentials), other RequestInit | async getRequestInit(body) returning { ...(await super.getRequestInit(body)), credentials: 'include' }. Without await, the spread drops method, body and headers, so every mutation is sent as a GET |
A response interceptor reshapes the body without losing data: unwraps a { "data": ... } with nothing beside it, converts key case | process(value), e.g. return value?.data (null for a 204). Fields the app reads, like meta, stay in the endpoint's schema |
| Date fields | Not process(): the Entity's static schema, e.g. createdAt: Temporal.Instant.from (skill "data-client-schema") |
| Status handling, like a 401 redirect | async fetchResponse(input, init): super.fetchResponse() throws a NetworkError for any non-2xx status, so wrap it in try, check error.status in catch, and rethrow (Server error messages shows it) |
| Arrays or nested objects in the query | searchToString(searchParams), e.g. qs.stringify(searchParams, { arrayFormat: 'brackets' }) |
| Non-JSON responses (files, text) | The content option, e.g. content: 'blob'; otherwise parseResponse(response) |
Request bodies need no override: a plain object or array is sent as JSON, and anything else (FormData, URLSearchParams, a string) as-is (getRequestInit).
Defining endpoints
resource() for standard CRUD on one path (get, getList, getList.push, update, partialUpdate, delete):
export const TodoResource = resource({
path: '/todos/:id',
schema: Todo,
Endpoint: BaseEndpoint,
});
new BaseEndpoint({ ... }) for anything else (search, auth, custom actions). Type a body with a truthy value, body: {} as { email: string; password: string }, never undefined as unknown as T: body: undefined means the endpoint sends no body. Every method but GET and DELETE (including HEAD and OPTIONS) sends a body unless it sets that body: undefined, so one that sends none needs it, or its only argument is taken as the body and the path params go missing. A DELETE sends a body only when it has body, such as body: {} as { ids: string[] }, including one inherited through extend(): set body: undefined on a DELETE extended from an endpoint with a body.
If the codebase validates responses with Zod or Yup, keep that by parsing in process() and still add an Entity schema; see "Coexisting with Zod or Yup" in the Axios migration.
Next steps
- Define Entity classes (skill "data-client-schema") and set each endpoint's
schema:. Without one, responses aren't normalized or cached. - Apply skill "data-client-rest" for resource and endpoint patterns.
- Only when the user asks to move components onto the store: apply skill "data-client-react" or "data-client-vue".
Auth on the base endpoint: Authentication; with a Django backend, Django REST Framework (CSRF header).
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| receiving-code-reviewobra/superpowersUse when receiving code review feedback, before implementing suggestions, especially if feedback seems unclear or technically questionable - requires technical rigor and verification, not performative agreement or blind implementation | Stars: 319k | Updated | Claude CodeCodex | Verified | Install |
| requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirements | Stars: 319k | Updated | Claude CodeCodex | Verified | Install |
| using-git-worktreesobra/superpowersUse when starting feature work that needs isolation from current workspace or before executing implementation plans - ensures an isolated workspace exists via native tools or git worktree fallback | Stars: 319k | Updated | Claude CodeCodex | Verified | Install |
| verification-before-completionobra/superpowersUse when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions always | Stars: 319k | Updated | Claude CodeCodex | Verified | Install |