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

@kubb/plugin-faker

Generate Faker.js mock-data factories from OpenAPI for tests, Storybook, and seeded local data.

Downloads: 161k / mo
Stars: 3
Bundle size: 386.1 kB
Updated: 2d ago

@kubb/plugin-faker

Generate a mock-data factory function for every schema in your OpenAPI spec, powered by Faker.js. Call createPet() to get a realistic Pet object — useful for tests, Storybook, and local development without a running backend.

Pair with @kubb/plugin-msw to mock entire endpoints, or use the factories directly in your test suite.

Installation

bunpnpmnpmyarn

shell

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

shell

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

shell

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

shell

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

Options

output

Where the generated mock factories are written and how they are exported.

Type:	`Output`
Required:	`false`
Default:	`{ path: 'mocks', 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:	`'mocks'`

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 },
    }),
  ],
})

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``

dateParser

Library used to format date, time, and datetime fields that are represented as strings.

Use a value other than 'faker' when you already have a date library in the project and want consistent formatting across mocks and runtime. The plugin auto-imports the default export of the library you choose.

Type:	`'faker' \| 'dayjs' \| 'moment' \| string`
Required:	`false`
Default:	`'faker'`

TIP

Any library exporting a default function works (dayjs, moment, luxon, ...). Kubb adds the import statement for you.

’faker’ (default)’dayjs’’moment’

typescript

faker.date.anytime().toISOString().substring(0, 10)

typescript

dayjs(faker.date.anytime()).format('YYYY-MM-DD')

typescript

moment(faker.date.anytime()).format('YYYY-MM-DD')

mapper

Maps OpenAPI schema names to specific Faker expressions. Use this when the schema name does not give Faker enough context to pick a sensible value ('email', 'phone', 'avatarUrl').

Keys are the schema name (case-sensitive); values are the JavaScript expression that produces the mock value.

Type:	`Record<string, string>`
Required:	`false`

kubb.config.ts

typescript

import { defineConfig } from 'kubb'
import { pluginFaker } from '@kubb/plugin-faker'

export default defineConfig({
  input: { path: './petStore.yaml' },
  output: { path: './src/gen' },
  plugins: [
    pluginFaker({
      mapper: {
        email: 'faker.internet.email()',
        avatarUrl: 'faker.image.avatar()',
      },
    }),
  ],
})

paramsCasing

Renames properties inside the generated path/query/header mocks. Body mocks are unaffected.

Type:	`'camelcase'`
Required:	`false`

IMPORTANT

Set the same paramsCasing here as on @kubb/plugin-ts so the generated mocks stay assignable to the generated types.

regexGenerator

Library used to generate strings that satisfy a regex pattern keyword in the OpenAPI spec.

'faker' (default) — faker.helpers.fromRegExp(...). No extra dependency.
'randexp' — uses the randexp package, which supports a wider regex grammar (lookaheads, named groups) but adds a runtime dependency.

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

’faker’ (default)’randexp’

typescript

faker.helpers.fromRegExp('^[A-Z]+$')

typescript

new RandExp(/^[A-Z]+$/).gen()

seed

Seed value passed to faker.seed(...). Set this to get deterministic output across runs — handy for snapshot tests and reproducible local data.

Type:	`number \| number[]`
Required:	`false`

Deterministic seed

typescript

import { defineConfig } from 'kubb'
import { pluginFaker } from '@kubb/plugin-faker'

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

locale

Faker locale used for generated mock values. Switches the named import to fakerXX from @faker-js/faker so names, addresses, and phone numbers reflect the target region.

Defaults to 'en', which imports fakerEN.

Type:	`string`
Required:	`false`
Default:	`'en'`

TIP

See Faker.js localization for the full list of locale codes.

’de’’de_AT’

typescript

import { fakerDE as faker } from '@faker-js/faker'

typescript

import { fakerDE_AT as faker } from '@faker-js/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<PluginFaker>>`
Required:	`false`

WARNING

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

resolver

Customizes the naming of the generated factory helpers. Common use case: append Mock or Factory so the helpers do not clash with the imported types.

Type:	`Partial<ResolverFaker>`
Required:	`false`

Append ”Mock” to every factory name

typescript

import { defineConfig } from 'kubb'
import { pluginFaker } from '@kubb/plugin-faker'

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

transformer

AST visitor applied to schema/operation nodes before code is printed. Use this to drop descriptions or rewrite metadata before the mock factory is built.

Type:	`ast.Visitor`
Required:	`false`

Strip schema descriptions

typescript

import { defineConfig } from 'kubb'
import { pluginFaker } from '@kubb/plugin-faker'

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

printer

Replaces the Faker handler for a specific schema type (e.g. 'integer', 'date', 'ref'). Each handler returns the Faker expression as a string.

Use this.transform to recurse into nested schema nodes and this.options to read printer options.

Type:	`{ nodes?: PrinterFakerNodes }`
Required:	`false`

Use faker.number.float() for integersOverride date strings

typescript

import { defineConfig } from 'kubb'
import { pluginFaker } from '@kubb/plugin-faker'

export default defineConfig({
  input: { path: './petStore.yaml' },
  output: { path: './src/gen' },
  plugins: [
    pluginFaker({
      printer: {
        nodes: {
          integer() {
            return 'faker.number.float()'
          },
        },
      },
    }),
  ],
})

typescript

import { defineConfig } from 'kubb'
import { pluginFaker } from '@kubb/plugin-faker'

export default defineConfig({
  input: { path: './petStore.yaml' },
  output: { path: './src/gen' },
  plugins: [
    pluginFaker({
      printer: {
        nodes: {
          date(node) {
            if (node.representation === 'string') {
              return 'new Date().toISOString().substring(0, 10)'
            }

            return 'new Date()'
          },
        },
      },
    }),
  ],
})

Dependencies

This plugin requires the following plugins to be installed:

@kubb/plugin-ts

Example

kubb.config.ts

typescript

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

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

Resources

Tags

Details

@kubb/plugin-faker

@kubb/plugin-faker

Installation

Options

output

output.path

output.barrel

output.banner

output.footer

output.override

group

group.type

group.name

dateParser

mapper

paramsCasing

regexGenerator

seed

locale

include

exclude

override

generators experimental

resolver

transformer

printer

Dependencies

Example

Resources

Tags

Details

Our Sponsors

@kubb/plugin-faker ​

Installation ​

Options ​

output ​

output.path ​

output.barrel ​

output.banner ​

output.footer ​

output.override ​

group ​

group.type ​

group.name ​

dateParser ​

mapper ​

paramsCasing ​

regexGenerator ​

seed ​

locale ​

include ​

exclude ​

override ​

generators experimental ​

resolver ​

transformer ​

printer ​

Dependencies ​

Example ​

@kubb/plugin-faker

Installation

Options

output

output.path

output.barrel

output.banner

output.footer

output.override

group

group.type

group.name

dateParser

mapper

paramsCasing

regexGenerator

seed

locale

include

exclude

override

generators experimental

resolver

transformer

printer

Dependencies

Example