Kubb

Kubb リファレンス

Kubb（kubb.dev）の全ドキュメントを網羅したスキル。 ユーザーのタスクに応じて適切な README.md を読み、そこから個別ファイルへ辿ること。

ディレクトリ構成

skills/kubb/
  SKILL.md
  references/
    getting-started/
      README.md
      configure.md
      installation.md
      introduction.md
      quick-start.md
      telemetry.md
      troubleshooting.md
    plugins/
      README.md
      overview.md
      core.md
      plugin-oas.md
      plugin-ts.md
      plugin-client.md
      plugin-zod.md
      plugin-react-query.md
      plugin-vue-query.md
      plugin-solid-query.md
      plugin-svelte-query.md
      plugin-swr.md
      plugin-faker.md
      plugin-msw.md
      plugin-cypress.md
      plugin-mcp.md
      plugin-redoc.md
    helpers/
      README.md
      cli.md
      mcp.md
      unplugin.md
    examples/
      README.md
      simple.md
      typescript.md
      client.md
      fetch.md
      cypress.md
      react-query.md
      vue-query.md
      svelte-query.md
      solid-query.md
      swr.md
      zod.md
      faker.md
      msw.md
      mcp.md
      generators.md
      advanced.md
    guides/
      README.md
      migration-guide.md
      tutorial.md
  samples/
    README.md
    basic-typescript-generation.md
    react-query-hooks.md
    zod-schema-generation.md
    api-client-generation.md
    msw-mock-handlers.md
    multi-plugin-workflow.md
    multiple-specs.md
    programmatic-build.md
    filtering-and-grouping.md
  scripts/
    README.md
    cli.md
    generate.md
    install.md
    mcp.md

探索手順

タスクからカテゴリを引き、カテゴリの README.md で目的のページを特定する:

1. 下記マッピング表でタスクに対応するカテゴリを探す 2. そのカテゴリの references/{category}/README.md を参照して目的のページを特定する 3. 該当ページの .md を Read して詳細を確認する

タスク → カテゴリ マッピング

Advanced Configuration Example

複数プラグインを組み合わせた高度な設定例。TypeScript 型、API クライアント、React Query hooks、Zod スキーマ、MSW ハンドラーを同時に生成する。

kubb.config.ts

import { defineConfig } from '@kubb/core'
import { pluginOas } from '@kubb/plugin-oas'
import { pluginTs } from '@kubb/plugin-ts'
import { pluginClient } from '@kubb/plugin-client'
import { pluginReactQuery } from '@kubb/plugin-react-query'
import { pluginZod } from '@kubb/plugin-zod'
import { pluginFaker } from '@kubb/plugin-faker'
import { pluginMsw } from '@kubb/plugin-msw'

export default defineConfig({
  input: { path: './petStore.yaml' },
  output: {
    path: './src/gen',
    clean: true,
    barrelType: 'named',
  },
  plugins: [
    pluginOas({
      validate: true,
      collisionDetection: true,
    }),
    pluginTs({
      output: { path: './types' },
      enumType: 'asConst',
      dateType: 'date',
      unknownType: 'unknown',
      optionalType: 'questionTokenAndUndefined',
    }),
    pluginClient({
      output: { path: './clients' },
      client: 'fetch',
      group: { type: 'tag' },
      parser: 'zod',
    }),
    pluginReactQuery({
      output: { path: './hooks' },
      group: { type: 'tag' },
      suspense: {},
      infinite: {
        queryParam: 'page',
        initialPageParam: 0,
      },
    }),
    pluginZod({
      output: { path: './zod' },
      group: { type: 'tag' },
      typed: true,
      dateType: 'stringOffset',
    }),
    pluginFaker({
      output: { path: './mocks' },
      group: { type: 'tag' },
      dateType: 'date',
      seed: [42],
    }),
    pluginMsw({
      output: { path: './msw' },
      group: { type: 'tag' },
      handlers: true,
      parser: 'faker',
    }),
  ],
  hooks: {
    done: [
      'npm run typecheck',
      'biome format --write ./',
      'biome lint --fix --unsafe ./src',
    ],
  },
})

依存関係

npm install --save-dev @kubb/cli @kubb/core @kubb/plugin-oas @kubb/plugin-ts @kubb/plugin-client @kubb/plugin-react-query @kubb/plugin-zod @kubb/plugin-faker @kubb/plugin-msw
npm install @tanstack/react-query zod @faker-js/faker msw

生成されるディレクトリ構造

src/gen/
├── types/          ← TypeScript 型・インターフェース
├── clients/        ← Fetch ベース API クライアント（Zod パース付き）
├── hooks/          ← React Query hooks（Suspense・無限クエリ対応）
├── zod/            ← Zod バリデーションスキーマ
├── mocks/          ← Faker モックデータジェネレーター
├── msw/            ← MSW ハンドラー
│   └── handlers.ts ← 全ハンドラーの統合ファイル
└── index.ts        ← バレルエクスポート

ポイント

• parser: 'zod'（client）— レスポンスを Zod スキーマでバリデーション
• parser: 'faker'（msw）— Faker でモックレスポンスを生成
• collisionDetection: true — スキーマ名の衝突を自動解決
• hooks.done — 生成後に型チェック・フォーマット・リントを実行

Axios Client Example

OpenAPI 仕様から Axios ベースの API クライアントを生成する設定例。

kubb.config.ts

import { defineConfig } from '@kubb/core'
import { pluginOas } from '@kubb/plugin-oas'
import { pluginTs } from '@kubb/plugin-ts'
import { pluginClient } from '@kubb/plugin-client'

export default defineConfig({
  input: { path: './petStore.yaml' },
  output: { path: './src/gen', clean: true },
  plugins: [
    pluginOas({ generators: [] }),
    pluginTs({
      output: { path: 'models' },
      enumType: 'asConst',
    }),
    pluginClient({
      output: { path: './clients' },
      client: 'axios',
      group: {
        type: 'tag',
        name: ({ group }) => `${group}Service`,
      },
      exclude: [{ type: 'tag', pattern: 'store' }],
      pathParamsType: 'object',
    }),
  ],
})

依存関係

npm install --save-dev @kubb/cli @kubb/core @kubb/plugin-oas @kubb/plugin-ts @kubb/plugin-client
npm install axios

生成コードの使用例

import { getPetById } from './gen/clients/PetService'

const pet = await getPetById({ petId: 1 })

Cypress Example

OpenAPI 仕様から Cypress リクエスト定義を生成する設定例。

kubb.config.ts

import { defineConfig } from '@kubb/core'
import { pluginOas } from '@kubb/plugin-oas'
import { pluginTs } from '@kubb/plugin-ts'
import { pluginCypress } from '@kubb/plugin-cypress'

export default defineConfig({
  input: { path: './petStore.yaml' },
  output: { path: './src/gen', clean: true },
  plugins: [
    pluginOas(),
    pluginTs({ output: { path: 'models' } }),
    pluginCypress({
      output: { path: './cypress' },
      group: {
        type: 'tag',
        name: ({ group }) => `${group}Requests`,
      },
    }),
  ],
})

依存関係

npm install --save-dev @kubb/cli @kubb/core @kubb/plugin-oas @kubb/plugin-ts @kubb/plugin-cypress cypress

Faker Example

OpenAPI 仕様から Faker.js モックデータジェネレーターを生成する設定例。

kubb.config.ts

import { defineConfig } from '@kubb/core'
import { pluginOas } from '@kubb/plugin-oas'
import { pluginTs } from '@kubb/plugin-ts'
import { pluginFaker } from '@kubb/plugin-faker'

export default defineConfig({
  input: { path: './petStore.yaml' },
  output: { path: './src/gen', clean: true },
  plugins: [
    pluginOas({ generators: [] }),
    pluginTs({ output: { path: 'models' } }),
    pluginFaker({
      output: { path: './mocks' },
      group: {
        type: 'tag',
        name: ({ group }) => `${group}Mocks`,
      },
      dateType: 'date',
      seed: [100],
    }),
  ],
})

依存関係

npm install --save-dev @kubb/cli @kubb/core @kubb/plugin-oas @kubb/plugin-ts @kubb/plugin-faker
npm install @faker-js/faker

Fetch Client Example

OpenAPI 仕様から Fetch ベースの API クライアントを生成する設定例。

kubb.config.ts

import { defineConfig } from '@kubb/core'
import { pluginOas } from '@kubb/plugin-oas'
import { pluginTs } from '@kubb/plugin-ts'
import { pluginClient } from '@kubb/plugin-client'

export default defineConfig({
  input: { path: './petStore.yaml' },
  output: { path: './src/gen', clean: true },
  plugins: [
    pluginOas({ validate: false }),
    pluginTs({
      output: { path: 'models.ts' },
    }),
    pluginClient({
      client: 'fetch',
      output: { path: './clients' },
    }),
  ],
  hooks: {
    done: ['npm run typecheck', 'biome format --write ./', 'biome lint --fix --unsafe ./src'],
  },
})

依存関係

npm install --save-dev @kubb/cli @kubb/core @kubb/plugin-oas @kubb/plugin-ts @kubb/plugin-client

Custom Generators Example

カスタムジェネレーターを使って生成コードをカスタマイズする設定例。

概要

Kubb のジェネレーターシステムにより、プラグインの出力をカスタマイズできる。generators オプションにカスタム関数を渡すことで、スキーマやオペレーションの生成ロジックを制御する。

kubb.config.ts

import { defineConfig } from '@kubb/core'
import { pluginOas } from '@kubb/plugin-oas'
import { pluginTs } from '@kubb/plugin-ts'
import { pluginClient } from '@kubb/plugin-client'

export default defineConfig({
  input: { path: './petStore.yaml' },
  output: { path: './src/gen', clean: true },
  plugins: [
    pluginOas({
      generators: [],  // JSON スキーマ生成を無効化
    }),
    pluginTs({
      output: { path: 'models' },
      generators: undefined,  // デフォルトのジェネレーターを使用
    }),
    pluginClient({
      output: { path: './clients' },
      transformers: {
        name: (name, type) => {
          if (type === 'file') {
            return `${name}Client`
          }
          return name
        },
      },
    }),
  ],
})

