Skip to content

@kubb/plugin-cypress ​

Generate Cypress request definitions from your OpenAPI schema.

Installation ​

shell
bun add -d @kubb/plugin-cypress
shell
pnpm add -D @kubb/plugin-cypress
shell
npm install --save-dev @kubb/plugin-cypress
shell
yarn add -D @kubb/plugin-cypress

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:'cypress'

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

paramsType ​

Defines how parameters are passed to generated functions. Switch between object-style parameters and inline parameters.

Type:'object' | 'inline'
Required:false
Default:'inline'

TIP

When paramsType is set to 'object', pathParams will also be set to 'object'.

  • 'object' returns params and pathParams as an object.
  • 'inline' returns params as comma-separated params.
typescript
export async function deletePet(
  {
    petId,
    headers,
  }: {
    petId: DeletePetPathParams['petId']
    headers?: DeletePetHeaderParams
  },
  config: Partial<RequestConfig> = {},
) {
...
}
typescript
export async function deletePet(
  petId: DeletePetPathParams['petId'],
  headers?: DeletePetHeaderParams,
  config: Partial<RequestConfig> = {}
){
  ...
}

paramsCasing ​

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

IMPORTANT

When using paramsCasing, ensure that @kubb/plugin-ts also has the same paramsCasing setting. This option automatically maps transformed parameter names back to their original API names in HTTP requests.

Type:'camelcase'
Required:false
Default:undefined
  • 'camelcase' transforms parameter names to camelCase
typescript
// Function parameters use camelCase
export async function deletePet(
  petId: DeletePetPathParams['petId'],  // ✓ camelCase
  headers?: DeletePetHeaderParams,
  config: Partial<RequestConfig> = {}
) {
  // Automatically maps back to original name for the API
  const pet_id = petId
  
  return fetch({
    method: 'DELETE',
    url: `/pet/${pet_id}`,  // Uses original API parameter name
    ...
  })
}
typescript
// Parameters use original API naming
export async function deletePet(
  pet_id: DeletePetPathParams['pet_id'],  // Original naming
  headers?: DeletePetHeaderParams,
  config: Partial<RequestConfig> = {}
) {
  return fetch({
    method: 'DELETE',
    url: `/pet/${pet_id}`,
    ...
  })
}

TIP

The client automatically generates mapping code to convert camelCase parameter names back to the original API format. You write code with developer-friendly camelCase names, but HTTP requests use the exact parameter names from your OpenAPI specification.

pathParamsType ​

Defines how pathParams are passed to generated functions.

Type:'object' | 'inline'
Required:false
Default:'inline'
  • 'object' returns pathParams as an object.
  • 'inline' returns pathParams as comma-separated params.
typescript
export async function getPetById (
  { petId }: GetPetByIdPathParams,
) {
  ...
}
typescript
export async function getPetById(
  petId: GetPetByIdPathParams,
) {
  ...
}

baseURL ​

Sets a custom base URL for all generated calls.

Type: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}Requests'

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<PluginMsw>>
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 {
pluginTs
} from '@kubb/plugin-ts'
import {
pluginCypress
} from '@kubb/plugin-cypress'
export default
defineConfig
({
input
: {
path
: './petStore.yaml',
},
output
: {
path
: './src/gen',
},
plugins
: [
pluginOas
(),
pluginTs
(),
pluginCypress
({
output
: {
path
: './cypress',
barrelType
: 'named',
banner
: '/* eslint-disable no-alert, no-console */',
footer
: ''
},
group
: {
type
: 'tag',
name
: ({
group
}) => `${
group
}Requests`,
}, }), ], })

See Also ​

Released under the MIT License.