Options

Pass these options to pluginFaker(), all of them optional. Shared options link to Shared plugin options.

Options overview

Option	Purpose	Default
`output`	Where files are written: `path`, `mode`, `barrel`, `banner`, `footer`.	`{ path: 'mocks', barrel: { type: 'named' } }`
`group`	Split output by tag or path: `type`, `name`.	None
`typeMode`	Whether factory types come from the generated values or the declared model.	`'inferred'`
`dateParser`	Library that formats string date and time fields.	`'faker'`
`regexGenerator`	Library that turns a regex `pattern` into a string.	`'faker'`
`locale`	Faker locale code for the generated values.	`'en'`
`seed`	Value passed to `faker.seed(...)` for deterministic output.	None
`include`	Keep only operations and schemas that match.	None
`exclude`	Skip operations and schemas that match.	`[]`
`override`	Apply different options per pattern.	`[]`
`resolver`	Customize generated names and file paths.	`resolverFaker`
`macros`	Rewrite AST nodes before printing.	`[]`
`printer`	Replace the handler for a schema type.	None

Option details

typeMode

Controls the input and return types of object and intersection factories. Both modes generate the same values and apply overrides with a shallow merge.


Type	`'inferred' \| 'schema'`
Required	`false`
Default	`'inferred'`

'inferred'

Default value. Derives return types from generated values and supplied overrides. Optional and nullable fields retain their concrete value types, and overrides preserve literal types.

'schema'

Accepts Partial<Model> and returns the declared model type, including optional and nullable fields. Use it for fixtures you modify after creation.

// export function createOrder<TData extends Partial<Order> = object>(data?: TData)
const order = createOrder({ quantity: 2, complete: true })
const complete: true = order.complete

// TypeScript error: false is not assignable to true.
order.complete = false

// export function createOrder(data?: Partial<Order>): Order
const order = createOrder({ quantity: 2, complete: true })
order.complete = false

// TypeScript error: foo does not exist in Partial<Order>.
createOrder({ quantity: 2, foo: '' })

Use override to select a mode for matching schemas. String patterns are regular expressions, so '^Order$' matches only the Order schema:

kubb.config.ts

pluginFaker({
  override: [{ type: 'schemaName', pattern: '^Order$', options: { typeMode: 'schema' } }],
})

Library used to format date and time fields represented as strings. Pick a value other than 'faker' when your project already uses a date library, and install that library in the consuming app. Generated date and time strings use YYYY-MM-DD and HH:mm:ss, and date-time values keep the ISO string.


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

'faker'

Default value. Renders a date field as faker.date.anytime().toISOString().substring(0, 10).

'dayjs'

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

'moment'

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

Custom module

Pass a module name that exports a default formatting function. Kubb adds the import to generated files.

regexGenerator

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


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

'faker'

Default value. Generates faker.helpers.fromRegExp(pattern) without an extra dependency.

'randexp'

Generates new RandExp(pattern).gen(). Supports a wider regex grammar and requires the randexp runtime dependency.

locale

Faker locale code. It switches the named import to fakerXX from @faker-js/faker, so generated values reflect the target region. The default 'en' imports fakerEN, 'de' imports fakerDE, and 'de_AT' imports fakerDE_AT. See Faker.js localization for all locale codes.


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

seed

Kubb passes this value to faker.seed(...) at the top of each factory, so every run returns the same data. Use it for snapshot tests. Pass a single number or an array of numbers. Factories still accept overrides, such as createPet({ name: 'Rex' }).


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

resolver

Overrides generated file and symbol names. Omitted members keep resolverFaker. The shared members (name, file, imports) and the this context are described under resolver.


Type	`ResolverPatch<ResolverFaker>`
Required	`false`

Partial override

type ResolverFakerPatch = {
  name?(name: string): string
  file?: {
    baseName?(params: { name: string; extname: string }): string
    path?(params: { baseName: string; output: Output }): string
  }
  imports?(options: ResolveImportsOptions): Array<ImportNode>
  param?: {
    name?(node: OperationNode, param: ParameterNode): string    // → 'showPetByIdPathPetId'
    path?(node: OperationNode, param: ParameterNode): string     // → 'createShowPetByIdPath'
    query?(node: OperationNode, param: ParameterNode): string    // → 'createListPetsQuery'
    headers?(node: OperationNode, param: ParameterNode): string  // → 'createDeletePetHeaders'
  }
  response?: {
    status?(node: OperationNode, statusCode: StatusCode): string // → 'listPetsStatus200'
    body?(node: OperationNode): string                           // → 'createPetsBody'
    response?(node: OperationNode): string                       // → 'listPetsResponse'
    responses?(node: OperationNode): string                      // → 'listPetsResponses'
  }
}

printer

Replaces the Faker node handler for a specific schema type, such as 'integer', 'date', or 'string'. Each handler returns the Faker expression as a string. Use this.transform to recurse into nested nodes and this.options to read printer options. The printer guide covers how overrides compose with macros.


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

Map integer schemas to a float

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

pluginFaker({
  printer: {
    nodes: {
      integer() {
        return 'faker.number.float()'
      },
    },
  },
})