chowbea-axios - Type-safe Axios Client Generator

Prerequisites

Node.js version 18 or higher
A project with package.json
An OpenAPI specification (v3.x) endpoint or file

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.

The CLI uses openapi-typescript under the hood for type generation, accessed via pnpm dlx (no direct dependency needed).

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