Official v5.0.0-beta.36 MIT kubb >=5.0.0 node >=22

@kubb/plugin-msw

Generate MSW request handlers from OpenAPI so you can mock the entire API in tests and during local development.

Downloads: 124k / mo
Stars: 3
Bundle size: 240.3 kB
Updated: 4d ago

@kubb/plugin-msw

Generate MSW handlers from your OpenAPI spec. Drop them into your test setup or service worker to mock the API end-to-end — request path, method, status, and response body all stay in sync with the spec.

Combine with @kubb/plugin-faker to seed handlers with realistic data, or feed them custom payloads from tests.

Installation

bunpnpmnpmyarn

shell

bun add -d @kubb/plugin-msw@beta

shell

pnpm add -D @kubb/plugin-msw@beta

shell

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

shell

yarn add -D @kubb/plugin-msw@beta

Options

output

Where the generated MSW handlers are written and how they are exported.

Type:	`Output`
Required:	`false`
Default:	`{ path: 'handlers', barrel: { type: 'named' } }`

output.path

Folder (or single file) where the plugin writes its generated code. The path is resolved against the global output.path set on defineConfig.

Use a folder to keep each generator's output isolated ('types', 'clients', 'hooks'). Use a single file when you want everything in one place, for example 'api.ts'.

Type:	`string`
Required:	`true`
Default:	`'handlers'`

TIP

When output.path points to a single file, the group option cannot be used because every operation ends up in the same file.

kubb.config.tsResulting tree

typescript

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

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

text

src/
└── gen/
    └── types/
        ├── Pet.ts
        └── Store.ts

output.barrel

Controls how the generated index.ts (barrel) file re-exports the plugin's output.

{ type: 'named' } re-exports each symbol by name. Best for tree-shaking and explicit imports.
{ type: 'all' } uses export *. Smaller barrel file, but exports everything.
{ nested: true } creates a barrel in every subdirectory, so callers can import from any depth.
false skips the barrel entirely. The plugin's files are also excluded from the root index.ts.

Type:	`{ type: 'named' \| 'all', nested?: boolean } \| false`
Required:	`false`
Default:	`{ type: 'named' }`

TIP

Pick 'named' when consumers care about which symbols they import (better tree-shaking, friendlier auto-import). Pick 'all' when the file count is small and you want a one-line barrel.

typescript

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

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

typescript

export { Pet, PetStatus } from './Pet'
export { Store } from './Store'

typescript

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

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

typescript

export * from './Pet'
export * from './Store'

typescript

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

export default defineConfig({
  input: { path: './petStore.yaml' },
  output: { path: './src/gen' },
  plugins: [
    pluginTs({
      output: { barrel: { type: 'named', nested: true } },
    }),
  ],
})

text

src/gen/types/
├── index.ts          # re-exports ./petController and ./storeController
├── petController/
│   ├── index.ts      # re-exports Pet, Store, ...
│   └── Pet.ts
└── storeController/
    ├── index.ts
    └── Store.ts

typescript

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

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

text

# No index.ts is generated for this plugin.
# Its files are also excluded from the root index.ts.

Text prepended to every generated file. Useful for license headers, lint disables, or @ts-nocheck directives.

Pass a string for a static banner. Pass a function to compute the banner from each file's RootNode (the AST root containing path, schema, and operation context).

Type:	`string \| ((node: RootNode) => string)`
Required:	`false`

Static bannerGenerated fileDynamic banner

typescript

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

export default defineConfig({
  input: { path: './petStore.yaml' },
  output: { path: './src/gen' },
  plugins: [
    pluginTs({
      output: {
        banner: '/* eslint-disable */\n// @ts-nocheck',
      },
    }),
  ],
})

typescript

/* eslint-disable */
// @ts-nocheck
export type Pet = {
  id: number
  name: string
}

typescript

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

export default defineConfig({
  input: { path: './petStore.yaml' },
  output: { path: './src/gen' },
  plugins: [
    pluginTs({
      output: {
        banner: (node) => `// Source: ${node.path}\n// Generated at ${new Date().toISOString()}`,
      },
    }),
  ],
})