ポイント

• generators: [] — 特定のプラグインの生成を無効化
• generators: undefined — デフォルトのジェネレーターを使用
• transformers.name — 生成されるファイル名・関数名をカスタマイズ
• カスタムジェネレーターの詳細は @kubb/plugin-oas の generators オプションを参照

MCP Example

OpenAPI 仕様から MCP（Model Context Protocol）サーバーを生成する設定例。

kubb.config.ts

import { defineConfig } from '@kubb/core'
import { pluginOas } from '@kubb/plugin-oas'
import { pluginTs } from '@kubb/plugin-ts'
import { pluginClient } from '@kubb/plugin-client'
import { pluginMcp } from '@kubb/plugin-mcp'

export default defineConfig({
  input: { path: './petStore.yaml' },
  output: { path: './src/gen', clean: true },
  plugins: [
    pluginOas({ generators: [] }),
    pluginTs({ output: { path: 'models' } }),
    pluginClient({
      output: { path: './clients' },
      client: 'fetch',
    }),
    pluginMcp({
      output: { path: './mcp' },
      client: {
        baseURL: 'https://petstore.swagger.io/v2',
      },
      group: {
        type: 'tag',
        name: ({ group }) => `${group}Handlers`,
      },
    }),
  ],
})

依存関係

npm install --save-dev @kubb/cli @kubb/core @kubb/plugin-oas @kubb/plugin-ts @kubb/plugin-client @kubb/plugin-mcp

MSW Example

OpenAPI 仕様から MSW（Mock Service Worker）ハンドラーを生成する設定例。

kubb.config.ts

import { defineConfig } from '@kubb/core'
import { pluginOas } from '@kubb/plugin-oas'
import { pluginTs } from '@kubb/plugin-ts'
import { pluginFaker } from '@kubb/plugin-faker'
import { pluginMsw } from '@kubb/plugin-msw'

export default defineConfig({
  input: { path: './petStore.yaml' },
  output: { path: './src/gen', clean: true },
  plugins: [
    pluginOas({ generators: [] }),
    pluginTs({ output: { path: 'models' } }),
    pluginFaker({ output: { path: './mocks' } }),
    pluginMsw({
      output: { path: './msw' },
      group: {
        type: 'tag',
        name: ({ group }) => `${group}Handlers`,
      },
      handlers: true,
      parser: 'faker',
    }),
  ],
})

依存関係

npm install --save-dev @kubb/cli @kubb/core @kubb/plugin-oas @kubb/plugin-ts @kubb/plugin-faker @kubb/plugin-msw
npm install msw @faker-js/faker

React Query Example

OpenAPI 仕様から React Query（TanStack Query）hooks を生成する設定例。

kubb.config.ts

import { defineConfig } from '@kubb/core'
import { pluginOas } from '@kubb/plugin-oas'
import { pluginTs } from '@kubb/plugin-ts'
import { pluginReactQuery } from '@kubb/plugin-react-query'
import { QueryKey } from '@kubb/plugin-react-query/components'

export default defineConfig({
  input: { path: './petStore.yaml' },
  output: { path: './src/gen', clean: true },
  plugins: [
    pluginOas({ generators: [] }),
    pluginTs({ output: { path: 'models' } }),
    pluginReactQuery({
      client: { bundle: true },
      output: { path: './hooks' },
      group: { type: 'path' },
      paramsType: 'inline',
      pathParamsType: 'object',
      suspense: {},
      transformers: {
        name: (name, type) => {
          if (type === 'file' || type === 'function') {
            return `${name}Hook`
          }
          return name
        },
      },
      queryKey(props) {
        const keys = QueryKey.getTransformer(props)
        return ['"v5"', ...keys]
      },
      override: [
        {
          type: 'operationId',
          pattern: 'findPetsByTags',
          options: {
            client: { dataReturnType: 'full' },
            infinite: {
              queryParam: 'pageSize',
              initialPageParam: 0,
            },
          },
        },
      ],
    }),
  ],
})

依存関係

npm install --save-dev @kubb/cli @kubb/core @kubb/plugin-oas @kubb/plugin-ts @kubb/plugin-react-query
npm install @tanstack/react-query

生成コードの使用例

import { useGetPetByIdHook } from './gen/hooks'

function PetDetail({ petId }: { petId: number }) {
  const { data: pet } = useGetPetByIdHook({ petId })
  return <div>{pet?.name}</div>
}

Examples

Kubb の各プラグインを使った kubb.config.ts の設定例集。

Simple Example

最小限の Kubb 設定例。OpenAPI 仕様から基本的なコードを生成する。

kubb.config.ts

import { defineConfig } from '@kubb/core'
import { pluginOas } from '@kubb/plugin-oas'

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

依存関係

npm install --save-dev @kubb/cli @kubb/core @kubb/plugin-oas

実行

npx kubb generate

Solid Query Example

OpenAPI 仕様から Solid Query hooks を生成する設定例。

kubb.config.ts

import { defineConfig } from '@kubb/core'
import { pluginOas } from '@kubb/plugin-oas'
import { pluginTs } from '@kubb/plugin-ts'
import { pluginSolidQuery } from '@kubb/plugin-solid-query'

export default defineConfig({
  input: { path: './petStore.yaml' },
  output: { path: './src/gen', clean: true },
  plugins: [
    pluginOas({ generators: [] }),
    pluginTs({ output: { path: 'models' } }),
    pluginSolidQuery({
      output: { path: './hooks' },
      group: {
        type: 'tag',
        name: ({ group }) => `${group}Hooks`,
      },
    }),
  ],
})

依存関係

npm install --save-dev @kubb/cli @kubb/core @kubb/plugin-oas @kubb/plugin-ts @kubb/plugin-solid-query
npm install @tanstack/solid-query

Svelte Query Example

OpenAPI 仕様から Svelte Query hooks を生成する設定例。

kubb.config.ts

import { defineConfig } from '@kubb/core'
import { pluginOas } from '@kubb/plugin-oas'
import { pluginTs } from '@kubb/plugin-ts'
import { pluginSvelteQuery } from '@kubb/plugin-svelte-query'

export default defineConfig({
  input: { path: './petStore.yaml' },
  output: { path: './src/gen', clean: true },
  plugins: [
    pluginOas({ generators: [] }),
    pluginTs({ output: { path: 'models' } }),
    pluginSvelteQuery({
      output: { path: './hooks' },
      group: {
        type: 'tag',
        name: ({ group }) => `${group}Hooks`,
      },
    }),
  ],
})

依存関係

npm install --save-dev @kubb/cli @kubb/core @kubb/plugin-oas @kubb/plugin-ts @kubb/plugin-svelte-query
npm install @tanstack/svelte-query

SWR Example

OpenAPI 仕様から SWR hooks を生成する設定例。

kubb.config.ts

import { defineConfig } from '@kubb/core'
import { pluginOas } from '@kubb/plugin-oas'
import { pluginTs } from '@kubb/plugin-ts'
import { pluginSwr } from '@kubb/plugin-swr'

export default defineConfig({
  input: { path: './petStore.yaml' },
  output: { path: './src/gen', clean: true },
  plugins: [
    pluginOas({ generators: [] }),
    pluginTs({ output: { path: 'models' } }),
    pluginSwr({
      output: { path: './hooks' },
      group: {
        type: 'tag',
        name: ({ group }) => `${group}Hooks`,
      },
      client: { dataReturnType: 'full' },
    }),
  ],
})

依存関係

npm install --save-dev @kubb/cli @kubb/core @kubb/plugin-oas @kubb/plugin-ts @kubb/plugin-swr
npm install swr

TypeScript Example

OpenAPI 仕様から TypeScript 型を生成する設定例。複数の enum スタイルと出力形式を示す。

kubb.config.ts

import { defineConfig } from '@kubb/core'
import { pluginOas } from '@kubb/plugin-oas'
import { pluginTs } from '@kubb/plugin-ts'

export default defineConfig([
  // 基本: 単一ファイルに interface で出力
  {
    input: { path: './petStore.yaml' },
    output: { path: './src/gen', clean: true },
    plugins: [
      pluginOas({ validate: false }),
      pluginTs({
        output: { path: 'models.ts', barrelType: false },
        syntaxType: 'interface',
        enumType: 'enum',
      }),
    ],
  },
  // タグでグループ化、asConst enum
  {
    input: { path: './petStore.yaml' },
    output: { path: './src/gen2' },
    plugins: [
      pluginOas({ validate: false }),
      pluginTs({
        output: { path: 'models' },
        group: { type: 'tag' },
        enumType: 'asConst',
      }),
    ],
  },
])

依存関係

npm install --save-dev @kubb/cli @kubb/core @kubb/plugin-oas @kubb/plugin-ts

enumType の比較

Vue Query Example

OpenAPI 仕様から Vue Query hooks を生成する設定例。

kubb.config.ts

import { defineConfig } from '@kubb/core'
import { pluginOas } from '@kubb/plugin-oas'
import { pluginTs } from '@kubb/plugin-ts'
import { pluginVueQuery } from '@kubb/plugin-vue-query'

export default defineConfig({
  input: { path: './petStore.yaml' },
  output: { path: './src/gen', clean: true },
  plugins: [
    pluginOas({ generators: [] }),
    pluginTs({ output: { path: 'models' } }),
    pluginVueQuery({
      output: { path: './hooks' },
      group: {
        type: 'tag',
        name: ({ group }) => `${group}Hooks`,
      },
      client: { dataReturnType: 'full' },
    }),
  ],
})

依存関係

npm install --save-dev @kubb/cli @kubb/core @kubb/plugin-oas @kubb/plugin-ts @kubb/plugin-vue-query
npm install @tanstack/vue-query

Zod Example

OpenAPI 仕様から Zod バリデーションスキーマを生成する設定例。

kubb.config.ts

