Options

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

Options overview

Option details

importPath

Module the generated files import z from. Point it at your own module to re-export Zod.

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

inferred

Exports a type alias next to each schema, so you do not need @kubb/plugin-ts. The type takes the PascalCase schema name plus SchemaType, so petSchema gets PetSchemaType.

export type PetSchemaType = z.infer<typeof petSchema>

With 'codec', request types read the schema's input:

export type PutEventBodySchemaType = z.input<typeof putEventBodySchema>

Pair 'codec' with validator: { request: 'zod', params: 'zod' } in @kubb/plugin-fetch or @kubb/plugin-axios. Without request validation, the client sends the domain value unencoded.

It also writes a ResponsesSchema for each operation (one schema per status code) and its inferred type. @kubb/plugin-fetch and @kubb/plugin-axios key their RequestResult on it when @kubb/plugin-ts is absent.

coercion

Wraps schemas in z.coerce so input is coerced before validation, for form data, query params, and similar string sources. See Coercion for primitives.

guidType

Validator used for OpenAPI properties with format: uuid.

regexType

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

oneOfType

Controls how a oneOf is validated. Use 'xor' when values may carry extra keys, or when members have no required keys.

A oneOf with a discriminator, where every member is an object, prints z.discriminatedUnion(...) with either value. An anyOf always prints z.union(...).

compile

Wraps schemas in z.compile(...) to generate validation code instead of interpreting the schema on each call. Needs Zod v4.5.0 or higher.

Schemas with circular references (z.lazy) and bare $ref response aliases stay uncompiled to prevent runtime errors.

mini

Generates Zod Mini schemas. They use functions (z.optional(z.string())) instead of method chains (z.string().optional()), so bundlers can drop unused validators. Also sets the importPath default to 'zod/mini'.

typeGuards

Generates TypeScript type guards (is*) and assertion functions (assert*) with Zod's validate API. Needs Zod v4.6.0 or higher.

When inferred is true, the guards narrow to the generated type alias such as PetSchemaType. When mini is true, they route through z.validate and z.parse.

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)
  }
}

resolver

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

type ResolverZodPatch = {
  // plus the shared name, file, and imports members
  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
  }
  response?: {
    status?(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
  }
}

printer

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

import { pluginZod } from '@kubb/plugin-zod'

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

A handler can read this.options.direction, which is 'decode' for responses and 'encode' for request bodies and parameters. If it returns a different expression per direction, Kubb also writes an ${name}InputSchema. Request bodies use it, including bodies that reach the schema through a $ref. See Encode custom types.