Text appended at the end of every generated file. The mirror of banner — use it for closing comments, re-enabling lint rules, or marker lines.

Pass a string for a static footer, or a function that receives the file's RootNode and returns the footer text.

Type:	`string \| ((node: RootNode) => string)`
Required:	`false`

Re-enable lint after a banner disable

typescript

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

export default defineConfig({
  input: { path: './petStore.yaml' },
  output: { path: './src/gen' },
  plugins: [
    pluginTs({
      output: {
        banner: '/* eslint-disable */',
        footer: '/* eslint-enable */',
      },
    }),
  ],
})

output.override

Allows the plugin to overwrite hand-written files that share a name with a generated file.

false (default): Kubb skips a file if it already exists and is not marked as generated. This protects manual edits.
true: Kubb overwrites any file at the target path, including hand-written ones.

Type:	`boolean`
Required:	`false`
Default:	`false`

WARNING

Enable this only when you are sure the target folder contains nothing you need to keep. Local edits are lost on the next generation.

kubb.config.ts

typescript

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

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

handlers

Emits a handlers.ts file that re-exports every generated handler grouped by HTTP method. Drop this file into your MSW setupServer(...handlers) or setupWorker(...handlers) call.

Type:	`boolean`
Required:	`false`
Default:	`false`

setup.ts

typescript

import { setupServer } from 'msw/node'
import { handlersGet, handlersPost } from './gen/handlers'

export const server = setupServer(...handlersGet, ...handlersPost)

baseURL

Base URL prepended to every request URL in the generated client. When omitted, the URL comes from the OpenAPI spec's servers[0].url (or whichever index the adapter is configured to read).

Set this when the generated client should point at a different environment (staging, production) than the one written in the spec.

Type:	`string`
Required:	`false`

Override the spec’s server URL

typescript

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

export default defineConfig({
  input: { path: './petStore.yaml' },
  output: { path: './src/gen' },
  plugins: [
    pluginClient({
      baseURL: 'https://petstore.swagger.io/v2',
    }),
  ],
})

group

Splits generated files into subfolders based on the operation's tag, so each tag in your OpenAPI spec gets its own directory.

Without group, every file lands in the plugin's output.path folder. With group, files are bucketed under {output.path}/{groupName}/, where groupName is derived from the operation's first tag.

Type:	`Group`
Required:	`false`

TIP

Use group to mirror your API's domain structure (pet, store, user) in the generated code. Combine it with output.barrel: { type: 'named', nested: true } to get per-tag barrel files.

kubb.config.ts

typescript

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

export default defineConfig({
  input: { path: './petStore.yaml' },
  output: { path: './src/gen' },
  plugins: [
    pluginTs({
      group: {
        type: 'tag',
        name: ({ group }) => `${group}Controller`,
      },
    }),
  ],
})

With the configuration above, the generator emits:

text

src/gen/
├── petController/
│   ├── AddPet.ts
│   └── GetPet.ts
└── storeController/
    ├── CreateStore.ts
    └── GetStoreById.ts

group.type

Property used to assign each operation to a group. Required whenever group is set.

Today only 'tag' is supported: Kubb reads the first tag on the operation (operation.getTags().at(0)?.name) and uses it as the group key. Operations without a tag are placed in a default group.

Type:	`'tag'`
Required:	`true`

NOTE

Required: true* is conditional — only required when the parent group option is used. group itself stays optional.

group.name