import { defineConfig } from '@kubb/core'
import { pluginOas } from '@kubb/plugin-oas'
import { pluginTs } from '@kubb/plugin-ts'
import { pluginZod } from '@kubb/plugin-zod'

export default defineConfig({
  input: { path: './petStore.yaml' },
  output: { path: './src/gen', clean: true },
  plugins: [
    pluginOas({ generators: [] }),
    pluginTs({ output: { path: 'models' } }),
    pluginZod({
      output: { path: './zod' },
      group: {
        type: 'tag',
        name: ({ group }) => `${group}Schemas`,
      },
      typed: true,
      dateType: 'stringOffset',
      unknownType: 'unknown',
    }),
  ],
})

依存関係

npm install --save-dev @kubb/cli @kubb/core @kubb/plugin-oas @kubb/plugin-ts @kubb/plugin-zod
npm install zod

生成コードの使用例

import { petSchema } from './gen/zod'

const result = petSchema.safeParse(apiResponse)
if (result.success) {
  console.log(result.data.name)
}

Configure

kubb.config.ts の全オプションリファレンス。

基本構造

defineConfig ヘルパーを使うことで型安全な設定が得られる:

import { defineConfig } from '@kubb/core'

export default defineConfig({
  input: { path: './petStore.yaml' },
  output: { path: './src/gen' },
  plugins: [],
})

設定オプション一覧

name

root

input

OpenAPI仕様のソースを指定する。path と data のどちらか一方を使う。

input.path

input.data

output

output.path（必須）

output.clean

output.format

output.lint

output.write（非推奨）

output.storage

output.extension

output.barrelType

output.defaultBanner

output.override

plugins

高度な設定

カスタムストレージ

ファイルシステム以外のバックエンド（S3, Redis, インメモリ等）に出力する場合は createStorage を使用:

import { createStorage, defineConfig } from '@kubb/core'

const memoryStorage = createStorage(() => {
  const store = new Map<string, string>()
  return {
    name: 'memory',
    async hasItem(key) { return store.has(key) },
    async getItem(key) { return store.get(key) ?? null },
    async setItem(key, value) { store.set(key, value) },
    async removeItem(key) { store.delete(key) },
    async getKeys(base) { /* ... */ },
    async clear(base) { /* ... */ },
  }
})

export default defineConfig({
  input: { path: './petStore.yaml' },
  output: {
    path: './src/gen',
    storage: memoryStorage,
  },
  plugins: [],
})

条件付き設定（CLI引数を動的に参照）

import { defineConfig } from '@kubb/core'

export default defineConfig(({ config, watch, logLevel }) => ({
  input: { path: './petStore.yaml' },
  output: {
    path: './src/gen',
    clean: !watch,
  },
  plugins: [],
}))

複数設定（配列エクスポート）

複数のOpenAPI仕様を処理したり、異なる設定で複数回生成する場合:

import { defineConfig } from '@kubb/core'
import { pluginOas } from '@kubb/plugin-oas'
import { pluginTs } from '@kubb/plugin-ts'

export default defineConfig([
  {
    name: 'petStore',
    input: { path: './petStore.yaml' },
    output: { path: './src/gen/petStore' },
    plugins: [pluginOas(), pluginTs()],
  },
  {
    name: 'userApi',
    input: { path: './userApi.yaml' },
    output: { path: './src/gen/userApi' },
    plugins: [pluginOas(), pluginTs()],
  },
])

設定ファイルの検索順序

Kubbは以下の順序で設定ファイルを検索する:

1. kubb.config.ts 2. kubb.config.mts（v4.36.5+） 3. kubb.config.cts（v4.36.5+） 4. kubb.config.js 5. kubb.config.mjs 6. kubb.config.cjs 7. .kubbrc 8. 上記の configs/ または .config/ サブディレクトリ内のバリエーション

Related

• quick-start.md
• troubleshooting.md

Installation

Kubb のインストール方法とシステム要件。

システム要件

• Node.js: 20以上（必須）
• TypeScript: 4.7以上（任意）
• パッケージマネージャー: npm / pnpm / yarn / bun いずれも対応

インストール方法

推奨: インタラクティブセットアップ

npx kubb init

このコマンドが自動的に以下を行う:

1. package.json を検出または作成 2. OpenAPI/Swagger 仕様ファイルの場所を確認 3. 出力ディレクトリパスを確認 4. 使用プラグインを選択（TypeScript, React Query, Zod など） 5. 必要なnpmパッケージをすべてインストール 6. kubb.config.ts を生成

セットアップ完了後:

npx kubb generate

手動インストール

コアパッケージ:

npm install --save-dev @kubb/cli @kubb/core

オプションプラグイン（カテゴリ別）:

TypeScript & HTTP:

npm install --save-dev @kubb/plugin-ts       # TypeScriptインターフェース生成
npm install --save-dev @kubb/plugin-client   # HTTPクライアント生成

Data Fetching:

npm install --save-dev @kubb/plugin-react-query
npm install --save-dev @kubb/plugin-swr
npm install --save-dev @kubb/plugin-vue-query
npm install --save-dev @kubb/plugin-solid-query
npm install --save-dev @kubb/plugin-svelte-query

Validation & Testing:

npm install --save-dev @kubb/plugin-zod     # ランタイムバリデーション
npm install --save-dev @kubb/plugin-faker   # モックデータ生成
npm install --save-dev @kubb/plugin-msw     # Mock Service Workerハンドラー生成
npm install --save-dev @kubb/plugin-cypress # E2Eテストユーティリティ生成

推奨 TypeScript 設定

{
  "compilerOptions": {
    "module": "ESNext",
    "moduleResolution": "bundler",
    "target": "ES2022",
    "lib": ["ES2023"]
  }
}

インストール確認

npx kubb --version

Notes

• グローバルインストールよりプロジェクトごとのインストールを推奨
• ピア依存関係の警告は通常無視して問題ない
• 必要なプラグインだけをインストールすればよい

Related

• introduction.md
• quick-start.md
• configure.md

Introduction

Kubb はプラグインベースのコードジェネレーターで、OpenAPI/Swagger 仕様から本番環境で使えるTypeScriptコードを自動生成する。

概要

フロントエンド開発者が APIクライアントを手動で保守すると、バックエンドAPIの変更時に型の陳腐化・クライアント関数の更新漏れ・フロントエンドとバックエンドの不整合が生じる。Kubb はOpenAPI仕様を唯一の真実源として読み込み、単一コマンドで完全な本番対応コードを生成することでこの問題を解決する。

生成できるコード

対応OpenAPIバージョン

• OpenAPI 2.0（Swagger）
• OpenAPI 3.0
• OpenAPI 3.1

システム要件

• Node.js: 20以上

クイックスタート

npx kubb init
npx kubb generate

init コマンドは以下を実行する:

1. package.json がなければ作成 2. OpenAPI/Swagger ファイルの場所を対話形式で確認 3. 使用プラグインを選択（TypeScript, React Query, Zod など） 4. 依存パッケージをインストール 5. kubb.config.ts を生成

プラグインエコシステム

コアプラグイン

ビルドツール

Kubbを選ぶ理由

• 単一の真実源: OpenAPI仕様のみを管理
• プラグインベース: 必要な生成物だけを選択
• ゼロメンテナンス: API変更時は再生成するだけ
• コンパイル時型安全: ランタイムエラーを排除
• 拡張可能: カスタムプラグインで任意の生成ロジックを追加

FAQ

JavaScriptプロジェクトでも使えるか? Kubbは TypeScriptファイルを生成するが、JavaScriptとして利用するかトランスパイルして使用可能。

GraphQLはサポートされているか? No。KubbはOpenAPI/Swagger REST APIのみを対象とする。

生成コードの更新方法は? npx kubb generate を再実行するだけで最新のAPI変更が反映される。

カスタマイズはできるか? はい。ジェネレーター、トランスフォーマー、カスタムプラグインで対応可能。

本番環境で使えるか? はい。広く本番環境で利用されており、TypeScriptのベストプラクティスに従った型安全なコードを生成する。

コミュニティ・サポート

• Discord: discord.gg/shfBFeczrm
• GitHub: github.com/kubb-labs/kubb

Related

• installation.md
• quick-start.md
• configure.md

Quick Start

2分以内にOpenAPI仕様からコードを生成するためのガイド。

前提条件

• Node.js 20以上
• TypeScript 4.7以上（任意）
• 有効なOpenAPI 2.0, 3.0, または 3.1 ファイル（YAML or JSON）

方法1: インタラクティブセットアップ（推奨）

npx kubb init

ウィザードが以下を順に実行する:

1. package.json を検出または作成 2. OpenAPI仕様ファイルのパスを確認 3. 出力ディレクトリパスを確認 4. プラグインを選択（React Query, Zod など） 5. 依存パッケージを自動インストール 6. kubb.config.ts を生成

その後、コードを生成:

npx kubb generate

方法2: 手動セットアップ

Step 1: コアパッケージをインストール

npm install --save-dev @kubb/cli @kubb/core

Step 2: kubb.config.ts を作成

import { defineConfig } from '@kubb/core'

export default defineConfig({
  root: '.',
  input: {
    path: './petStore.yaml',
  },
  output: {
    path: './src/gen',
  },
  plugins: [],
})

Step 3: npm スクリプトを追加

{
  "scripts": {
    "generate": "kubb generate"
  }
}

Step 4: コードを生成

npm run generate

設定例

TypeScript + React Query

import { defineConfig } from '@kubb/core'
import { pluginOas } from '@kubb/plugin-oas'
import { pluginTs } from '@kubb/plugin-ts'
import { pluginReactQuery } from '@kubb/plugin-react-query'

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

複数OpenAPI仕様を同時処理

export default defineConfig([
  {
    name: 'petStore',
    input: { path: './petStore.yaml' },
    output: { path: './src/gen/petStore' },
    plugins: [pluginOas(), pluginTs()],
  },
  {
    name: 'userApi',
    input: { path: './userApi.yaml' },
    output: { path: './src/gen/userApi' },
    plugins: [pluginOas(), pluginTs()],
  },
])

