@kubb/plugin-zod 5.0.0-beta.3 → 5.0.0-beta.4

package/extension.yaml

@@ -0,0 +1,502 @@
+$schema: https://kubb.dev/schemas/extension.json
+kind: plugin
+id: plugin-zod
+name: Zod
+description: Generate Zod validation schemas from OpenAPI specifications for runtime data validation.
+category: validation
+type: official
+npmPackage: "@kubb/plugin-zod"
+docsPath: /plugins/plugin-zod
+repo: https://github.com/kubb-labs/plugins
+maintainers:
+  - name: Stijn Van Hulle
+    github: stijnvanhulle
+compatibility:
+  kubb: ">=5.0.0"
+  node: ">=22"
+tags:
+  - zod
+  - validation
+  - schema
+  - runtime-validation
+  - codegen
+  - openapi
+dependencies: []
+resources:
+  documentation: https://kubb.dev/plugins/plugin-zod
+  repository: https://github.com/kubb-labs/plugins
+  issues: https://github.com/kubb-labs/plugins/issues
+  changelog: https://github.com/kubb-labs/plugins/blob/main/packages/plugin-zod/CHANGELOG.md
+  codesandbox: https://codesandbox.io/p/github/kubb-labs/plugins/main/examples/zod
+featured: true
+icon:
+  light: https://kubb.dev/feature/zod.svg
+intro: |
+  # @kubb/plugin-zod
+
+  Generate [Zod](https://zod.dev/) validation schemas from your OpenAPI schema for runtime validation. Kubb generates Zod v4 schemas.
+options:
+  - name: output
+    type: Output
+    required: false
+    default: "{ path: 'zod', barrelType: 'named' }"
+    description: Specify the export location for the files and define the behavior of the output.
+    properties:
+      - name: path
+        type: string
+        required: true
+        description: Output directory or file for the generated code, relative to the global `output.path`.
+        tip: |
+          if `output.path` is a file, `group` cannot be used.
+        default: "'zod'"
+      - name: barrelType
+        type: "'all' | 'named' | 'propagate' | false"
+        required: false
+        default: "'named'"
+        description: Specify what to export and optionally disable barrel-file generation.
+        tip: |
+          Using `propagate` will prevent a plugin from creating a barrel file, but it will still propagate, allowing [`output.barrelType`](https://kubb.dev/docs/5.x/configuration#output-barreltype) to export the specific function or type.
+        examples:
+          - name: all
+            files:
+              - lang: typescript
+                code: |
+                  export * from './gen/petService.ts'
+                twoslash: false
+          - name: named
+            files:
+              - lang: typescript
+                code: |
+                  export { PetService } from './gen/petService.ts'
+                twoslash: false
+          - name: propagate
+            files:
+              - lang: typescript
+                code: ""
+                twoslash: false
+          - name: "false"
+            files:
+              - lang: typescript
+                code: ""
+                twoslash: false
+      - name: banner
+        type: "string | ((node: RootNode) => string)"
+        required: false
+        description: Add a banner comment at the top of every generated file. Accepts a static string or a function that receives the `RootNode` and returns a string.
+      - name: footer
+        type: "string | ((node: RootNode) => string)"
+        required: false
+        description: Add a footer comment at the end of every generated file. Accepts a static string or a function that receives the `RootNode` and returns a string.
+      - name: override
+        type: boolean
+        required: false
+        default: "false"
+        description: Whether Kubb overrides existing external files that can be generated if they already exist.
+  - name: resolver
+    type: Partial<ResolverZod> & ThisType<ResolverZod>
+    required: false
+    description: |
+      A single resolver that overrides the naming and path-resolution conventions. Each method you provide replaces the corresponding built-in one. When a method returns `null` or `undefined`, the resolver's result is used as the fallback, so you only need to supply the methods you want to change.
+
+      `this` inside each method is bound to the **full** resolver, so you can call other resolver methods (e.g. `this.default(name, 'function')`) without losing context.
+    body: |
+      Each plugin ships a built-in resolver:
+
+      | Plugin | Default resolver |
+      | --- | --- |
+      | `@kubb/plugin-ts` | `resolverTs` |
+      | `@kubb/plugin-zod` | `resolverZod` |
+      | `@kubb/plugin-cypress` | `resolverCypress` |
+      | `@kubb/plugin-mcp` | `resolverMcp` |
+    codeBlock:
+      lang: typescript
+      title: Custom resolver (plugin-ts example)
+      code: |
+        import { pluginTs } from '@kubb/plugin-ts'
+
+        pluginTs({
+          resolver: {
+            resolveName(name) {
+              // Prefix every operation-derived name; falls back for names where
+              // this returns null/undefined.
+              return `Api${this.default(name, 'function')}`
+            },
+          },
+        })
+    tip: |
+      Use `resolver` for fine-grained control over naming conventions.
+  - name: group
+    type: Group
+    required: false
+    description: |
+      Grouping combines files in a folder based on a specific `type`.
+    examples:
+      - name: kubb.config.ts
+        files:
+          - lang: typescript
+            code: |
+              group: {
+                type: 'tag',
+                name({ group }) {
+                  return `${group}Controller`
+                }
+              }
+            twoslash: false
+    body: |
+      With the configuration above, the generator emits:
+
+      ```text
+      .
+      ├── src/
+      │   └── petController/
+      │   │   ├── addPet.ts
+      │   │   └── getPet.ts
+      │   └── storeController/
+      │       ├── createStore.ts
+      │       └── getStoreById.ts
+      ├── petStore.yaml
+      ├── kubb.config.ts
+      └── package.json
+      ```
+    properties:
+      - name: type
+        type: "'tag'"
+        required: true
+        description: Specify the property to group files by. Required when `group` is defined.
+        note: |
+          `Required: true*` means this is required only when the `group` option is used. The `group` option itself is optional.
+        body: |
+          - `'tag'`: Uses the first tag from `operation.getTags().at(0)?.name`
+      - name: name
+        type: "(context: GroupContext) => string"
+        required: false
+        default: (ctx) => `${ctx.group}Controller`
+        description: Return the name of a group based on the group name. This is used for file and identifier generation.
+  - name: importPath
+    type: string
+    required: false
+    default: "'zod'"
+    description: |
+      Import path for Zod. Use `'zod/mini'` to import from Zod's mini bundle.
+  - name: typed
+    type: boolean
+    required: false
+    default: "false"
+    description: Annotate schemas with their TypeScript types from `@kubb/plugin-ts`. Requires `@kubb/plugin-ts` in the plugins array.
+    important: |
+      We rely on [`ToZod`](https://github.com/colinhacks/tozod) from the creator of Zod to create a schema based on a type.
+      Kubb contains its own version to those kind of conversions.
+  - name: inferred
+    type: boolean
+    required: false
+    default: "false"
+    description: Export a `z.infer<typeof schema>` type alias for each schema to keep types in sync with validation.
+    codeBlock:
+      lang: typescript
+      title: "inferred: true"
+      code: |
+        import { z } from 'zod'
+
+        export const petSchema = z.object({
+          name: z.string(),
+          status: z.enum(['available', 'pending', 'sold']).optional(),
+        })
+
+        // Inferred type export
+        export type Pet = z.infer<typeof petSchema>
+  - name: integerType
+    warning: |
+      This option has been moved to [`adapterOas`](/adapters/adapter-oas#integerType). Use `adapterOas({ integerType })` instead.
+  - name: unknownType
+    warning: |
+      This option has been moved to [`adapterOas`](/adapters/adapter-oas#unknownType). Use `adapterOas({ unknownType })` instead.
+  - name: emptySchemaType
+    warning: |
+      This option has been moved to [`adapterOas`](/adapters/adapter-oas#emptySchemaType). Use `adapterOas({ emptySchemaType })` instead.
+  - name: coercion
+    type: "boolean | { dates?: boolean, strings?: boolean, numbers?: boolean }"
+    required: false
+    default: "false"
+    description: Apply `z.coerce` to automatically convert input values to the expected type before validation. Pass `true` to coerce all primitives, or an object to selectively enable coercion for `dates`, `strings`, and `numbers`. See [Coercion for primitives](https://zod.dev/?id=coercion-for-primitives).
+    examples:
+      - name: "true"
+        files:
+          - lang: typescript
+            code: |
+              z.coerce.string();
+              z.coerce.date();
+              z.coerce.number();
+            twoslash: false
+      - name: "false"
+        files:
+          - lang: typescript
+            code: |
+              z.string();
+              z.date();
+              z.number();
+            twoslash: false
+      - name: "{numbers: true, strings: false, dates: false}"
+        files:
+          - lang: typescript
+            code: |
+              z.string();
+              z.date();
+              z.coerce.number();
+            twoslash: false
+  - name: operations
+    type: boolean
+    required: false
+    default: "false"
+    description: Generate an `operations.ts` file with schemas for each operation, including request and response data.
+  - name: paramsCasing
+    type: "'camelcase'"
+    required: false
+    description: Transform parameter property names to camelCase.
+    codeBlock:
+      lang: typescript
+      title: "'camelcase'"
+      code: |
+        // OpenAPI spec uses: pet_id, X-Api-Key
+
+        type GetPetPathParams = {
+          petId: string   // ✓ camelCase
+        }
+
+        type GetPetHeaderParams = {
+          xApiKey?: string  // ✓ camelCase
+        }
+  - name: guidType
+    type: "'uuid' | 'guid'"
+    required: false
+    default: "'uuid'"
+    description: |
+      Validator to use for OpenAPI properties with `format: uuid`. Use `'guid'` to generate `.guid()` validation instead of the default `.uuid()`.
+    examples:
+      - name: "'uuid' (default)"
+        files:
+          - lang: typescript
+            code: |
+              z.uuid()
+            twoslash: false
+      - name: "'guid'"
+        files:
+          - lang: typescript
+            code: |
+              z.guid()
+            twoslash: false
+  - name: mini
+    type: boolean
+    required: false
+    default: "false"
+    badge:
+      type: tip
+      text: beta
+    description: |
+      Use Zod Mini's functional API for better tree-shaking support.
+
+      When enabled, generates functional syntax (e.g., `z.optional(z.string())`) instead of chainable methods (e.g., `z.string().optional()`).
+
+      When `mini: true`, `importPath` will default to `'zod/mini'`.
+    warning: |
+      This feature is currently in beta. The API may change in future releases.
+    tip: |
+      Zod Mini provides a smaller bundle size with better tree-shaking. See [Zod Mini documentation](https://zod.dev/packages/mini) for more details.
+    examples:
+      - name: "mini: true"
+        files:
+          - lang: typescript
+            code: |
+              // Import from zod/mini
+              import { z } from 'zod/mini'
+
+              // Functional syntax for better tree-shaking
+              z.optional(z.string())
+              z.nullable(z.number())
+              z.array(z.string()).check(z.minLength(1), z.maxLength(10))
+            twoslash: false
+      - name: "mini: false (default)"
+        files:
+          - lang: typescript
+            code: |
+              // Import from zod or zod/v4
+              import { z } from 'zod'
+
+              // Chainable method syntax
+              z.string().optional()
+              z.number().nullable()
+              z.array(z.string()).min(1).max(10)
+            twoslash: false
+  - name: include
+    type: Array<Include>
+    required: false
+    description: Array containing include parameters to include tags, operations, methods, paths, or content types.
+    codeBlock:
+      lang: typescript
+      title: Include
+      code: |
+        export type Include = {
+          type: 'tag' | 'operationId' | 'path' | 'method' | 'contentType'
+          pattern: string | RegExp
+        }
+  - name: exclude
+    type: Array<Exclude>
+    required: false
+    description: Array containing exclude parameters to exclude or skip tags, operations, methods, paths, or content types.
+    codeBlock:
+      lang: typescript
+      title: Exclude
+      code: |
+        export type Exclude = {
+          type: 'tag' | 'operationId' | 'path' | 'method' | 'contentType'
+          pattern: string | RegExp
+        }
+  - name: override
+    type: Array<Override>
+    required: false
+    description: Array containing override parameters to override `options` based on tags, operations, methods, paths, or content types.
+    codeBlock:
+      lang: typescript
+      title: Override
+      code: |
+        export type Override = {
+          type: 'tag' | 'operationId' | 'path' | 'method' | 'contentType'
+          pattern: string | RegExp
+          options: PluginOptions
+        }
+  - name: generators
+    type: Array<Generator<PluginZod>>
+    required: false
+    experimental: true
+    description: |
+      Define additional generators next to the built-in generators.
+
+      See [Generators](https://kubb.dev/docs/5.x/guides/creating-plugins) for more information on how to use generators.
+  - name: transformer
+    type: Visitor
+    required: false
+    description: |
+      A single AST visitor applied to every node before code is printed. Each method you provide replaces the corresponding built-in one. When a method returns `null` or `undefined`, the preset transformer's result is used as the fallback — so you only need to supply the methods you want to change.
+
+      Visitor methods receive the node and a context object. Return a modified node to replace it, or return `undefined`/`void` to leave it unchanged.
+    examples:
+      - name: Strip descriptions before printing
+        files:
+          - lang: typescript
+            code: |
+              import { pluginTs } from '@kubb/plugin-ts'
+
+              pluginTs({
+                transformer: {
+                  schema(node) {
+                    return { ...node, description: undefined }
+                  },
+                },
+              })
+            twoslash: false
+      - name: Prefix every operationId
+        files:
+          - lang: typescript
+            code: |
+              import { pluginTs } from '@kubb/plugin-ts'
+
+              pluginTs({
+                transformer: {
+                  operation(node) {
+                    return { ...node, operationId: `api_${node.operationId}` }
+                  },
+                },
+              })
+            twoslash: false
+    tip: |
+      Use `transformer` to rewrite node properties before printing. For output naming customization, use `resolver` instead.
+  - name: printer
+    type: "{ nodes?: PrinterZodNodes | PrinterZodMiniNodes }"
+    required: false
+    description: |
+      Override individual printer node handlers to customize how specific schema types are rendered. When `mini: true` the overrides apply to the Zod Mini printer.
+
+      Each key is a `SchemaType` (e.g. `'integer'`, `'date'`). The function you provide replaces the built-in handler for that type. Use `this.transform` to recurse into nested schema nodes.
+    examples:
+      - name: Override integer to z.number()
+        files:
+          - lang: typescript
+            code: |
+              import { pluginZod } from '@kubb/plugin-zod'
+
+              pluginZod({
+                printer: {
+                  nodes: {
+                    integer() {
+                      return 'z.number()'
+                    },
+                  },
+                },
+              })
+            twoslash: false
+      - name: Override date to z.string().date()
+        files:
+          - lang: typescript
+            code: |
+              import { pluginZod } from '@kubb/plugin-zod'
+
+              pluginZod({
+                printer: {
+                  nodes: {
+                    date(node) {
+                      return 'z.string().date()'
+                    },
+                  },
+                },
+              })
+            twoslash: false
+  - name: wrapOutput
+    type: "(arg: { output: string; schema: SchemaNode }) => string | undefined"
+    required: false
+    description: Wrap the generated Zod schema string with additional validation or metadata. The callback receives the schema's output string and the `SchemaNode` AST node, and returns the modified schema string.
+    tip: |
+      This is useful for cases where you need to extend the generated zod output with additional properties from an OpenAPI schema. E.g. in the case of `OpenAPI -> Zod -> OpenAPI`, you could include the examples from the schema for a given property and then ultimately provide a modified schema to a router that supports zod and OpenAPI spec generation.
+    codeBlock:
+      lang: typescript
+      title: Conditionally append .openapi() to the generated schema
+      code: |
+        wrapOutput: ({ output, schema }) => {
+          const metadata: Record<string, unknown> = {};
+
+          if (schema.keywords?.includes('example')) {
+            // access SchemaNode properties
+          }
+
+          if (Object.keys(metadata).length > 0) {
+            return `${output}.openapi(${JSON.stringify(metadata)})`;
+          }
+        };
+examples:
+  - name: kubb.config.ts
+    files:
+      - lang: typescript
+        code: |
+          import { defineConfig } from 'kubb';
+          import { pluginTs } from '@kubb/plugin-ts';
+          import { pluginZod } from '@kubb/plugin-zod';
+
+          export default defineConfig({
+            input: {
+              path: './petStore.yaml',
+            },
+            output: {
+              path: './src/gen',
+            },
+            plugins: [
+              pluginTs(),
+              pluginZod({
+                output: {
+                  path: './zod',
+                },
+                group: { type: 'tag', name: ({ group }) => `${group}Schemas` },
+                typed: true,
+                dateType: 'stringOffset',
+                importPath: 'zod',
+              }),
+            ],
+          });
+        twoslash: false

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kubb/plugin-zod",
-  "version": "5.0.0-beta.3",
+  "version": "5.0.0-beta.4",
   "description": "Zod schema generator plugin for Kubb, creating type-safe validation schemas from OpenAPI specifications for runtime data validation.",
   "keywords": [
     "code-generator",
@@ -30,7 +30,7 @@
     "src",
     "templates",
     "dist",
-    "plugin.json",
+    "extension.yaml",
     "!/**/**.test.**",
     "!/**/__tests__/**",
     "!/**/__snapshots__/**"
@@ -52,15 +52,15 @@
     "registry": "https://registry.npmjs.org/"
   },
   "dependencies": {
-    "@kubb/core": "5.0.0-beta.3",
-    "@kubb/renderer-jsx": "5.0.0-beta.3",
+    "@kubb/core": "5.0.0-beta.4",
+    "@kubb/renderer-jsx": "5.0.0-beta.4",
     "remeda": "^2.34.0"
   },
   "devDependencies": {
     "@internals/utils": "0.0.0"
   },
   "peerDependencies": {
-    "@kubb/renderer-jsx": "5.0.0-beta.3"
+    "@kubb/renderer-jsx": "5.0.0-beta.4"
   },
   "size-limit": [
     {