@kubb/plugin-zod

With the Zod plugin you can use Zod to validate your schema's.

Installation

bun

bun add -d @kubb/plugin-zod

pnpm

pnpm add -D @kubb/plugin-zod

npm

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

yarn

yarn add -D @kubb/plugin-zod

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 will contain the generated code.

TIP

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

Type:	string
Required:	true
Default:	'zod'

output.barrelType

Define what needs to be exported, here you can also disable the export of barrel files.

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 text in the beginning of every file.

Type:	string
Required:	false

output.footer

Add a footer text at the end of every file.

Type:	string
Required:	false

group

Grouping makes it possible to combine files in a folder based on specific type.

Imagine you have the following setup:

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

That will create a structure like this:

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

group.type

Define a type where to group the files on.

Type:	'tag'
Required:	true

• 'tag': Use of 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'

importPath

Type:	string
Required:	false
Default:	'zod'

typed

Use TypeScript(@kubb/plugin-ts) to add type annotation.

IMPORTANT

We rely on tozod from the creator of Zod to create a schema based on a type. Kubb contains its own version to those kind of conversions.

Type:	boolean
Required:	false
Default:	false

inferred

Return Zod generated schema as type with z.infer.

Type:	boolean
Required:	false
Default:	false

dateType

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

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

false

z.string()

'string'

z.string().datetime()

'stringOffset'

z.string().datetime({ offset: true })

'stringLocal'

z.string().datetime({ local: true })

'date'

z.date()

unknownType

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

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

'any'

z.any()

'unknown'

z.unknown()

coercion

Use of z.coerce.string() instead of z.string(). Coercion for primitives

Type:	boolean | { dates?: boolean, strings?: boolean, numbers?: boolean}
Required:	false
Default:	false'

true

z.coerce.string()
z.coerce.date()
z.coerce.number()

false

z.string()
z.date()
z.number()

{numbers: true, strings: false, dates: false}

z.string()
z.date()
z.coerce.number()

operations

Type:	boolean
Required:	false
Default:	false

mapper

Type:	Record<string, string>
Required:	false

exclude

Array containing exclude parameters to exclude/skip tags/operations/methods/paths.

Type:	Array<Exclude>
Required:	false

Exclude

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

override

Array containing override parameters to override options based on tags/operations/methods/paths.

Type:	Array<Override>
Required:	false

Override

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

generators

See Generators for more information on how to use generators.

Type:	Array<Generator<PluginZod>>
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'

transformers.schema

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

Type:	(props: { schema?: SchemaObject; name?: string; parentName?: string}, defaultSchemas: Schema[],) => Schema[] | undefined
Required:	false

Example

import { defineConfig } from '@kubb/core'
import { pluginOas } from '@kubb/plugin-oas'
import { pluginZod } from '@kubb/plugin-zod'

export default defineConfig({
  input: {
    path: './petStore.yaml',
  },
  output: {
    path: './src/gen',
  },
  plugins: [
    pluginOas(),
    pluginZod({
      output: {
        path: './zod',
      },
      group: { type: 'tag', name: ({ group }) => `${group}Schemas` },
      typed: true,
      dateType: 'stringOffset',
      unknownType: 'unknown',
      importPath: 'zod'
    }),
  ],
})

Links

• Zod