graphql-codegen-simple-zod

A small GraphQL Code Generator plugin that creates Zod 4 schemas for GraphQL objects, inputs, and enums.

Disclaimer

This project was built for internal company use, and its code was generated using AI. Use it at your own risk.

It is provided as-is. There are no plans to support or maintain this library. If you want to use it, forking the repository and maintaining your own version is recommended.

Install

pnpm add graphql zod
pnpm add -D @graphql-codegen/cli graphql-codegen-simple-zod

Use

Add the plugin to your GraphQL Code Generator config:

import type { CodegenConfig } from "@graphql-codegen/cli";

const config: CodegenConfig = {
  schema: "./schema.graphql",
  generates: {
    "./src/generated/schemas.ts": {
      plugins: [
        {
          "graphql-codegen-simple-zod": {
            includeTypename: false,
            includeRelations: true,
            scalarSchemas: {
              DateTime: "z.iso.datetime()",
              JSON: "z.unknown()",
            },
          },
        },
      ],
    },
  },
};

export default config;

Then run GraphQL Code Generator:

pnpm graphql-codegen --config codegen.ts

Options

| Option | Default | What it does | | ------------------------------- | ---------- | ------------------------------------------------------------- | | schemaNamePrefix | "" | Adds a prefix to generated schema names. | | schemaNameSuffix | "Schema" | Adds a suffix to generated schema names. | | includeTypename | false | Adds a required __typename literal. | | includeClientMutationId | false | Includes clientMutationId fields. | | includeRelations | false | Includes object, interface, and union fields. | | includeConnectionAndEdgeTypes | false | Generates Relay-style Connection and Edge object schemas. | | useTypeScriptEnums | false | Passes runtime TypeScript enums to z.enum. | | nullableWithDefaultNull | false | Adds .default(null) to nullable fields and list items. | | scalarSchemas | {} | Maps scalar names to Zod expressions. |

Built-in scalars map to their usual Zod types. Unknown custom scalars use z.unknown() unless they are configured in scalarSchemas.

When nullableWithDefaultNull is enabled, nullable schemas such as z.string().nullable() become z.string().nullable().default(null). Missing or undefined nullable input and output fields parse as null. Nullable input fields use this default instead of .optional(), and explicit GraphQL input defaults take precedence. Non-null types remain unchanged.

When useTypeScriptEnums is enabled, each TypeScript enum must be available as a runtime value in the generated module. This is compatible with runtime enums and enum-like as const objects, but not type-only enum unions such as those generated with enumsAsTypes: true.

When generating the enums and schemas into the same file, run the TypeScript plugin first:

plugins: [
  "typescript",
  {
    "graphql-codegen-simple-zod": {
      useTypeScriptEnums: true,
    },
  },
];

Query, Mutation, Subscription, interface, and union schemas are not generated. References to interfaces or unions use z.unknown().

Development

vp install
vp check
vp test
vp run build