@kubb/plugin-zod 5.0.0-alpha.9 → 5.0.0-beta.15

package/extension.yaml

@@ -0,0 +1,505 @@
+$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', barrel: { type: '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: barrel
+        type: "{ type: 'named' | 'all', nested?: boolean } | false"
+        required: false
+        default: "{ type: 'named' }"
+        description: 'Configure barrel file export strategy. Use `type` to control named vs. wildcard exports; set `nested: true` to generate hierarchical barrels in subdirectories.'
+        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: nested
+            files:
+              - name: kubb.config.ts
+                lang: typescript
+                code: |
+                  output: {
+                    path: './gen',
+                    barrel: { type: 'named', nested: true },
+                  }
+                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,74 +1,63 @@
 {
   "name": "@kubb/plugin-zod",
-  "version": "5.0.0-alpha.9",
-  "description": "Zod schema generator plugin for Kubb, creating type-safe validation schemas from OpenAPI specifications for runtime data validation.",
+  "version": "5.0.0-beta.15",
+  "description": "Generate Zod validation schemas from your OpenAPI specification for runtime data parsing and type safety. Pairs perfectly with @kubb/plugin-ts for end-to-end type coverage.",
   "keywords": [
-    "zod",
-    "schema",
-    "schema-validation",
-    "validation",
-    "runtime-validation",
-    "type-safety",
-    "type-safe",
-    "typescript",
+    "code-generation",
+    "codegen",
+    "kubb",
     "openapi",
+    "parse",
+    "runtime-validation",
+    "schema",
     "swagger",
-    "oas",
-    "code-generator",
-    "codegen",
-    "plugins",
-    "kubb"
+    "typescript",
+    "validation",
+    "zod"
   ],
+  "license": "MIT",
+  "author": "stijnvanhulle",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/kubb-labs/kubb.git",
+    "url": "git+https://github.com/kubb-labs/plugins.git",
     "directory": "packages/plugin-zod"
   },
-  "license": "MIT",
-  "author": "stijnvanhulle",
-  "sideEffects": false,
+  "files": [
+    "src",
+    "templates",
+    "dist",
+    "extension.yaml",
+    "!/**/**.test.**",
+    "!/**/__tests__/**",
+    "!/**/__snapshots__/**"
+  ],
   "type": "module",
+  "sideEffects": false,
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
   "exports": {
     ".": {
       "import": "./dist/index.js",
       "require": "./dist/index.cjs"
     },
-    "./components": {
-      "import": "./dist/components.js",
-      "require": "./dist/components.cjs"
-    },
-    "./generators": {
-      "import": "./dist/generators.js",
-      "require": "./dist/generators.cjs"
-    },
-    "./templates/ToZod.source": {
-      "import": "./dist/templates/ToZod.source.js",
-      "require": "./dist/templates/ToZod.source.cjs"
-    },
     "./package.json": "./package.json"
   },
-  "types": "./dist/index.d.ts",
-  "typesVersions": {
-    "*": {
-      "components": [
-        "./dist/components.d.ts"
-      ],
-      "generators": [
-        "./dist/generators.d.ts"
-      ],
-      "templates/ToZod.source": [
-        "./dist/templates/ToZod.source.d.ts"
-      ]
-    }
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "dependencies": {
+    "@kubb/core": "5.0.0-beta.19",
+    "@kubb/renderer-jsx": "5.0.0-beta.19",
+    "remeda": "^2.34.1"
+  },
+  "devDependencies": {
+    "@internals/utils": "0.0.0"
+  },
+  "peerDependencies": {
+    "@kubb/renderer-jsx": "5.0.0-beta.19"
   },
-  "files": [
-    "src",
-    "templates",
-    "dist",
-    "!/**/**.test.**",
-    "!/**/__tests__/**",
-    "!/**/__snapshots__/**"
-  ],
   "size-limit": [
     {
       "path": "./dist/*.js",
@@ -76,33 +65,14 @@
       "gzip": true
     }
   ],
-  "dependencies": {
-    "@kubb/react-fabric": "0.14.0",
-    "remeda": "^2.33.6",
-    "@kubb/core": "5.0.0-alpha.9",
-    "@kubb/oas": "5.0.0-alpha.9",
-    "@kubb/plugin-oas": "5.0.0-alpha.9",
-    "@kubb/plugin-ts": "5.0.0-alpha.9"
-  },
-  "devDependencies": {
-    "@asteasolutions/zod-to-openapi": "^8.4.3",
-    "zod": "^3.25.76",
-    "@internals/utils": "0.0.0"
-  },
   "engines": {
     "node": ">=22"
   },
-  "publishConfig": {
-    "access": "public",
-    "registry": "https://registry.npmjs.org/"
-  },
-  "main": "./dist/index.cjs",
-  "module": "./dist/index.js",
   "scripts": {
     "build": "tsdown && size-limit",
     "clean": "npx rimraf ./dist",
-    "lint": "bun biome lint .",
-    "lint:fix": "bun biome lint --fix --unsafe .",
+    "lint": "oxlint .",
+    "lint:fix": "oxlint --fix .",
     "release": "pnpm publish --no-git-check",
     "release:canary": "bash ../../.github/canary.sh && node ../../scripts/build.js canary && pnpm publish --no-git-check",
     "start": "tsdown --watch",