🔮 apicraft

Generate types, requests and hooks for your API with one command.

Installation

npm install @siberiacancode/apicraft

Usage

Create apicraft.config.ts:

import { apicraft } from '@siberiacancode/apicraft';

export default apicraft([
  {
    input: 'api.yaml',
    output: 'generated/api',
    instance: 'fetches',
    nameBy: 'path',
    groupBy: 'tag'
  }
]);

Then use:

npx apicraft generate

CLI

generate

npx apicraft generate

• --input, -i - Path to input OpenAPI specification file (YAML or JSON)
• --output, -o - Path to output folder for generated files
• --config, -c - Path to a specific apicraft.config.(js|ts) file

Configuration

Apicraft consumes an array of options exported from apicraft.config.ts.

baseUrl

baseUrl lets you describe the path prefix that every request should strip while generating the client. This is particularly useful when a reverse-proxy rewrites the upstream path.

import { apicraft } from '@siberiacancode/apicraft';

export default apicraft([
  {
    input: 'api.yaml',
    output: 'generated/api',
    baseUrl: '/api', // drop /api when generating request paths
    instance: 'fetches'
  }
]);

runtimeInstance

Set the instance option to an object to keep using an HTTP client you already initialize at runtime while still benefiting from generated request helpers. The runtimeInstancePath is an import that apicraft will use instead of creating a new instance.

export default apicraft([
  {
    input: 'api.yaml',
    output: 'generated/api',
    baseUrl: '/api',
    instance: {
      name: 'axios',
      runtimeInstancePath: './src/lib/http/axiosInstance' // must export { instance }
    }
  }
]);

Also in that file you can define custom request return type/interface that will be used instead of default one:

export type ApicraftApiResponse<Data, Error> = AxiosResponse<Data | Error>;

Client Instances

Apicraft supports three HTTP client instances:

Fetches

Uses @siberiacancode/fetches for making requests:

{
  "input": "api.yaml",
  "output": "generated/api",
  "instance": "fetches"
}

Axios

Uses axios for making requests:

{
  "input": "api.yaml",
  "output": "generated/api",
  "instance": "axios"
}

Ofetch

Uses ofetch for making requests:

{
  "input": "api.yaml",
  "output": "generated/api",
  "instance": "ofetch"
}

Plugins

TanStack Query Plugin

Generate React Query query, mutations and options for your API requests:

{
  "input": "api.yaml",
  "output": "generated/api",
  "instance": "fetches",
  "plugins": ["tanstack"]
}