Options

Pass these options to pluginZod(). Shared options link to Shared plugin options, which documents their behavior once.

Options overview

Option details

importPath

Module specifier for the import { z } from '...' statement in every generated file, so you can re-export Zod from your own module.

inferred

Exports a z.infer<typeof schema> type alias next to every generated schema, so the schema is the single source of truth and you do not import types from @kubb/plugin-ts. The alias is the PascalCased schema name with a SchemaType suffix, so petSchema becomes PetSchemaType.

import * as z from 'zod'

export const petSchema = z.object({
  name: z.string(),
})

export type PetSchemaType = z.infer<typeof petSchema>

It also generates a ResponsesSchema per operation, the per-status responses record, with 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.

compile

Wraps schemas in z.compile(...) to generate validation code instead of interpreting the schema on each call.

import * as z from 'zod'

export const petSchema = z.compile(
  z.object({
    id: z.number(),
    name: z.string(),
  }),
  { strict: true }, // omitted with compile: true
)

mini

Switches code generation to Zod Mini, which uses the functional API (z.optional(z.string())) instead of the chainable one (z.string().optional()) so bundlers can tree-shake unused validators. mini: true also defaults importPath to 'zod/mini'.

import * as z from 'zod/mini'

z.optional(z.string())
z.nullable(z.number())
z.array(z.string()).check(z.minLength(1), z.maxLength(10))

typeGuards

Generates TypeScript type guards (is*) and assertion functions (assert*) for schemas using Zod v4's native validate API.

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.

Use the generated guard to filter unknown data, or assert a value before reading it:

import { isPet, assertPet } from './src/gen/zod/petSchema'

const items: unknown[] = []
const pets = items.filter(isPet)

export function processPayload(payload: unknown) {
  assertPet(payload)
  console.log(payload.name)
}

import * as z from 'zod'

export const petSchema = z.object({
  id: z.int32(),
  name: z.string(),
})

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 = {
  name?(name: string): string
  file?: {
    baseName?(params: { name: string; extname: string }): string
    path?(params: { baseName: string; output: Output }): string
  }
  imports?(options: ResolveImportsOptions): Array<ImportNode>
  schema?: {
    typeName?(name: string): string       // → 'PetSchemaType'
    type?(name: string): string           // → 'PetSchemaType'
    inputName?(name: string): string      // → 'orderInputSchema'
    inputTypeName?(name: string): string  // → 'OrderInputSchemaType'
    isName?(name: string): string         // → 'isPet'
    assertName?(name: string): string     // → 'assertPet'
  }
  param?: {
    name?(node: OperationNode, param: ParameterNode): string    // → 'deletePetPathPetIdSchema'
    path?(node: OperationNode, param: ParameterNode): string     // → 'deletePetPathSchema'
    query?(node: OperationNode, param: ParameterNode): string    // → 'findPetsByStatusQuerySchema'
    headers?(node: OperationNode, param: ParameterNode): string  // → 'deletePetHeadersSchema'
  }
  response?: {
    status?(node: OperationNode, statusCode: StatusCode): string // → 'listPetsStatus200Schema'
    body?(node: OperationNode): string                           // → 'createPetBodySchema'
    responses?(node: OperationNode): string                      // → 'listPetsResponsesSchema'
    response?(node: OperationNode): string                       // → 'listPetsResponseSchema'
    error?(node: OperationNode): string                          // → 'listPetsErrorSchema'
    options?(node: OperationNode): string                        // → 'ListPetsOptionsSchemaType'
  }
}

printer

Replaces the Zod handler for a schema type such as 'integer' or 'string', each returning the Zod expression as a string and targeting the Zod Mini printer 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()'
      },
      date() {
        return 'z.string().date()'
      },
    },
  },
})

A handler that reads this.options.direction ('decode' for responses, 'encode' for request bodies and parameters) and returns a different expression per direction registers a two-way conversion: the generator detects the difference and emits an ${name}InputSchema variant for request bodies to resolve to, including through a $ref. See Encode a custom type on requests.