プログラマティック利用

@kubb/core の build 関数を使ってNode.jsスクリプトやビルドシステムに組み込める:

import { build } from '@kubb/core'
import { pluginOas } from '@kubb/plugin-oas'
import { pluginTs } from '@kubb/plugin-ts'

const { error, files } = await build({
  config: {
    root: '.',
    input: { path: './petStore.yaml' },
    output: { path: './gen' },
    plugins: [pluginOas(), pluginTs()],
  },
})

Notes

• input.path にはURLも指定可能
• output.clean: true で生成前に出力ディレクトリをクリーンアップ
• プラグインの include / exclude オプションで生成するエンドポイントを絞り込める
• 仕様変更後は npx kubb generate を再実行するだけ

Related

• installation.md
• configure.md
• troubleshooting.md

Getting Started

Telemetry

Kubb CLIが収集する匿名使用データについての説明。

収集される情報

各コマンド実行後に以下の匿名情報が収集される:

収集されない情報

プライバシー保護のため、以下は明示的に除外される:

• OpenAPI仕様の内容
• ファイルパスやディレクトリ構造
• 認証情報・APIキー・トークン
• ソースコードや生成されたコード
• IPアドレスやユーザー識別子

テレメトリーの無効化

2つの環境変数のいずれかで無効化できる。

方法1: 標準的な方法（DO_NOT_TRACK）

export DO_NOT_TRACK=1

方法2: Kubb固有の変数（KUBB_DISABLE_TELEMETRY）

export KUBB_DISABLE_TELEMETRY=1

どちらも "1" または "true" を受け付ける。

データの送信方法

• フォーマット: OpenTelemetry OTLPスタンダード
• 送信先: https://otlp.kubb.dev/v1/traces（単一のHTTP POSTリクエスト）
• タイムアウト: 5秒
• フォールバック: 送信失敗時はサイレントに無視（CLI操作を妨げない）
• 前提: アクティブなインターネット接続がある場合のみ送信

データの活用目的

収集されたメトリクスは以下の目的で利用される:

• フィーチャーの採用状況の把握
• パフォーマンス問題の特定
• 非推奨オプションへの依存の検出
• 開発優先順位の決定

Related

• introduction.md
• troubleshooting.md

Troubleshooting

Kubbでよく発生する問題とその解決方法。

インストール問題

Node.jsバージョンエラー

症状: バージョン関連のエラーが発生する

解決策: Kubbは Node.js 20以上 が必須。

node --version
# v20.x.x 以上であることを確認

パッケージマネージャーの競合

症状: 依存関係のインストールが失敗する、または予期しないバージョンが入る

解決策: キャッシュをクリアして依存関係を再インストールする:

# npm
npm cache clean --force && npm install

# pnpm
pnpm store prune && pnpm install

# yarn
yarn cache clean && yarn install

# bun
bun pm cache rm && bun install

設定問題

設定ファイルが認識されない

症状: kubb generate 実行時に設定ファイルが見つからないエラー

解決策: Kubbが受け付ける設定ファイル名は以下のいずれか:

• kubb.config.ts
• kubb.config.js
• kubb.config.mjs
• kubb.config.cjs

OpenAPI仕様のバリデーションエラー

症状: OpenAPIファイルのパースエラー

解決策: Swagger Editor でOpenAPI仕様を事前にバリデーションする。

モジュールエラー（ESM）

症状: require is not defined または Cannot use import statement エラー

解決策: package.json に "type": "module" を追加するか、設定ファイルの拡張子を .mjs にする:

{
  "type": "module"
}

生成の失敗

プラグインが見つからない

症状: プラグイン関連のエラーが発生する

解決策: ほとんどのプラグインは @kubb/plugin-oas を依存として必要とする:

npm install --save-dev @kubb/plugin-oas

出力が空になる

症状: 生成コマンドは成功するが、ファイルが生成されない

解決策: 1. OpenAPIファイルの内容を確認する 2. プラグインの include / exclude 設定を確認する

TypeScriptエラー

症状: 生成されたコードでTypeScriptコンパイルエラーが発生する

解決策: tsconfig.json の moduleResolution 設定を確認する:

{
  "compilerOptions": {
    "moduleResolution": "bundler"
  }
}

パフォーマンス問題

生成が遅い

解決策: include オプションで必要なエンドポイントのみを生成し、不要なプラグインを無効化する。

メモリ不足エラー

症状: JavaScript heap out of memory エラー

解決策: Node.jsのヒープサイズを増やす:

NODE_OPTIONS="--max-old-space-size=4096" npx kubb generate

ランタイム問題

インポートエラー

症状: 生成されたコードのインポートが解決できない

解決策:

• 出力パスとインポート文が一致しているか確認する
• バレルファイル（index.ts）の生成設定を確認する（output.barrelType）

クライアントリクエストの失敗

症状: 生成されたHTTPクライアントがリクエストに失敗する

解決策:

• baseURL の設定が正しいか確認する
• CORSの設定を確認する

デバッグモード

詳細なログを .kubb ディレクトリに出力する:

kubb generate --debug

このログファイルを使って問題を特定できる。

サポート

問題が解決しない場合は以下を活用する:

• GitHub Issues: github.com/kubb-labs/kubb/issues（バージョン番号と最小再現手順を添えて報告）
• Discord: discord.gg/shfBFeczrm

Related

• installation.md
• configure.md
• telemetry.md

マイグレーションガイド

Kubb v5 への移行

Node.js 22 必須

Kubb v5 は Node.js 22 以上が必要。

ファクトリ関数のリネーム

define* プレフィックスが create* に変更（Vite エコシステムの慣例に合わせ、define* は純粋な型/設定ヘルパー用に予約）:

// v5 以前
import { definePlugin } from '@kubb/core'
// v5 以降
import { createPlugin } from '@kubb/core'

対象: definePlugin → createPlugin, defineAdapter → createAdapter, defineGenerator → createGenerator, defineLogger → createLogger, defineStorage → createStorage

単一プラグインインスタンスルール

同一プラグインを設定内で複数回使用できなくなった。複数インスタンスは単一に統合する必要がある。

PluginManager → PluginDriver

プラグイン形式の統一

オブジェクト形式・JSON 形式は削除。配列形式のみ有効:

import { pluginTs } from '@kubb/plugin-ts'
export default defineConfig({
  plugins: [pluginTs({})],
})

@kubb/plugin-ts の変更

mapper オプションが削除。新しい transform オプション（AST ノード変換）が計画されている。

---

Kubb v3 への移行

新機能

• Static Class Client: clientType: 'staticClass' でクラスベースのクライアント生成
• Generators: テンプレートに代わる新しいコード生成システム
• CLI 改善: 20-30% の高速化、プログレスバー、--debug モード
• `output.extension`: ファイル拡張子の制御
• `output.barrelType`: exportType の後継

パッケージリネーム

TanStack Query パッケージの分割

統合パッケージがフレームワーク別に分割。TanStack Query v4 のサポートは廃止（v5 必須）:

• @kubb/plugin-react-query
• @kubb/plugin-vue-query
• @kubb/plugin-svelte-query
• @kubb/plugin-solid-query

MSW v2 必須

MSW v1 のサポートは廃止。v2 が必須。

出力設定の変更

プラグイン固有の変更

@kubb/plugin-client:

• client.importPath → importPath
• 新オプション: operations, parser（'client' \| 'zod'）, paramsType

@kubb/plugin-ts:

• enumSuffix デフォルト: 'enum'
• mapper で TypeScript ノードオーバーライド

@kubb/plugin-zod:

• typedSchema → inferred
• 新オプション: operations, mapper

@kubb/plugin-swr / @kubb/plugin-react-query:

• dataReturnType → client.dataReturnType
• 新オプション: paramsType
• ミューテーションに mutationKey 生成
• 必須パラメータに基づく enabled 自動生成

@kubb/plugin-oas:

• experimentalFilter, experimentalSort 削除（外部ツール openapi-format の使用を推奨）

Node.js サポート

v3 の最小要件は Node.js 20（v18 サポート廃止）。

guides

基本チュートリアル

OpenAPI 仕様から TypeScript 型を生成するステップバイステップガイド。

前提条件

• Node.js 20 以上
• TypeScript 4.7 以上

1. プロジェクト構造の作成

.
├── src/
├── petStore.yaml
├── kubb.config.ts
└── package.json

2. OpenAPI 仕様の準備

petStore.yaml:

openapi: 3.0.0
info:
  title: Pet Store API
  version: 1.0.0
paths:
  /pets:
    get:
      operationId: listPets
      responses:
        '200':
          description: List of pets
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Pet'
components:
  schemas:
    Pet:
      type: object
      required:
        - id
        - name
      properties:
        id:
          type: integer
          format: int64
        name:
          type: string
        tag:
          type: string

3. 設定ファイルの作成

kubb.config.ts:

import { defineConfig } from '@kubb/core'
import { pluginOas } from '@kubb/plugin-oas'
import { pluginTs } from '@kubb/plugin-ts'

export default defineConfig(() => {
  return {
    root: '.',
    input: {
      path: './petStore.yaml',
    },
    output: {
      path: './src',
    },
    plugins: [
      pluginOas({
        generators: [],
        validate: true,
      }),
      pluginTs({
        output: {
          path: 'models',
        },
      }),
    ],
  }
})

ポイント:

• generators: [] — JSON スキーマ生成をスキップ
• validate: true — 処理前に仕様の妥当性を検証
• output.path: 'models' — TypeScript 型の出力先

4. 依存関係のインストール

package.json:

{
  "name": "kubb-getting-started",
  "scripts": {
    "generate": "kubb generate"
  },
  "dependencies": {
    "@kubb/cli": "latest",
    "@kubb/core": "latest",
    "@kubb/plugin-oas": "latest",
    "@kubb/plugin-ts": "latest"
  },
  "devDependencies": {
    "typescript": "^5.9.0"
  }
}

npm install

5. コード生成の実行

npm run generate