Function that builds the folder/identifier name from a group key (the operation's first tag).

Type:	`(context: GroupContext) => string`
Required:	`false`
Default:	`(ctx) => \`${ctx.group}Controller``

parser

Source of the response body returned by each generated handler.

'data' (default) — handlers return a typed empty/example payload, ready for you to fill in from tests.
'faker' — handlers return a value produced by @kubb/plugin-faker. Requires the Faker plugin in the plugins array.

Type:	`'data' \| 'faker'`
Required:	`false`
Default:	`'data'`

’faker’

typescript

import { defineConfig } from 'kubb'
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' },
  plugins: [
    pluginTs(),
    pluginFaker(),
    pluginMsw({ parser: 'faker' }),
  ],
})

include

Restricts generation to operations that match at least one entry in the list. Anything not matched is skipped.

Each entry filters by one of:

tag — the operation's first tag in the OpenAPI spec.
operationId — the operation's operationId.
path — the URL pattern ('/pet/{petId}').
method — HTTP method ('get', 'post', ...).
contentType — the media type of the request body.

pattern accepts either a string (exact match) or a RegExp for fuzzy matches.

Type:	`Array<Include>`
Required:	`false`

Type definition

typescript

export type Include = {
  type: 'tag' | 'operationId' | 'path' | 'method' | 'contentType'
  pattern: string | RegExp
}

Only the pet tagOnly GET operations under /pet

typescript

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

export default defineConfig({
  input: { path: './petStore.yaml' },
  output: { path: './src/gen' },
  plugins: [
    pluginTs({
      include: [
        { type: 'tag', pattern: 'pet' },
      ],
    }),
  ],
})

typescript

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

export default defineConfig({
  input: { path: './petStore.yaml' },
  output: { path: './src/gen' },
  plugins: [
    pluginTs({
      include: [
        { type: 'method', pattern: 'get' },
        { type: 'path', pattern: /^\/pet/ },
      ],
    }),
  ],
})

exclude

Skips any operation that matches at least one entry in the list. The opposite of include.

Each entry filters by one of:

tag — the operation's first tag.
operationId — the operation's operationId.
path — the URL pattern ('/pet/{petId}').
method — HTTP method ('get', 'post', ...).
contentType — the media type of the request body.

pattern accepts a plain string or a RegExp. When both include and exclude are set, exclude wins.

Type:	`Array<Exclude>`
Required:	`false`

Type definition

typescript

export type Exclude = {
  type: 'tag' | 'operationId' | 'path' | 'method' | 'contentType'
  pattern: string | RegExp
}

Skip everything under the store tagSkip a specific operation and all delete methods

typescript

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

export default defineConfig({
  input: { path: './petStore.yaml' },
  output: { path: './src/gen' },
  plugins: [
    pluginTs({
      exclude: [
        { type: 'tag', pattern: 'store' },
      ],
    }),
  ],
})

typescript

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

export default defineConfig({
  input: { path: './petStore.yaml' },
  output: { path: './src/gen' },
  plugins: [
    pluginTs({
      exclude: [
        { type: 'operationId', pattern: 'deletePet' },
        { type: 'method', pattern: 'delete' },
      ],
    }),
  ],
})

override

Applies a different set of plugin options to operations that match a pattern. Use this when most of your API should follow the global config, but a handful of endpoints need different treatment.

Each entry has the same type and pattern shape as include/exclude, plus an options object that overrides the plugin's options for matched operations.

Entries are evaluated top to bottom. The first matching entry's options is merged onto the plugin defaults; later entries do not stack.

Type:	`Array<Override>`
Required:	`false`

Type definition

typescript

export type Override = {
  type: 'tag' | 'operationId' | 'path' | 'method' | 'contentType'
  pattern: string | RegExp
  options: PluginOptions
}

Use a different enum style for the user tag

typescript

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

export default defineConfig({
  input: { path: './petStore.yaml' },
  output: { path: './src/gen' },
  plugins: [
    pluginTs({
      enumType: 'asConst',
      override: [
        {
          type: 'tag',
          pattern: 'user',
          options: { enumType: 'literal' },
        },
      ],
    }),
  ],
})

generators experimental

Adds custom generators that run alongside the plugin's built-in generators. Each generator can emit additional files or post-process existing ones using the plugin's AST and options.

Use this when you need output the plugin does not produce out of the box (a custom client wrapper, an extra index, a metadata file). For end-to-end guidance, see Creating plugins.

Type:	`Array<Generator<PluginMsw>>`
Required:	`false`

WARNING

Generators are an experimental, low-level API. The signature may change between minor releases.

resolver

Overrides how the plugin builds names and paths for generated files and symbols. Use this to add prefixes, suffixes, or to swap the casing strategy without forking the plugin.

Only override the methods you want to change. Anything you omit falls back to the plugin's default resolver. A method that returns null or undefined also falls back.

Inside each method, this is bound to the full resolver, so you can call this.default(name, 'function') to delegate to the built-in implementation.

Type:	`Partial<ResolverMsw> & ThisType<ResolverMsw>`
Required:	`false`

TIP

Use resolver for naming and file-location tweaks. For changing the AST nodes themselves (e.g. stripping descriptions), use transformer instead.

Prefix every handler name with ”Mock”

typescript

import { defineConfig } from 'kubb'
import { pluginMsw } from '@kubb/plugin-msw'

export default defineConfig({
  input: { path: './petStore.yaml' },
  output: { path: './src/gen' },
  plugins: [
    pluginMsw({
      resolver: {
        resolveName(name) {
          return `Mock${this.default(name, 'function')}`
        },
      },
    }),
  ],
})

Each plugin ships with a default resolver:

Plugin	Default resolver
`@kubb/plugin-ts`	`resolverTs`
`@kubb/plugin-zod`	`resolverZod`
`@kubb/plugin-faker`	`resolverFaker`
`@kubb/plugin-cypress`	`resolverCypress`
`@kubb/plugin-msw`	`resolverMsw`
`@kubb/plugin-mcp`	`resolverMcp`
`@kubb/plugin-client`	`resolverClient`

transformer

Modifies AST nodes before they are printed to source code. Use this when you need to rewrite operation IDs, drop descriptions, or change schema metadata without forking the generator.

Each visitor method (e.g. schema, operation) receives the node and a context object. Return a new node to replace it, or return undefined to leave it untouched. Methods you omit keep the plugin's default behavior.

Type:	`Visitor`
Required:	`false`

TIP

Use transformer to rewrite node properties before printing. For changing the names of generated symbols and files, use resolver instead.

Strip descriptions before printingPrefix every operationId

typescript

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

export default defineConfig({
  input: { path: './petStore.yaml' },
  output: { path: './src/gen' },
  plugins: [
    pluginTs({
      transformer: {
        schema(node) {
          return { ...node, description: undefined }
        },
      },
    }),
  ],
})

typescript

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

export default defineConfig({
  input: { path: './petStore.yaml' },
  output: { path: './src/gen' },
  plugins: [
    pluginTs({
      transformer: {
        operation(node) {
          return { ...node, operationId: `api_${node.operationId}` }
        },
      },
    }),
  ],
})

Dependencies

This plugin requires the following plugins to be installed:

Example

kubb.config.ts

typescript

import { defineConfig } from 'kubb'
import { pluginMsw } from '@kubb/plugin-msw'
import { pluginTs } from '@kubb/plugin-ts'

export default defineConfig({
  input: { path: './petStore.yaml' },
  output: { path: './src/gen' },
  plugins: [
    pluginTs(),
    pluginMsw({
      output: { path: './mocks' },
      group: {
        type: 'tag',
        name: ({ group }) => `${group}Service`,
      },
      handlers: true,
    }),
  ],
})

Resources

Tags

Details

@kubb/plugin-msw

@kubb/plugin-msw

Installation

Options

output

output.path

output.barrel

output.banner

output.footer

output.override

handlers

baseURL

group

group.type

group.name

parser

include

exclude

override

generators experimental

resolver

transformer

Dependencies

Example

Resources

Tags

Details

Our Sponsors

@kubb/plugin-msw ​

Installation ​

Options ​

output ​

output.path ​

output.barrel ​

output.banner ​

output.footer ​

output.override ​

handlers ​

baseURL ​

group ​

group.type ​

group.name ​

parser ​

include ​

exclude ​

override ​

generators experimental ​

resolver ​

transformer ​

Dependencies ​

Example ​

@kubb/plugin-msw

Installation

Options

output

output.path

output.barrel

output.banner

output.footer

output.override

handlers

baseURL

group

group.type

group.name

parser

include

exclude

override

generators experimental

resolver

transformer

Dependencies

Example