Skip to content
Zod logo

Zod

Officialv5.10.0

@kubb/plugin-zod

kubb add plugin-zod

Options

Pass these options to pluginZod(). Shared options link to Shared plugin options.

Options overview

OptionPurposeDefault
outputWhere files are written.{ path: 'zod', barrel: { type: 'named' } }
groupSplit output by tag or path.None
importPathModule the generated files import z from.'zod', or 'zod/mini' with mini
inferredExport a type next to each schema.false
coercionCoerce input before validation.false
guidTypeValidator for format: uuid.'uuid'
regexTypeHow an OpenAPI pattern is written.'literal'
oneOfTypeHow a oneOf is validated.'union'
compileWrap schemas in z.compile for fast-path validation.false
miniGenerate Zod Mini schemas.false
typeGuardsGenerate is* type guards and assert* assertions.false
printerReplace the handler for a schema type.None
includeKeep only operations and schemas that match.None
excludeSkip operations and schemas that match.[]
overrideApply different options per pattern.[]
resolverCustomize generated names and file paths. See resolver members.resolverZod
macrosRewrite AST nodes before printing.[]

Option details

importPath

Module the generated files import z from, such as your own module that re-exports Zod.

Type'zod' | 'zod/mini' | string
Requiredfalse
Defaultmini ? 'zod/mini' : 'zod'

'zod' and 'zod/mini' are imported as import * as z. Any other module is imported as import { z }, so export z by name.

inferred

Exports a type next to each schema, so you do not need @kubb/plugin-ts.

Typeboolean | 'codec' | 'direction'
Requiredfalse
Defaultfalse
true
Writes z.infer<typeof schema> for every schema.
'codec'
Writes z.input for request schemas and z.output for response schemas, for codecs. See Type codecs on each side.
'direction'
Deprecated name for 'codec'.
export type PetSchemaType = z.infer<typeof petSchema>
With 'codec', set validator: { request: 'zod', params: 'zod' } in @kubb/plugin-fetch or @kubb/plugin-axios, or the client sends the domain value unencoded.

coercion

Wraps schemas in z.coerce to convert input, such as form data and query params, before validation.

Typeboolean | { dates?: boolean, strings?: boolean, numbers?: boolean }
Requiredfalse
Defaultfalse
false
No coercion, except format: int64 fields, which use z.coerce.bigint().pipe(z.int64()) with the adapter's default integerType: 'bigint'.
true
Coerces strings, numbers, and dates.
{ dates?, strings?, numbers? }
Coerces only the primitives you pick.

Coerced fields lose some format checks, such as jwt. See Coerce input with Zod.

guidType

Validator for format: uuid.

Type'uuid' | 'guid'
Requiredfalse
Default'uuid'
'uuid'
Writes z.uuid(), for a standard RFC 4122 UUID.
'guid'
Writes z.guid(), which also accepts Microsoft-style GUIDs.

regexType

How an OpenAPI pattern is written inside .regex(...). Use 'constructor' when a regex literal breaks your build or you need a string pattern.

Type'literal' | 'constructor'
Requiredfalse
Default'literal'
'literal'
Writes .regex(/^[a-z]+$/).
'constructor'
Writes .regex(new RegExp("^[a-z]+$")).

oneOfType

How a oneOf without a discriminator is validated. Use 'xor' when values may carry extra keys.

Type'union' | 'xor'
Requiredfalse
Default'union'
'union'
Writes z.union([...]) with strict object members, so extra keys fail, even keys the spec allows.
'xor'
Writes z.xor([...]), which passes only when exactly one member matches. Needs Zod 4.2 or later.

compile

Wraps schemas in z.compile(...), which generates validation code instead of interpreting the schema on each call. Needs Zod 4.5 or later.

Typeboolean | { strict?: boolean }
Requiredfalse
Defaultfalse
true
Compiles schemas. Parts that cannot compile fall back to the interpreter.
{ strict: true }
Zod throws when a part cannot be compiled, except in schemas Kubb leaves uncompiled.

Circular schemas and coerced fields, int64 included, stay on the interpreter. See Compile Zod schemas.

mini

Generates Zod Mini schemas, which use functions instead of method chains so bundlers can drop unused validators. It sets the importPath default to 'zod/mini'. In beta.

Typeboolean
Requiredfalse
Defaultfalse
status: z.string().optional(),

typeGuards

Generates is* type guards and assert* assertions with Zod's validate API. Needs Zod 4.6 or later.

Typeboolean | { is?: boolean, assert?: boolean }
Requiredfalse
Defaultfalse
true
Writes both is<Schema> and assert<Schema>.
{ is?, assert? }
Both default to true, so { assert: false } writes only the is* guards.
src/gen/zod/petSchema.ts
export const isPet = (data: unknown): data is z.infer<typeof petSchema> => petSchema.validate(data)

export function assertPet(data: unknown): asserts data is z.infer<typeof petSchema> {
  if (!petSchema.validate(data)) {
    petSchema.parse(data)
  }
}

printer

Replaces the handler for a schema type such as 'integer'. Each handler returns the Zod expression as a string, in Zod Mini syntax when mini is true. this.base(node) returns the built-in output, and this.transform(node) recurses into nested nodes. See the printer guide.

Type{ nodes?: PrinterZodNodes | PrinterZodMiniNodes }
Requiredfalse
kubb.config.ts
import { pluginZod } from '@kubb/plugin-zod'

pluginZod({
  printer: {
    nodes: {
      integer() {
        return 'z.number()'
      },
    },
  },
})

To convert requests and responses differently, branch on this.options.direction, as in Encode custom types.

Resolver members

Besides the shared members of resolver, resolverZod has these. Members you leave out keep the default.

Partial override
type ResolverZodPatch = {
  schema?: {
    typeName?(name: string): string
    type?(name: string): string
    inputName?(name: string): string
    inputTypeName?(name: string): string
    isName?(name: string): string
    assertName?(name: string): string
  }
  param?: {
    name?(node: OperationNode, param: ParameterNode): string
    path?(node: OperationNode, param: ParameterNode): string
    query?(node: OperationNode, param: ParameterNode): string
    headers?(node: OperationNode, param: ParameterNode): string
    cookies?(node: OperationNode, param: ParameterNode): string
  }
  response?: {
    status?(node: OperationNode, statusCode: StatusCode): string
    headers?(node: OperationNode, statusCode: StatusCode): string
    body?(node: OperationNode): string
    responses?(node: OperationNode): string
    response?(node: OperationNode): string
    error?(node: OperationNode): string
    options?(node: OperationNode): string
  }
}

Format and type mappings

Kubb maps each OpenAPI format to its Zod v4 call, such as format: email to z.email(). See Zod validators for OpenAPI formats.