6. 生成結果

src/
├── index.ts
└── models/
    ├── Category.ts
    ├── Pet.ts
    ├── User.ts
    └── index.ts

生成される型の例（src/models/Pet.ts）

/**
 * Generated by Kubb (https://kubb.dev/).
 * Do not edit manually.
 */

export type Pet = {
  /**
   * @type integer, int64
   */
  id: number
  /**
   * @type string
   */
  name: string
  /**
   * @type string | undefined
   */
  tag?: string
}

次のステップ

• 追加プラグインの探索（React Query、Zod 等）
• TypeScript プラグインの詳細設定オプション
• 設定リファレンスの確認

@kubb/cli

OpenAPI 仕様からコードを生成する Kubb の CLI ツール。

インストール

bun add -d @kubb/cli
pnpm add -D @kubb/cli
npm install --save-dev @kubb/cli
yarn add -D @kubb/cli

コマンド一覧

kubb init

新規プロジェクトのインタラクティブセットアップウィザード。

npx kubb init

ワークフロー: 1. package.json の作成/検出 2. パッケージマネージャーの検出（npm, pnpm, yarn, bun） 3. OpenAPI 仕様ファイルのパスを入力 4. 出力ディレクトリの指定 5. プラグイン選択メニュー表示 6. パッケージのインストール 7. kubb.config.ts の生成

デフォルトで @kubb/plugin-oas と @kubb/plugin-ts が選択される。

kubb generate（または kubb）

設定ファイルに基づいてコードを生成する。

kubb generate [OPTIONS]
kubb petStore.yaml

オプション:

ログレベル詳細:

• silent: 出力なし
• info: 警告、エラー、情報メッセージ（デフォルト）
• verbose: プラグインのタイミングとパフォーマンスメトリクスを追加
• debug: 完全な実行トレースと詳細情報

kubb start

SSE（Server-Sent Events）ストリーミング付き HTTP サーバーを起動する。

kubb start petStore.yaml
kubb start --config kubb.config.ts

オプション:

kubb validate

Swagger/OpenAPI ファイルの構文と構造をチェックする。oas-normalize を使用。

kubb validate --input petstore.yaml

オプション:

@kubb/oas パッケージが必要。

kubb agent

Kubb Studio との WebSocket 連携用 HTTP サーバーを管理する。

kubb agent start
kubb agent start --config ./my-config.ts
kubb agent start --host 0.0.0.0 --port 8080
kubb agent start --allow-write
kubb agent start --allow-all

`agent start` オプション:

環境変数:

API エンドポイント: GET /api/health — サーバーステータス確認

kubb mcp

AI アシスタント用の MCP（Model Context Protocol）サーバーを起動する。v4.36.5 以降 kubb.config.mts / kubb.config.cts にも対応。

npx kubb mcp

@kubb/mcp パッケージが必要。Claude Desktop、Cursor 等の MCP 対応ツールで利用可能。

デバッグ

--debug フラグで .kubb/ ディレクトリに詳細ログを作成:

• タイムスタンプ
• 設定詳細
• プラグイン実行タイミング
• スキーマパース情報
• ファイル生成進捗
• フォーマッター/リンター詳細
• エラースタックトレース

テレメトリ

kubb generate 実行後に匿名使用統計を収集。OpenAPI 仕様、ファイルパス、シークレットは収集されない。

無効化:

DO_NOT_TRACK=1 kubb generate          # 標準的な無効化
KUBB_DISABLE_TELEMETRY=1 kubb generate # Kubb 固有の無効化

@kubb/mcp

Kubb のコード生成機能を AI アシスタント（Claude、Cursor 等）に公開する MCP（Model Context Protocol）サーバー。

インストール

npm install --save-dev @kubb/mcp @kubb/cli

両パッケージが必要。インストールせずに直接実行も可能:

npx @kubb/mcp

クイックスタート

1. サーバーの起動

npx kubb mcp

stdio 経由で通信する MCP サーバーが起動し、クライアントリクエストを待機する。

2. Claude Desktop の設定

設定ファイルに MCP サーバーを追加:

ファイルの場所:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "kubb": {
      "command": "npx",
      "args": ["kubb", "mcp"]
    }
  }
}

3. 設定ファイルの作成

プロジェクトに kubb.config.ts が存在し、プラグインと入出力パスが定義されていることを確認する。

4. AI との対話

AI アシスタントに自然言語でコード生成をリクエストする。

利用可能なツール

generate ツール

OpenAPI/Swagger 仕様からコードを生成する。

パラメータ:

startServer API

@kubb/plugin-mcp から startServer 関数がエクスポートされており、カスタムサーバーロジックの実装や追加トランスポート対応が可能:

import { startServer } from '@kubb/plugin-mcp'

startServer({ /* options */ })

ユースケース

• 初回コード生成: 新規プロジェクトで OpenAPI 仕様から TypeScript 型を生成
• 仕様更新時の再生成: API 仕様変更後にクライアントコードを再生成
• トラブルシューティング: verbose ログで生成問題を診断
• カスタムトランスポート: startServer で独自 MCP サーバー実装

トラブルシューティング

helpers

unplugin-kubb

Kubb コード生成を複数のビルドツールに統合するユニバーサルプラグイン。 Vite、webpack、Rollup、esbuild、Nuxt、Astro、Rspack に対応。

インストール

bun add -d unplugin-kubb @kubb/core
pnpm add -D unplugin-kubb @kubb/core
npm install --save-dev unplugin-kubb @kubb/core
yarn add -D unplugin-kubb @kubb/core

設定オプション

config

• 型: UserConfig
• 必須: true
• 説明: Kubb の生成設定（input, output, plugins 等）

ビルドツール別の統合例

Vite

// vite.config.ts
import kubb from 'unplugin-kubb/vite'

export default defineConfig({
  plugins: [
    kubb({
      config: {
        root: '.',
        input: { path: './petStore.yaml' },
        output: { path: './src/gen' },
        plugins: [/* ... */],
      },
    }),
  ],
})

Rollup

// rollup.config.js
import kubb from 'unplugin-kubb/rollup'

export default {
  plugins: [
    kubb({
      config: {
        // ...UserConfig
      },
    }),
  ],
}

webpack

// webpack.config.js
const kubb = require('unplugin-kubb/webpack')

module.exports = {
  plugins: [
    kubb({
      config: {
        // ...UserConfig
      },
    }),
  ],
}

Rspack

// rspack.config.js
const kubb = require('unplugin-kubb/rspack')

module.exports = {
  plugins: [
    kubb({
      config: {
        // ...UserConfig
      },
    }),
  ],
}

esbuild

import { build } from 'esbuild'
import kubb from 'unplugin-kubb/esbuild'

build({
  plugins: [
    kubb({
      config: {
        // ...UserConfig
      },
    }),
  ],
})

Vue CLI

// vue.config.js
const kubb = require('unplugin-kubb/webpack')

module.exports = {
  configureWebpack: {
    plugins: [
      kubb({
        config: {
          // ...UserConfig
        },
      }),
    ],
  },
}

Nuxt

// nuxt.config.ts
export default defineNuxtConfig({
  modules: [
    ['unplugin-kubb/nuxt', {
      config: {
        // ...UserConfig
      },
    }],
  ],
})

Astro

// astro.config.mjs
import kubb from 'unplugin-kubb/astro'

export default defineConfig({
  integrations: [
    kubb({
      config: {
        // ...UserConfig
      },
    }),
  ],
})

制限事項

• hook オプションは unplugin では動作しない。生成後に Prettier や ESLint を実行する必要がある場合は、Kubb CLI を使用すること。

@kubb/core

全 Kubb プラグインの基盤となるコアモジュール。build() API を提供する。

インストール

bun add -d @kubb/core
pnpm add -D @kubb/core
npm install --save-dev @kubb/core
yarn add -D @kubb/core

build() 関数

コード生成プロセスを開始する主要関数。設定に定義されたプラグインとライフサイクルメソッドをトリガーする。

import { build } from '@kubb/core'

const { error, files, driver } = await build({
  config: {
    root: '.',
    input: {
      data: '',
    },
    output: {
      path: './gen',
    },
  },
})

console.log(files)

戻り値

ストレージ API（v4.36.0+）

カスタムストレージバックエンドを定義するファクトリ関数:

import { defineStorage, fsStorage, memoryStorage } from '@kubb/core'

URLPath ヘルパー（v4.36.1+）

カスタムプラグインでパスの標準化・組み立てに使用するユーティリティクラス:

import { URLPath } from '@kubb/core'

設定の型

build() は UserConfig 型のオブジェクトを受け取る。詳細は configure を参照。

プラグイン概要

Kubb はプラグインベースのアーキテクチャで、OpenAPI 仕様から様々なコード成果物を生成する。

プラグインの依存関係

ほとんどのプラグインは @kubb/plugin-oas を基盤として必要とする。

@kubb/plugin-oas（必須基盤）
├── @kubb/plugin-ts（TypeScript 型生成）
├── @kubb/plugin-client（API クライアント）
│   ├── @kubb/plugin-react-query
│   ├── @kubb/plugin-vue-query
│   ├── @kubb/plugin-solid-query
│   ├── @kubb/plugin-svelte-query
│   └── @kubb/plugin-swr
├── @kubb/plugin-zod（バリデーション）
├── @kubb/plugin-faker（モックデータ）
├── @kubb/plugin-msw（MSW ハンドラー）
├── @kubb/plugin-cypress（Cypress テスト）
├── @kubb/plugin-mcp（MCP サーバー）
└── @kubb/plugin-redoc（API ドキュメント）

カテゴリ別プラグイン

基盤レイヤー

• @kubb/plugin-oas: OpenAPI 仕様の読み込み・パース・バリデーション

型生成

• @kubb/plugin-ts: TypeScript インターフェース・型の生成

API クライアント

• @kubb/plugin-client: Axios/Fetch ベースの HTTP クライアント生成

データフェッチング

