@kubb/plugin-faker

Generate mock data using Faker.

Installation

bun

bun add -d @kubb/plugin-faker

pnpm

pnpm add -D @kubb/plugin-faker

npm

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

yarn

yarn add -D @kubb/plugin-faker

Options

output

Specify the export location for the files and define the behavior of the output.

output.path

Path to the output folder or file that contains the generated code.

TIP

if output.path is a file, group cannot be used.

Type:	string
Required:	true
Default:	'mocks'

output.barrelType

Specify what to export and optionally disable barrel file generation.

TIP

Using propagate will prevent a plugin from creating a barrel file, but it will still propagate, allowing output.barrelType to export the specific function or type.

Type:	'all' | 'named' | 'propagate' | false
Required:	false
Default:	'named'

all

export * from "./gen/petService.ts"

named

export { PetService } from "./gen/petService.ts"

propagate

false

output.banner

Add a banner comment at the top of every generated file.

Type:	string | (oas: Oas) => string
Required:	false

output.footer

Add a footer comment at the end of every generated file.

Type:	string | (oas: Oas) => string
Required:	false

output.override

Whether Kubb overrides existing external files that can be generated if they already exist.

Type:	boolean
Required:	false
Default:	false

contentType

Define which content type to use.

By default, Kubb uses the first JSON-valid media type.

Type:	'application/json' | (string & {})
Required:	false

group

Grouping combines files in a folder based on a specific type.

For example, with this configuration:

kubb.config.ts

group: {
  type: 'tag',
  name({ group }){
    return `${group}Controller`
  }
}

This generates the following structure:

.
├── src/
│   └── petController/
│   │   ├── addPet.ts
│   │   └── getPet.ts
│   └── storeController/
│       ├── createStore.ts
│       └── getStoreById.ts
├── petStore.yaml
├── kubb.config.ts
└── package.json

group.type

Specify the property to group files by.

Type:	'tag'
Required:	true

• 'tag': Uses the first tag from operation.getTags().at(0)?.name

group.name

Return the name of a group based on the group name, this will be used for the file and name generation.

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

dateType

Choose to use date or datetime as JavaScript Date instead of string.

Type:	'string' | 'date'
Required:	false
Default:	'string'

'string'

faker.date.anytime().toISOString()

'date'

faker.date.anytime()

dateParser

Which parser should be used when dateType is set to 'string'.

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

TIP

You can use any other library. For example, when you want to use moment you can pass moment and Kubb will add the import for moment: import moment from 'moment'. This only works when the package is using default exports like Dayjs and Moment.

undefined

// schema with format set to 'date'
faker.date.anytime().toISOString().substring(0, 10)

// schema with format set to 'time'
faker.date.anytime().toISOString().substring(11, 19)

'dayjs'

// schema with format set to 'date'
dayjs(faker.date.anytime()).format("YYYY-MM-DD")

// schema with format set to 'time'
dayjs(faker.date.anytime()).format("HH:mm:ss")

'moment'

// schema with format set to 'date'
moment(faker.date.anytime()).format("YYYY-MM-DD")

// schema with format set to 'time'
moment(faker.date.anytime()).format("HH:mm:ss")

mapper

Type:	Record<string, string>
Required:	false

unknownType

Which type to use when the Swagger/OpenAPI file is not providing more information.

Type:	'any' | 'unknown' | 'void'
Required:	false
Default:	'any'

emptySchemaType

Which type to use for empty schema values.

Type:	'any' | 'unknown' | 'void'
Required:	false
Default:	unknownType

paramsCasing

Transform parameter names to a specific casing format for path, query, and header parameters in generated mock data.

IMPORTANT

When using paramsCasing, ensure that @kubb/plugin-ts also has the same paramsCasing setting. This option transforms property names in mock objects to match the TypeScript types.

Type:	'camelcase'
Required:	false
Default:	undefined

• 'camelcase' transforms parameter names to camelCase

With paramsCasing: 'camelcase'

// Mock data uses camelCase property names
export function createFindPetsByStatusPathParamsFaker(
  data?: Partial<FindPetsByStatusPathParams>
): FindPetsByStatusPathParams {
  return {
    ...{ stepId: faker.string.alpha() },  // ✓ camelCase
    ...(data || {}),
  }
}

Without paramsCasing

// Mock data uses original API naming
export function createFindPetsByStatusPathParamsFaker(
  data?: Partial<FindPetsByStatusPathParams>
): FindPetsByStatusPathParams {
  return {
    ...{ step_id: faker.string.alpha() },  // Original naming
    ...(data || {}),
  }
}

regexGenerator

Choose which generator to use when using Regexp.

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

'faker'

faker.helpers.fromRegExp(new RegExp(/test/))

'randexp'

new RandExp(/test/).gen()

seed

The use of Seed is intended to allow for consistent values in a test.

Type:	`number
Required:	false

include

Array containing include parameters to include tags, operations, methods, paths, or content types.

Type:	Array<Include>
Required:	false

Include

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

exclude

Array containing exclude parameters to exclude or skip tags, operations, methods, paths, or content types.

Type:	Array<Exclude>
Required:	false

Exclude

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

override

Array containing override parameters to override options based on tags, operations, methods, paths, or content types.

Type:	Array<Override>
Required:	false

Override

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

generators

See Generators for more information on how to use generators.

Type:	Array<Generator<PluginFaker>>
Required:	false

transformers

transformers.name

Customize the names based on the type that is provided by the plugin.

Type:	(name: string, type?: ResolveType) => string
Required:	false

type ResolveType = 'file' | 'function' | 'type' | 'const'

Example

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

export default defineConfig({
  input: {
    path: './petStore.yaml',
  },
  output: {
    path: './src/gen',
  },
  plugins: [
    pluginOas(),
    pluginTs(),
    pluginFaker({
      output: {
        path: './mocks',
        barrelType: 'named',
        banner: '/* eslint-disable no-alert, no-console */',
        footer: ''
      },
      group: {
        type: 'tag',
        name: ({ group }) => `${group}Service`,
      },
      dateType: 'date',
      unknownType: 'unknown',
      seed: [100],
    }),
  ],
})

See Also

• Faker