chowbea-axios - Type-safe Axios Client Generator

Prerequisites

Node.js version 20 or higher (tested in CI on 20, 22, 24 across Linux, macOS, and Windows)
A project with package.json
An OpenAPI specification (v3.x) endpoint or file

chowbea-axios is ESM only. package.json declares "type": "module", so importing the library from a CommonJS file with require("chowbea-axios") fails with ERR_REQUIRE_ESM. CJS consumers should use a dynamic import() or migrate the importing file to ESM. The chowbea-axios CLI binary works regardless of your project's module format.

Installation Options

Global Installation (Recommended)

Install globally to use chowbea-axios anywhere:

npm install -g chowbea-axios

yarn global add chowbea-axios

pnpm add -g chowbea-axios

bun add -g chowbea-axios

After installation, verify it works:

chowbea-axios --version

Using npx (No Installation)

Run commands directly without installing:

npx chowbea-axios init
npx chowbea-axios fetch
npx chowbea-axios watch

Using npx downloads the package on first use, so subsequent runs are faster.

Dependencies

chowbea-axios automatically installs axios in your project during init. No manual installation required.

Type generation is built in — there are no other runtime dependencies you need to install. The CLI ships its own OpenAPI-to-TypeScript generator and writes everything atomically.

Optional: Interactive Dashboard

Running chowbea-axios with no command launches an interactive TUI dashboard for fetch, generate, diff, validate, watch, plugins, and endpoint inspection. The dashboard requires Bun. When invoked under Node, the CLI re-launches itself under Bun automatically; if Bun isn't installed, the CLI falls back to headless mode and prints a hint. The headless CLI (fetch, generate, watch, etc.) works under Node alone — use it in CI and scripted workflows. See the dashboard guide for details.

Adding to an Existing Project

Already have Axios set up in your project? No problem. chowbea-axios generates an isolated client that works alongside your existing code. You can migrate endpoints gradually.

Initialize chowbea-axios

Run init in your project root. This creates the config file and sets up the output folder:

npx chowbea-axios init

When prompted, enter your OpenAPI endpoint URL and choose an output folder (e.g., src/services/api).

Generate the typed client

Fetch your spec and generate the client:

npx chowbea-axios fetch

This creates a new typed client in your chosen folder. Your existing Axios code is untouched.

Use both clients side by side

Your old Axios calls still work. Start using the generated client for new features or when you touch existing code:

// Your existing code (keep working)
import axios from 'axios';
const user = await axios.get('/api/users/123');

// New typed client (use for new work)
import { api } from '@/services/api';
const { data, error } = await api.op.getUserById({ id: '123' });

Migrate at your own pace

There's no rush. Replace old Axios calls with the typed client whenever you're already editing that code. Over time, your codebase becomes fully typed without a big rewrite.

Using Your Existing Axios Instance

Already have an Axios instance with interceptors, auth logic, or custom configuration? You can use it directly instead of the generated one.

Open api.instance.ts (in your output folder) and swap the export:

// Before: generated instance
import axios from "axios";

export const axiosInstance = axios.create({
  baseURL: import.meta.env.VITE_API_URL,
  timeout: 30000,
});

// After: your existing instance
import { myAxiosInstance } from '@/lib/axios';

export const axiosInstance = myAxiosInstance;

The typed client will now use your existing instance with all its interceptors, headers, and configuration intact.

The api.instance.ts file is never overwritten after initial creation, so your changes persist across regenerations.

Verify Installation

Run the status command to check everything is working:

chowbea-axios status

If you haven't set up a project yet, you'll see:

╭────────────────────────────────────────
│ Status
├────────────────────────────────────────
│
│ Config: api.config.toml (created)
│   endpoint: http://localhost:3000/docs/swagger/json
│   output: app/services/api
│
│ Spec:
│   cached: no - run 'chowbea-axios fetch' first
╰────────────────────────────────────────

Installation