Skip to content
Valibot logo

Valibot

OfficialBetav0.1.0

@kubb/plugin-valibot

kubb add plugin-valibot

Options

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

Options overview

OptionPurposeDefault
outputWhere files are written.{ path: 'valibot', barrel: { type: 'named' } }
groupSplit output by tag or path.None
importPathModule the generated files import v from.'valibot'
inferredExport a type next to each schema.false
coercionConvert input before validation.false
coercion.stringsConvert a string with v.toString().false
coercion.numbersConvert a number and an integer with v.toNumber().false
coercion.datesConvert a Date field of a response with v.toDate().false
typeGuardsGenerate is* type guards and assert* assertions.false
typeGuards.isGenerate the is* type guard.true
typeGuards.assertGenerate the assert* function.true
regexTypeHow an OpenAPI pattern is written.'literal'
oneOfTypeHow a oneOf without a discriminator is validated.'union'
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.resolverValibot
macrosRewrite AST nodes before printing.[]

Option details

importPath

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

Typestring
Requiredfalse
Default'valibot'

The module is imported as import * as v, so it must export every Valibot function the schemas call.

inferred

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

Typeboolean
Requiredfalse
Defaultfalse
petSchema.ts
export type PetSchemaType = v.InferOutput<typeof petSchema>

A request schema, such as a request body or a query schema, gets v.InferInput, which is the value the caller passes. Every other schema gets v.InferOutput. The two differ for a schema that converts, such as a Date field or a default.

A schema that is part of a circular reference is annotated as v.GenericSchema, so its inferred type is unknown. Add @kubb/plugin-ts when you need the types of those schemas.

coercion

Converts input before validation, so a query string such as '5' passes an integer schema.

Typeboolean | { dates?: boolean; strings?: boolean; numbers?: boolean }
Requiredfalse
Defaultfalse
strings
Writes v.pipe(v.unknown(), v.toString()) for a string.
numbers
Writes v.pipe(v.unknown(), v.toNumber()) for a number and an integer.
dates
Writes v.pipe(v.unknown(), v.toDate()) for a response field that is a Date. This needs dateType: 'date' on the adapter.

true turns on all three. An integer with format: int64 converts with or without this option, because JSON holds a number or a string.

typeGuards

Generates an is* type guard and an assert* function for every component schema.

Typeboolean | { is?: boolean; assert?: boolean }
Requiredfalse
Defaultfalse
petSchema.ts
export const isPet = (data: unknown): data is v.InferInput<typeof petSchema> => v.is(petSchema, data)

export function assertPet(data: unknown): asserts data is v.InferInput<typeof petSchema> {
  v.assert(petSchema, data)
}

Both narrow to v.InferInput, the value the schema accepts before it converts anything.

regexType

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

Type'literal' | 'constructor'
Requiredfalse
Default'literal'
'literal'
Writes v.regex(/^[a-z]+$/).
'constructor'
Writes v.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 v.union([...]) with strict object members, so extra keys fail, even keys the spec allows.
'xor'
Writes v.union([...]) behind a v.check that passes only when exactly one member matches.

printer

Replaces the handler for a schema type such as 'date'. Each handler returns the Valibot expression as a string. this.base(node) returns the built-in output, and this.transform(node) recurses into nested nodes. See the printer guide.

Type{ nodes?: PrinterValibotNodes }
Requiredfalse
kubb.config.ts
import { pluginValibot } from '@kubb/plugin-valibot'

pluginValibot({
  printer: {
    nodes: {
      date() {
        return 'v.pipe(v.string(), v.isoDate(), v.transform((value) => new Date(value)))'
      },
    },
  },
})

Resolver members

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

Partial override
type ResolverValibotPatch = {
  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 Valibot call, such as format: email to v.pipe(v.string(), v.email()). See Valibot schemas for OpenAPI formats.