• @kubb/plugin-react-query: TanStack Query for React
• @kubb/plugin-vue-query: TanStack Query for Vue
• @kubb/plugin-solid-query: TanStack Query for SolidJS
• @kubb/plugin-svelte-query: TanStack Query for Svelte
• @kubb/plugin-swr: Vercel SWR hooks

バリデーション・モック

• @kubb/plugin-zod: Zod バリデーションスキーマ生成
• @kubb/plugin-faker: Faker.js モックデータ生成
• @kubb/plugin-msw: Mock Service Worker ハンドラー生成

テスト・ドキュメント

• @kubb/plugin-cypress: Cypress リクエスト定義（v3.7.0+）
• @kubb/plugin-redoc: Redoc HTML ドキュメント生成

AI 連携

• @kubb/plugin-mcp: MCP サーバー生成（v3.9.0+）

設定例

import { defineConfig } from '@kubb/core'
import { pluginOas } from '@kubb/plugin-oas'
import { pluginTs } from '@kubb/plugin-ts'
import { pluginClient } from '@kubb/plugin-client'

export default defineConfig({
  input: { path: './petstore.yaml' },
  output: { path: './src/gen' },
  plugins: [
    pluginOas(),
    pluginTs(),
    pluginClient(),
  ],
})

共通パターン

全プラグインは一貫したパターンに従う:

• パッケージマネージャーでインストール
• kubb.config.ts の plugins 配列に追加
• 出力ディレクトリを指定
• 依存プラグインを宣言

@kubb/plugin-client

OpenAPI 仕様から API クライアントコード（Axios/Fetch）を生成するプラグイン。

インストール

npm install --save-dev @kubb/plugin-client

設定オプション

output

クライアント設定

注意: Query プラグイン（React Query 等）は clientType: 'function' のみ対応。class ベースのクライアントとは非互換。

データ・パラメータ

その他

カスタムクライアントの要件

importPath 使用時は以下の型をエクスポートする必要がある:

• RequestConfig<TData>
• ResponseConfig<TData>
• ResponseErrorConfig<TError>
• Client（Query プラグイン使用時に必須）

生成コードの例

Function スタイル（デフォルト）

export async function getPetById(
  petId: GetPetByIdPathParams['petId'],
  config?: Partial<RequestConfig>
): Promise<GetPetByIdQueryResponse>

Static Class スタイル

export class Pet {
  static async getPetById(
    { petId }: { petId: GetPetByIdPathParams['petId'] },
    config?: Partial<RequestConfig>
  ): Promise<GetPetByIdQueryResponse>
}

設定例

import { defineConfig } from '@kubb/core'
import { pluginClient } from '@kubb/plugin-client'
import { pluginOas } from '@kubb/plugin-oas'

export default defineConfig({
  input: { path: './petStore.yaml' },
  output: { path: './src/gen' },
  plugins: [
    pluginOas(),
    pluginClient({
      output: { path: './clients', barrelType: 'named' },
      client: 'fetch',
      clientType: 'staticClass',
      group: { type: 'tag' },
      dataReturnType: 'full',
      paramsType: 'object',
    }),
  ],
})

@kubb/plugin-cypress

OpenAPI 仕様から Cypress リクエスト定義を生成するプラグイン。v3.7.0 で追加。

インストール

npm install --save-dev @kubb/plugin-cypress

設定オプション

output

パラメータ

その他

設定例

pluginCypress({
  output: { path: './cypress', barrelType: 'named' },
  group: { type: 'tag', name: ({ group }) => `${group}Requests` },
})

@kubb/plugin-faker

OpenAPI スキーマから Faker.js モックデータジェネレーターを生成するプラグイン。

インストール

npm install --save-dev @kubb/plugin-faker

設定オプション

output

データ生成オプション

その他

dateParser の例

// dateParser: 'dayjs', dateType: 'string'
dayjs(faker.date.anytime()).format("YYYY-MM-DD")

// dateType: 'date'
faker.date.anytime()

設定例

pluginFaker({
  output: { path: './mocks', barrelType: 'named' },
  group: { type: 'tag', name: ({ group }) => `${group}Service` },
  dateType: 'date',
  seed: [100],
})

@kubb/plugin-mcp

OpenAPI 仕様から MCP（Model Context Protocol）サーバーを生成するプラグイン。v3.9.0 で追加。 AI モデルが API と対話可能になる。

インストール

npm install --save-dev @kubb/plugin-mcp

設定オプション

output

client

その他

設定例

pluginMcp({
  output: { path: './mcp', barrelType: 'named' },
  client: { baseURL: 'https://petstore.swagger.io/v2' },
  group: { type: 'tag', name: ({ group }) => `${group}Handlers` },
})

@kubb/plugin-msw

OpenAPI 仕様から MSW（Mock Service Worker）ハンドラーを生成するプラグイン。

インストール

npm install --save-dev @kubb/plugin-msw

設定オプション

output

MSW 固有オプション

その他

設定例

pluginMsw({
  output: {
    path: './mocks',
    barrelType: 'named',
    banner: '/* eslint-disable no-alert, no-console */',
  },
  group: { type: 'tag', name: ({ group }) => `${group}Service` },
  handlers: true,
  parser: 'data',
  baseURL: 'https://api.example.com',
})

@kubb/plugin-oas

OpenAPI 仕様のパース・バリデーションを行う Kubb の基盤プラグイン。ほとんどの他プラグインがこのプラグインに依存する。

インストール

npm install --save-dev @kubb/plugin-oas

設定オプション

output

group

バリデーション・サーバー

discriminator

• 型: 'strict' \| 'inherit'
• デフォルト: 'strict'

discriminator の解釈方法:

• strict: oneOf スキーマをそのまま使用。discriminator は型の絞り込みのみ
• inherit: 子スキーマに discriminator プロパティと enum 値を追加

OpenAPI 3.0/3.1、oneOf/anyOf、インラインスキーマ、$ref 参照をサポート。

その他

設定例

import { defineConfig } from '@kubb/core'
import { pluginOas } from '@kubb/plugin-oas'

export default defineConfig({
  input: { path: './petStore.yaml' },
  output: { path: './src/gen' },
  plugins: [
    pluginOas({
      validate: true,
      output: { path: './json' },
      serverIndex: 0,
      contentType: 'application/json',
      collisionDetection: true,
    }),
  ],
})

discriminator の例（inherit モード）

// 生成結果
export type Cat = {
  type: CatTypeEnum
  name?: string
  indoor: boolean
}

export type Dog = {
  type: DogTypeEnum
  name: string
}

@kubb/plugin-react-query

OpenAPI 仕様から React Query（TanStack Query）hooks を生成するプラグイン。

インストール

npm install --save-dev @kubb/plugin-react-query

設定オプション

output

client

query / mutation

パラメータ

高度な機能

infinite の型

type Infinite = {
  queryParam: string        // デフォルト: 'id'
  initialPageParam: unknown // デフォルト: 0
  nextParam?: string | string[]
  previousParam?: string | string[]
} | false

フィルタリング

設定例

pluginReactQuery({
  output: { path: './hooks' },
  group: { type: 'tag', name: ({ group }) => `${group}Hooks` },
  client: { dataReturnType: 'full' },
  query: { methods: ['get'], importPath: '@tanstack/react-query' },
  mutation: { methods: ['post', 'put', 'delete'] },
  infinite: { queryParam: 'page', initialPageParam: 0 },
  suspense: {},
  parser: 'zod',
})

@kubb/plugin-redoc

OpenAPI 仕様から Redoc HTML ドキュメントを生成するプラグイン。Redocly を使用。

インストール

npm install --save-dev @kubb/plugin-redoc

設定オプション

設定例

import { defineConfig } from '@kubb/core'
import { pluginRedoc } from '@kubb/plugin-redoc'

export default defineConfig({
  input: { path: './petStore.yaml' },
  output: { path: './src/gen' },
  plugins: [
    pluginRedoc({
      output: { path: './docs/index.html' },
    }),
  ],
})

@kubb/plugin-solid-query

OpenAPI 仕様から Solid Query（TanStack Query）hooks を生成するプラグイン。

インストール

npm install --save-dev @kubb/plugin-solid-query

設定オプション

@kubb/plugin-react-query とほぼ同一の構成。主な違いは importPath のデフォルト値のみ。

output

client

query / mutation

その他

設定例

pluginSolidQuery({
  output: { path: './hooks' },
  group: { type: 'tag', name: ({ group }) => `${group}Hooks` },
  client: { dataReturnType: 'full' },
  query: { methods: ['get'], importPath: '@tanstack/solid-query' },
})

@kubb/plugin-svelte-query

OpenAPI 仕様から Svelte Query（TanStack Query）hooks を生成するプラグイン。

インストール

npm install --save-dev @kubb/plugin-svelte-query

設定オプション

@kubb/plugin-react-query とほぼ同一の構成。主な違いは importPath のデフォルト値のみ。

output

client

query / mutation

その他

設定例

pluginSvelteQuery({
  output: { path: './hooks' },
  group: { type: 'tag', name: ({ group }) => `${group}Hooks` },
  client: { dataReturnType: 'full' },
  query: { methods: ['get'], importPath: '@tanstack/svelte-query' },
})

@kubb/plugin-swr

OpenAPI 仕様から SWR hooks を生成するプラグイン。

インストール

npm install --save-dev @kubb/plugin-swr

設定オプション

output

client

query / mutation

パラメータ・パーサー

フィルタリング

設定例

pluginSwr({
  output: { path: './hooks' },
  group: { type: 'tag', name: ({ group }) => `${group}Hooks` },
  client: { dataReturnType: 'full' },
  parser: 'zod',
})

@kubb/plugin-ts

OpenAPI スキーマから TypeScript の型・インターフェースを生成するプラグイン。

インストール

npm install --save-dev @kubb/plugin-ts

設定オプション

output

型生成オプション

データ型オプション

詳細オプション

フィルタリング

設定例

import { defineConfig } from "@kubb/core"
import { pluginOas } from "@kubb/plugin-oas"
import { pluginTs } from "@kubb/plugin-ts"

