Getting Started
Set up chowbea-axios in your project in under 5 minutes.
This guide walks you through setting up chowbea-axios in a new or existing project.
Step 1: Initialize Your Project
Run the init command in your project root:
chowbea-axios initYou'll be prompted for:
- OpenAPI spec endpoint URL - Where your API documentation is served
- Output folder - Where generated files will be placed (default:
app/services/api) - Package manager - Detected automatically, but you can override
The init command automatically installs axios, adds npm scripts, and generates client files.
What Gets Created
After running init, your project will have:
NPM Scripts Added
The init command adds these scripts to your package.json:
{
"scripts": {
"api:fetch": "chowbea-axios fetch",
"api:generate": "chowbea-axios generate",
"api:watch": "chowbea-axios watch",
"api:status": "chowbea-axios status",
"api:validate": "chowbea-axios validate",
"api:diff": "chowbea-axios diff"
}
}Step 2: Fetch Your OpenAPI Spec
Once your API server is running, fetch the spec and generate types:
chowbea-axios fetchOr use the npm script:
npm run api:fetchThis command:
- Downloads your OpenAPI spec from the configured endpoint
- Caches it locally for change detection
- Generates TypeScript types (
api.types.ts) - Generates operation functions (
api.operations.ts)
Generated File Structure
Files in _internal/ and _generated/ are overwritten on each fetch. Don't edit them directly.
Step 3: Use the API Client
Import and use the typed client in your code:
import { api } from "./app/services/api/api.client";
// GET request with path parameters
const { data, error } = await api.get("/users/{id}", { id: "123" });
if (error) {
// error is typed as ApiError
console.error(error.message);
console.error(error.code); // e.g., "NOT_FOUND", "UNAUTHORIZED"
console.error(error.status); // HTTP status code
return;
}
// data is fully typed based on your OpenAPI spec
console.log(data.name);
console.log(data.email);POST Request with Body
const { data, error } = await api.post("/users", {
name: "John Doe",
email: "john@example.com",
});
if (error) {
console.error(error.message);
return;
}
console.log("Created user:", data.id);Using Operation-Based API
If your spec has operationId defined, you can use semantic method names:
// Instead of api.get("/users/{id}", { id: "123" })
const { data, error } = await api.op.getUserById({ id: "123" });Step 4: Watch Mode (Development)
During development, run watch mode to automatically regenerate types when your API changes:
npm run api:watchThis polls your API endpoint and regenerates types whenever the spec changes.
Pro Tip: Set up a concurrent script to run watch mode alongside your dev server. The init command can configure this for you.