Registry / devops / graphql-codegen-zod

graphql-codegen-zod

library1.10.6jsnpmunverified

A GraphQL codegen plugin that generates Zod schemas from GraphQL input types. Version 1.10.6 is stable, actively maintained. It allows developers to define validation rules via GraphQL directives (@validation) or rely on required fields only. Key differentiator: keeps GraphQL as single source of truth for validation, supports custom scalar mappings, and integrates with GraphQL Code Generator ecosystem.

devops testing

npm install graphql-codegen-zod

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · GRAPHQL-CODEGEN-ZO

graphql-codegen-zod

devopsjavascriptv1.10.6

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

graphql-codegen-zod

✓ plugins: - graphql-codegen-zod

✗ plugins: - @graphql-codegen/zod

Plugin is declared by its npm package name in codegen.yml, not imported in JavaScript.

Zod schemas

✓ import { TestInput } from './generated/schemas';

✗ const TestInput = require('./generated/schemas').TestInput;

Generated output is ESM by default; use named imports. CJS requires .default or esModuleInterop.

Directive

✓ directive @validation(pattern: String, min: Int, max: Int, requiredMessage: String, typeOf: String) on INPUT_FIELD_DEFINITION | ARGUMENT_DEFINITION

✗ directive @validation on INPUT_FIELD_DEFINITION

Directive must include all parameters to use advanced validations; otherwise only required checks work.

Generates Zod schemas from GraphQL input types using codegen.yml configuration with optional directives for validation.

// codegen.yml overwrite: true schema: './schema.graphql' generates: schemas.ts: plugins: - graphql-codegen-zod: onlyWithValidation: false // schema.graphql directive @validation( pattern: String min: Int max: Int requiredMessage: String typeOf: String ) on INPUT_FIELD_DEFINITION | ARGUMENT_DEFINITION input UserInput { name: String! age: Int @validation(min: 0, max: 120) } // Usage in your app: import { UserInput } from './schemas'; const result = UserInput.safeParse({ name: 'John', age: 30 }); if (!result.success) console.error(result.error.flatten());

Debug

Known issues

breakingPlugin only works with GraphQL input types and arguments; does not generate schemas for output types.

fix

Use only for input validation. For output schemas, consider other tools.

affects: <=1.10.6

deprecatedThe 'onlyWithValidation' option defaults to false; if set to true, schemas for inputs without @validation directives are skipped.

fix

Set onlyWithValidation: true only if you intend to skip inputs without @validation directives.

affects: >=1.0.0

gotchaCustom scalar mapping requires 'zodSchemasMap' config; otherwise unknown scalars default to z.any() and may cause type mismatches.

fix

Define zodSchemasMap for custom scalars, e.g., EmailAddress: z.string().email()

affects: >=1.0.0

gotchaDirective @validation must be defined in the schema for advanced validation to work; introspection does not include directives.

fix

Include the directive definition in your schema file used as codegen schema.

affects: >=1.0.0

Errors

Common errors & fixes

Cannot read properties of undefined (reading 'directives')

Missing @validation directive definition in the schema file.

fix

Add the directive definition from the documentation to your schema file.

Expected a valid Zod schema but received a GraphQL input type without generated schema

onlyWithValidation: true but input does not have @validation directive.

fix

Add @validation directive to the input or set onlyWithValidation: false.

Unknown scalar 'EmailAddress' - generated as z.any()

Scalar not mapped in zodSchemasMap.

fix

Add zodSchemasMap: { EmailAddress: 'z.string().email()' } in codegen.yml plugin config.

Upgrade

Version history

1.10.6latest on npm

Audit

Dependencies

@graphql-codegen/plugin-helpersrequiredUsed internally by graphql-codegen-zod for plugin infrastructure

zodrequiredPeer dependency; required for generated schemas to work

Agent activity

9 hits · last 30 days

node

Resources

githubhttps://github.com/withshepherd/graphql-codegen-zod ↗

packagegraphql-codegen-zod ↗

homepagehttps://github.com/withshepherd/graphql-codegen-zod ↗