export default defineConfig({
  input: { path: "./petStore.yaml" },
  output: { path: "./src/gen" },
  plugins: [
    pluginOas(),
    pluginTs({
      output: { path: "./types" },
      exclude: [{ type: "tag", pattern: "store" }],
      group: {
        type: "tag",
        name: ({ group }) => `${group}Controller`,
      },
      enumType: "asConst",
      dateType: "date",
      unknownType: "unknown",
      optionalType: "questionTokenAndUndefined",
      paramsCasing: "camelcase",
    }),
  ],
})

@kubb/plugin-vue-query

OpenAPI 仕様から Vue Query（TanStack Query）hooks を生成するプラグイン。

インストール

npm install --save-dev @kubb/plugin-vue-query

設定オプション

@kubb/plugin-react-query とほぼ同一の構成。主な違いは importPath のデフォルト値のみ。

output

client

query / mutation

その他

設定例

pluginVueQuery({
  output: { path: './hooks' },
  group: { type: 'tag', name: ({ group }) => `${group}Hooks` },
  client: { dataReturnType: 'full' },
  query: { methods: ['get'], importPath: '@tanstack/vue-query' },
  infinite: { queryParam: 'next_page', initialPageParam: 0 },
})

@kubb/plugin-zod

OpenAPI スキーマから Zod バリデーションスキーマを生成するプラグイン。Zod v3/v4 対応。

インストール

npm install --save-dev @kubb/plugin-zod

設定オプション

output

Zod 固有オプション

データ型オプション

その他

dateType の例

// false: z.string()
// 'string': z.string().datetime()
// 'stringOffset': z.string().datetime({ offset: true })
// 'stringLocal': z.string().datetime({ local: true })
// 'date': z.date()

coercion の例

// true: z.coerce.string(), z.coerce.date(), z.coerce.number()
// { numbers: true, strings: false }: z.string(), z.coerce.number()

mini モードの例（v4+、ベータ）

import { z } from 'zod/mini'
z.optional(z.string())
z.nullable(z.number())
z.array(z.string()).check(z.minLength(1), z.maxLength(10))

設定例

import { defineConfig } from "@kubb/core"
import { pluginOas } from "@kubb/plugin-oas"
import { pluginTs } from "@kubb/plugin-ts"
import { pluginZod } from "@kubb/plugin-zod"

export default defineConfig({
  input: { path: "./petStore.yaml" },
  output: { path: "./src/gen" },
  plugins: [
    pluginOas(),
    pluginTs(),
    pluginZod({
      output: { path: "./zod" },
      group: { type: "tag", name: ({ group }) => `${group}Schemas` },
      typed: true,
      dateType: "stringOffset",
      unknownType: "unknown",
      version: "4",
      wrapOutput: ({ output }) =>
        `${output}.openapi({ description: 'Custom' })`,
    }),
  ],
})

plugins

API Client Generation

OpenAPI 仕様から Axios または Fetch ベースの型安全な API クライアントを生成するワークフロー。

// kubb.config.ts（Fetch クライアント例）
import { defineConfig } from '@kubb/core'
import { pluginOas } from '@kubb/plugin-oas'
import { pluginTs } from '@kubb/plugin-ts'
import { pluginClient } from '@kubb/plugin-client'

export default defineConfig({
  input: { path: './petStore.yaml' },
  output: { path: './src/gen', clean: true },
  plugins: [
    pluginOas({ generators: [] }),
    pluginTs({
      output: { path: 'models' },
      enumType: 'asConst',
    }),
    pluginClient({
      output: { path: './clients' },
      client: 'fetch',
      group: { type: 'tag', name: ({ group }) => `${group}Service` },
      dataReturnType: 'data',
      pathParamsType: 'object',
    }),
  ],
})

# インストール（Fetch の場合）
npm install --save-dev @kubb/cli @kubb/core @kubb/plugin-oas @kubb/plugin-ts @kubb/plugin-client

# Axios を使う場合は axios も追加
npm install axios

生成されたクライアントの使用例:

import { getPetById } from './gen/clients/PetService'

const pet = await getPetById({ petId: 1 })
console.log(pet.name)

Notes

• client: 'fetch' で Fetch API、client: 'axios' で Axios ベースのコードを生成する
• pluginReactQuery と組み合わせる場合は clientType: 'function'（デフォルト）のままにする
• group: { type: 'tag' } でタグごとにサービスクラス/ファイルを分割できる
• parser: 'zod' を指定するとレスポンスを Zod スキーマで自動バリデーションする

Basic TypeScript Generation

OpenAPI 仕様から TypeScript 型を生成する最小構成のワークフロー。

// kubb.config.ts
import { defineConfig } from '@kubb/core'
import { pluginOas } from '@kubb/plugin-oas'
import { pluginTs } from '@kubb/plugin-ts'

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

# インストール
npm install --save-dev @kubb/cli @kubb/core @kubb/plugin-oas @kubb/plugin-ts

# 生成実行
npx kubb generate

生成結果（src/gen/models/Pet.ts）:

export type Pet = {
  /** @type integer, int64 */
  id: number
  /** @type string */
  name: string
  /** @type string | undefined */
  tag?: string
}

Notes

• pluginOas は必ず最初に配置する（他プラグインのベースとなる）
• generators: [] を指定すると JSON スキーマファイルの生成をスキップできる
• output.clean: true で生成前に出力ディレクトリをクリーンアップする
• input.path にはローカルファイルパスだけでなく URL も指定可能

Filtering and Grouping

include / exclude と group を使い、生成対象のエンドポイントを絞り込み、タグ別にファイルを整理するワークフロー。

// kubb.config.ts
import { defineConfig } from '@kubb/core'
import { pluginOas } from '@kubb/plugin-oas'
import { pluginTs } from '@kubb/plugin-ts'
import { pluginClient } from '@kubb/plugin-client'

export default defineConfig({
  input: { path: './petStore.yaml' },
  output: { path: './src/gen', clean: true },
  plugins: [
    pluginOas({ generators: [] }),
    pluginTs({
      output: { path: 'models' },
      // タグ "store" を除外
      exclude: [{ type: 'tag', pattern: 'store' }],
      // タグごとにファイルをグループ化
      group: {
        type: 'tag',
        name: ({ group }) => `${group}Controller`,
      },
    }),
    pluginClient({
      output: { path: './clients' },
      // operationId でフィルタリング（正規表現可）
      include: [{ type: 'operationId', pattern: '^get' }],
      // path パターンでフィルタリング
      exclude: [{ type: 'path', pattern: '/internal/' }],
      group: { type: 'tag' },
    }),
  ],
})

override でエンドポイントごとにオプションを上書きする例:

pluginReactQuery({
  output: { path: './hooks' },
  override: [
    {
      type: 'operationId',
      pattern: 'listPets',
      options: {
        infinite: {
          queryParam: 'page',
          initialPageParam: 0,
        },
      },
    },
  ],
})

Notes

• include / exclude の type は 'tag' / 'operationId' / 'path' / 'method' / 'contentType' から選択できる
• pattern は文字列（完全一致）または正規表現文字列として評価される
• group.type: 'tag' は OpenAPI の tags フィールドに基づきファイルを分割する
• override はマッチしたエンドポイントのプラグインオプションのみを上書きし、それ以外には影響しない

MSW Mock Handlers Generation

OpenAPI 仕様から MSW（Mock Service Worker）ハンドラーと Faker モックデータを生成するワークフロー。

// kubb.config.ts
import { defineConfig } from '@kubb/core'
import { pluginOas } from '@kubb/plugin-oas'
import { pluginTs } from '@kubb/plugin-ts'
import { pluginFaker } from '@kubb/plugin-faker'
import { pluginMsw } from '@kubb/plugin-msw'

export default defineConfig({
  input: { path: './petStore.yaml' },
  output: { path: './src/gen', clean: true },
  plugins: [
    pluginOas({ generators: [] }),
    pluginTs({ output: { path: 'models' } }),
    pluginFaker({
      output: { path: './mocks' },
      group: { type: 'tag', name: ({ group }) => `${group}Mocks` },
      dateType: 'date',
      seed: [42],
    }),
    pluginMsw({
      output: { path: './msw' },
      group: { type: 'tag', name: ({ group }) => `${group}Handlers` },
      handlers: true,
      parser: 'faker',
    }),
  ],
})

# インストール
npm install --save-dev @kubb/cli @kubb/core @kubb/plugin-oas @kubb/plugin-ts @kubb/plugin-faker @kubb/plugin-msw
npm install msw @faker-js/faker

生成されたハンドラーの使用例:

// src/mocks/browser.ts
import { setupWorker } from 'msw/browser'
import { handlers } from '../gen/msw/handlers'

export const worker = setupWorker(...handlers)

Notes

• pluginFaker を pluginMsw より前に配置する（parser: 'faker' 時に Faker の出力を参照するため）
• handlers: true で全エンドポイントを統合した handlers.ts を生成する
• seed を固定するとテスト実行ごとに同じモックデータが生成される
• parser: 'data'（デフォルト）は空レスポンスを返す最小ハンドラーを生成する

Multi-Plugin Workflow

複数プラグインを組み合わせて TypeScript 型・API クライアント・React Query hooks・Zod スキーマ・MSW ハンドラーを同時生成するフルスタック構成。

// kubb.config.ts
import { defineConfig } from '@kubb/core'
import { pluginOas } from '@kubb/plugin-oas'
import { pluginTs } from '@kubb/plugin-ts'
import { pluginClient } from '@kubb/plugin-client'
import { pluginReactQuery } from '@kubb/plugin-react-query'
import { pluginZod } from '@kubb/plugin-zod'
import { pluginFaker } from '@kubb/plugin-faker'
import { pluginMsw } from '@kubb/plugin-msw'

