Tutorials

Generate your first client

Generate and inspect a typed Axios client from a small OpenAPI specification.

Generate TypeScript types and an Axios client for one Petstore operation. You need Node.js 22 or higher and npm. You'll inspect the generated operation and its types.

Create a project

Terminal

mkdir kubb-first-client
cd kubb-first-client
npm init -y
npm pkg set type=module
npm install -D kubb typescript @kubb/plugin-ts @kubb/plugin-axios
npm install axios

Add the specification

Create petStore.yaml in the project root:

petStore.yaml

openapi: 3.0.3
info:
  title: Petstore
  version: 1.0.0
servers:
  - url: https://petstore.swagger.io/v2
paths:
  /pet/{petId}:
    get:
      operationId: getPetById
      parameters:
        - name: petId
          in: path
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: A pet
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Pet'
components:
  schemas:
    Pet:
      type: object
      required: [id, name]
      properties:
        id:
          type: integer
        name:
          type: string

The getPetById operation accepts a pet ID and returns a pet with an ID and name.

Configure generation

Create kubb.config.ts beside the specification:

kubb.config.ts

import { defineConfig } from 'kubb/config'
import { pluginTs } from '@kubb/plugin-ts'
import { pluginAxios } from '@kubb/plugin-axios'

export default defineConfig({
  input: './petStore.yaml',
  output: { path: './src/gen', clean: true },
  plugins: [
    pluginTs({ output: { path: 'models' } }),
    pluginAxios({ output: { path: 'clients' } }),
  ],
})

This configuration writes types to src/gen/models and the client to src/gen/clients.

Keep src/gen dedicated to generated files. clean: true removes its contents before each run.

Generate the client

Terminal

npx kubb generate

Kubb reports a successful build and writes this tree. Open src/gen/clients/getPetById.ts and notice that getPetById accepts typed path parameters and returns a typed result. Its imported types live in src/gen/models.

src/
- gen/
  - .kubb/
  - clients/
    - getPetById.ts
  - models/
    - GetPetById.ts
    - Pet.ts

The .kubb directory holds shared client and serialization helpers.

Regenerate after a change

Add a tag property to the Pet schema in petStore.yaml, alongside id and name:

petStore.yaml — properties

tag:
  type: string

Run npx kubb generate again and open src/gen/models/Pet.ts. It now includes an optional tag field because tag is not listed in the schema's required array. The client continues to import the regenerated types.

You now have a typed client and have seen how a specification change flows into its output.

Continue

Call generated operations

Use the generated Axios client. Configure its host for your API.

Configure generation

Add React or Vue hooks, validation, and mocks.

Configuration reference

Look up specification versions, options, and config formats.

Introduction

Create and extend a plugin