Skip to content

@kubb/plugin-faker ​

Generate mock data using Faker.

Installation ​

shell
bun add -d @kubb/plugin-faker
shell
pnpm add -D @kubb/plugin-faker
shell
npm install --save-dev @kubb/plugin-faker
shell
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'
typescript
export * from "./gen/petService.ts"
typescript
export { PetService } from "./gen/petService.ts"
typescript
typescript

output.banner ​

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

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

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
typescript
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'
typescript
faker.date.anytime().toISOString()
typescript
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.

typescript
// 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)
typescript
// 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")
typescript
// 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
typescript
// Mock data uses camelCase property names
export function createFindPetsByStatusPathParamsFaker(
  data?: Partial<FindPetsByStatusPathParams>
): FindPetsByStatusPathParams {
  return {
    ...{ stepId: faker.string.alpha() },  // ✓ camelCase
    ...(data || {}),
  }
}
typescript
// 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'
typescript
faker.helpers.fromRegExp(new RegExp(/test/))
typescript
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
typescript
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
typescript
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
typescript
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
typescript
type ResolveType = 'file' | 'function' | 'type' | 'const'

Example ​

typescript
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 ​

Released under the MIT License.