export default defineConfig({
  input: { path: './petStore.yaml' },
  output: {
    path: './src/gen',
    clean: true,
    barrelType: 'named',
  },
  plugins: [
    pluginOas({ validate: true, collisionDetection: true }),
    pluginTs({
      output: { path: './types' },
      enumType: 'asConst',
      dateType: 'date',
      unknownType: 'unknown',
    }),
    pluginClient({
      output: { path: './clients' },
      client: 'fetch',
      group: { type: 'tag' },
      parser: 'zod',
    }),
    pluginReactQuery({
      output: { path: './hooks' },
      group: { type: 'tag' },
      suspense: {},
    }),
    pluginZod({
      output: { path: './zod' },
      group: { type: 'tag' },
      typed: true,
      dateType: 'stringOffset',
    }),
    pluginFaker({
      output: { path: './mocks' },
      group: { type: 'tag' },
      seed: [42],
    }),
    pluginMsw({
      output: { path: './msw' },
      group: { type: 'tag' },
      handlers: true,
      parser: 'faker',
    }),
  ],
  hooks: {
    done: ['npm run typecheck'],
  },
})

生成されるディレクトリ構造:

src/gen/
├── types/      ← TypeScript 型
├── clients/    ← Fetch ベース API クライアント（Zod パース付き）
├── hooks/      ← React Query hooks（Suspense 対応）
├── zod/        ← Zod バリデーションスキーマ
├── mocks/      ← Faker モックデータジェネレーター
├── msw/        ← MSW ハンドラー
│   └── handlers.ts
└── index.ts    ← バレルエクスポート

Notes

• プラグインの順序は pluginOas → pluginTs → その他の順を守る
• collisionDetection: true でスキーマ名の衝突を自動解決する
• hooks.done で生成後に任意のシェルコマンドを実行できる
• pluginClient の parser: 'zod' は pluginZod と組み合わせてレスポンスを自動バリデーションする

Multiple OpenAPI Specs

複数の OpenAPI 仕様ファイルを1つの設定で並列処理するワークフロー。

// kubb.config.ts
import { defineConfig } from '@kubb/core'
import { pluginOas } from '@kubb/plugin-oas'
import { pluginTs } from '@kubb/plugin-ts'

export default defineConfig([
  {
    name: 'petStore',
    input: { path: './specs/petStore.yaml' },
    output: { path: './src/gen/petStore', clean: true },
    plugins: [
      pluginOas({ generators: [] }),
      pluginTs({ output: { path: 'models' } }),
    ],
  },
  {
    name: 'userApi',
    input: { path: './specs/userApi.yaml' },
    output: { path: './src/gen/userApi', clean: true },
    plugins: [
      pluginOas({ generators: [] }),
      pluginTs({ output: { path: 'models' } }),
    ],
  },
])

URL からリモートの仕様を直接参照する場合:

export default defineConfig([
  {
    name: 'externalApi',
    input: { path: 'https://api.example.com/openapi.json' },
    output: { path: './src/gen/external' },
    plugins: [pluginOas(), pluginTs()],
  },
])

Notes

• 配列形式でエクスポートすると各設定が並列実行される
• name フィールドを指定すると CLI 出力で設定を識別しやすくなる
• リモート URL 参照時はネットワーク到達性とスキーマの安定性に注意する
• 各設定は独立した output.path を持つ必要がある

Programmatic Build

build() API を使い Node.js スクリプトやビルドシステムから Kubb をプログラマティックに実行するワークフロー。

import { build } from '@kubb/core'
import { pluginOas } from '@kubb/plugin-oas'
import { pluginTs } from '@kubb/plugin-ts'

const { error, files } = await build({
  config: {
    root: '.',
    input: { path: './petStore.yaml' },
    output: { path: './src/gen', clean: true },
    plugins: [
      pluginOas({ generators: [] }),
      pluginTs({ output: { path: 'models' } }),
    ],
  },
})

if (error) {
  console.error('Generation failed:', error)
  process.exit(1)
}

console.log(`Generated ${files.length} files`)

カスタムインメモリストレージを使ったドライラン例:

import { build, createStorage } from '@kubb/core'

const store = new Map<string, string>()
const memoryStorage = createStorage(() => ({
  name: 'memory',
  async hasItem(key) { return store.has(key) },
  async getItem(key) { return store.get(key) ?? null },
  async setItem(key, value) { store.set(key, value) },
  async removeItem(key) { store.delete(key) },
  async getKeys(base) { return [...store.keys()].filter(k => k.startsWith(base)) },
  async clear(base) { for (const k of store.keys()) if (k.startsWith(base)) store.delete(k) },
}))

const { files } = await build({
  config: {
    input: { path: './petStore.yaml' },
    output: { path: './gen', storage: memoryStorage },
    plugins: [pluginOas(), pluginTs()],
  },
})

Notes

• build() は { error, files, driver } を返す非同期関数
• error が undefined でない場合は生成失敗
• output.storage にカスタムストレージを渡すとファイルシステムへの書き込みを回避できる
• CI やテストでの生成結果検証、ビルドパイプラインへの組み込みに適している

React Query Hooks Generation

OpenAPI 仕様から TanStack Query（React Query）hooks を生成するワークフロー。

// kubb.config.ts
import { defineConfig } from '@kubb/core'
import { pluginOas } from '@kubb/plugin-oas'
import { pluginTs } from '@kubb/plugin-ts'
import { pluginReactQuery } from '@kubb/plugin-react-query'

export default defineConfig({
  input: { path: './petStore.yaml' },
  output: { path: './src/gen', clean: true },
  plugins: [
    pluginOas({ generators: [] }),
    pluginTs({ output: { path: 'models' } }),
    pluginReactQuery({
      output: { path: './hooks' },
      group: { type: 'tag', name: ({ group }) => `${group}Hooks` },
      client: { dataReturnType: 'data' },
      query: { methods: ['get'] },
      mutation: { methods: ['post', 'put', 'delete'] },
    }),
  ],
})

# インストール
npm install --save-dev @kubb/cli @kubb/core @kubb/plugin-oas @kubb/plugin-ts @kubb/plugin-react-query
npm install @tanstack/react-query

生成された hooks の使用例:

import { useGetPetById } from './gen/hooks'

function PetDetail({ petId }: { petId: number }) {
  const { data: pet } = useGetPetById({ petId })
  return <div>{pet?.name}</div>
}

Notes

• pluginTs を pluginReactQuery より前に配置する（型定義に依存するため）
• group: { type: 'tag' } でタグごとにファイルをグループ化できる
• query.methods: ['get'] で GET のみ useQuery hooks を生成し、それ以外は useMutation となる
• Suspense Query を使う場合は suspense: {} を追加する

samples

Zod Schema Generation

OpenAPI 仕様から Zod バリデーションスキーマを生成するワークフロー。

// kubb.config.ts
import { defineConfig } from '@kubb/core'
import { pluginOas } from '@kubb/plugin-oas'
import { pluginTs } from '@kubb/plugin-ts'
import { pluginZod } from '@kubb/plugin-zod'

export default defineConfig({
  input: { path: './petStore.yaml' },
  output: { path: './src/gen', clean: true },
  plugins: [
    pluginOas({ generators: [] }),
    pluginTs({ output: { path: 'models' } }),
    pluginZod({
      output: { path: './zod' },
      group: { type: 'tag', name: ({ group }) => `${group}Schemas` },
      typed: true,
      dateType: 'stringOffset',
      unknownType: 'unknown',
      version: '4',
    }),
  ],
})

# インストール
npm install --save-dev @kubb/cli @kubb/core @kubb/plugin-oas @kubb/plugin-ts @kubb/plugin-zod
npm install zod

生成されたスキーマの使用例:

import { petSchema } from './gen/zod'

const result = petSchema.safeParse(apiResponse)
if (result.success) {
  console.log(result.data.name)
}

Notes

• typed: true を指定すると TypeScript 型アノテーション付きでスキーマが生成される（pluginTs が必要）
• version: '4' で Zod v4 用のスキーマを生成する（デフォルトは '3'）
• dateType: 'stringOffset' は z.string().datetime({ offset: true }) を生成する
• wrapOutput でスキーマに .openapi() などの後処理を追加できる

cli

Kubb CLI の全コマンドとオプション一覧。

バージョン確認

kubb --version

ヘルプ表示

kubb --help

kubb init: プロジェクトの初期化

npx kubb init

インタラクティブウィザードで kubb.config.ts を生成する。デフォルトで @kubb/plugin-oas と @kubb/plugin-ts が選択される。

kubb generate: コード生成

kubb generate

kubb.config.ts の設定に基づいてコードを生成する。

kubb generate --config ./configs/kubb.config.ts

カスタム設定ファイルを指定する。

kubb generate --watch

入力ファイルの変更を監視してコードを再生成する。

kubb generate --log-level verbose

プラグインのパフォーマンスメトリクスを含む詳細ログを出力する。

kubb generate --debug

完全なデバッグログを出力し、.kubb/ ディレクトリにログファイルを作成する。

kubb generate --silent

全出力を抑制する。

`kubb generate` オプション一覧:

kubb validate: OpenAPI ファイルの検証

kubb validate --input petstore.yaml

Swagger/OpenAPI ファイルの構文と構造をチェックする。@kubb/oas パッケージが必要。

kubb start: HTTP サーバーの起動

kubb start petStore.yaml

kubb start --config kubb.config.ts

SSE（Server-Sent Events）ストリーミング付き HTTP サーバーを起動する。

`kubb start` オプション一覧:

kubb agent: Agent サーバーの管理

kubb agent start

Kubb Studio との WebSocket 連携用 HTTP サーバーを起動する。

kubb agent start --config ./my-config.ts

kubb agent start --host 0.0.0.0 --port 8080

kubb agent start --allow-write

ファイルシステムへの書き込みを許可する。

kubb agent start --allow-all

警告: --allow-all はファイルシステム書き込みを含む全権限を付与する。信頼できる環境でのみ使用すること。

`kubb agent start` オプション一覧:

kubb mcp: MCP サーバーの起動

npx kubb mcp

AI アシスタント（Claude、Cursor 等）向けの MCP（Model Context Protocol）サーバーを起動する。@kubb/mcp パッケージが必要。

scripts