[Zod Plugin] Variable used before declaration in OpenAPI schema with circular references

[alirezas]

Description

The Zod plugin generates invalid TypeScript code when dealing with OpenAPI schemas that contain circular references between entities. This results in compilation errors due to variables being used before their declaration.

Bug Report

Current Behavior

When generating Zod schemas from an OpenAPI spec with circular references, the generated code contains TypeScript errors:

Block-scoped variable 'zSubregionDto' used before its declaration.

Expected Behavior

The generated Zod schemas should handle circular references properly, either by:

1. Using z.lazy() to wrap circular references
2. Reordering declarations to avoid forward references
3. Providing configuration options to handle circular dependencies

Minimal Reproduction

OpenAPI Schema (simplified):

components:
  schemas:
    CountryDto:
      type: object
      properties:
        id:
          type: number
        name:
          type: string
        region:
          $ref: '#/components/schemas/RegionDto'
        subregion:
          $ref: '#/components/schemas/SubregionDto'
    
    SubregionDto:
      type: object
      properties:
        id:
          type: number
        name:
          type: string
        region:
          $ref: '#/components/schemas/RegionDto'
        countries:
          type: array
          items:
            $ref: '#/components/schemas/CountryDto'
    
    RegionDto:
      type: object
      properties:
        id:
          type: number
        name:
          type: string
        countries:
          type: array
          items:
            $ref: '#/components/schemas/CountryDto'
        subregions:
          type: array
          items:
            $ref: '#/components/schemas/SubregionDto'

Generated Code (problematic):

export const zCountryDto = z.object({
  // ... other properties
  get region() {
    return zRegionDto;  // ✅ This works with getter
  },
  subregion: zSubregionDto,  // ❌ Error: used before declaration
  // ...
});

export const zSubregionDto = z.object({
  // ... defined later
});

Configuration:

// openapi-ts.config.ts
export default defineConfig({
  input: "http://localhost:3000/api-yaml",
  output: {
    path: "src/client",
    format: "prettier",
    lint: "eslint",
    tsConfigPath: "./tsconfig.json",
  },
  plugins: [
    "@hey-api/schemas",
    { name: "@hey-api/client-axios" },
    "@tanstack/react-query",
    "zod",  // ❌ No options available for circular reference handling
    {
      dates: true,
      name: "@hey-api/transformers",
    },
    {
      enums: "javascript",
      name: "@hey-api/typescript",
    },
  ],
});

System Information

• @hey-api/openapi-ts version: 0.84.0
• Node.js version: v24.8.0
• npm version: 11.6.0
• TypeScript version: 5.9.2
• Operating System: macOS (darwin 25.0.0)
• Package manager: pnpm

Dependencies

{
  "devDependencies": {
    "@hey-api/openapi-ts": "0.84.0"
  },
  "dependencies": {
    "@hey-api/client-axios": "0.9.1",
    "zod": "^3.x"
  }
}

Attempted Solutions

1. Tried configuration options (not available):

   // ❌ These don't exist in current version
   "zod": {
     circularReferenceHandler: "lazy"
   }

2. Attempted workarounds:

   • Removing circular references from API schema (not always feasible)
   • Manual post-processing of generated files (not sustainable)

Proposed Solutions

1. Add z.lazy() wrapper for circular references:

   export const zCountryDto = z.object({
     subregion: z.lazy(() => zSubregionDto),  // ✅ Wrapped in lazy
   });

2. Add configuration option:

   plugins: [
     {
       name: "zod",
       circularReferenceHandler: "lazy" | "reorder" | "error"
     }
   ]

3. Automatic dependency sorting to reorder declarations properly

Related Issues

• Similar issue reported: [Zod Plugin] Variable used before declaration in OpenAPI schema with recursive and self-referential types #2560
• Related to circular dependency handling in Zod schema generation

Additional Context

This issue commonly occurs with:

• Geographic entities (Country → Region → Country)
• User/Organization relationships
• Category/Subcategory hierarchies
• Any bidirectional entity relationships

The issue prevents using the Zod plugin with realistic API schemas that model real-world entity relationships.

Reproducible example or configuration

https://stackblitz.com/edit/hey-api-client-fetch-example

OpenAPI specification (optional)

No response

System information (optional)

No response

[bolt-new-by-stackblitz]

Start a new pull request in StackBlitz Codeflow.

• hey-api-client-fetch-example (Open reproduction)

[dosubot]

Hi @alirezas! I'm Dosu and I’m helping the openapi-ts team.

The Zod plugin for @hey-api/openapi-ts does not currently support automatic handling of circular references in generated schemas—there are no configuration options like circularReferenceHandler, nor does it wrap circular references with z.lazy() or reorder declarations to avoid forward references. The official documentation does not mention any built-in solution or recommended workaround for this issue, and manual post-processing remains the only option, though it's not sustainable or officially supported. This is a known limitation, so it's worth monitoring related issues and future updates for progress on this feature source.

To reply, just mention @dosu.

---

^{How did I do? Good | Irrelevant | Incorrect | Verbose | Hallucination | Report 🐛 | Other}   

[9M6]

Having the same issue

[mrlubos]

@9M6 is it a regression? What does your spec look like?

[9M6]

@mrlubos

I downgraded to 0.83.1 since here the generations work fine; The first image shows the generation with the error, while the second one shows the generation at 0.83.1.

import { defaultPlugins, defineConfig } from "@hey-api/openapi-ts";
import dotenv from "dotenv";

dotenv.config();

export default defineConfig({
  input: "http://localhost:9000/docs-json",
  output: {
    format: "prettier",
    lint: "eslint",
    path: "app/clients/api",
  },
  plugins: [
    ...defaultPlugins,
    "zod",
    {
      enums: "typescript", // default
      name: "@hey-api/typescript",
    },
    {
      name: "@hey-api/client-nuxt",
      runtimeConfigPath: "~~/api.config.ts",
    },
    {
      asClass: true, // default
      name: "@hey-api/sdk",
    },
  ],
});

[9M6]

Also @mrlubos from 0.82 to 0.83 the runtimeConfigPath stopped resolving the path dynamically now seems to be a plain string.

[mrlubos]

Yeah there's an issue for that #2634

Thanks for the details on the Zod issue!

[alirezas]

Temporary fix it by running this code after generating

#!/usr/bin/env node

const fs = require("fs");
const path = require("path");

const zodFilePath = path.join(__dirname, "src/client/zod.gen.ts");

if (!fs.existsSync(zodFilePath)) {
  console.log("zod.gen.ts not found, skipping fix");
  process.exit(0);
}

let content = fs.readFileSync(zodFilePath, "utf8");

// Pattern to find variable declarations and usages
const exportPattern = /export const (z\w+) = z\.object\(/g;
const variableNames = [];

// Extract all zod variable names
let match;
while ((match = exportPattern.exec(content)) !== null) {
  variableNames.push(match[1]);
}

// For each variable, find where it's used before declaration and wrap with z.lazy()
variableNames.forEach((varName) => {
  const declarationPattern = new RegExp(`export const ${varName} = z\\.object\\(`);
  const declarationMatch = content.match(declarationPattern);

  if (!declarationMatch) return;

  const declarationIndex = content.indexOf(declarationMatch[0]);
  const beforeDeclaration = content.substring(0, declarationIndex);

  // Look for usages of this variable before its declaration
  const usagePattern = new RegExp(`(\\s+\\w+:\\s*)${varName}([,\\}])`, "g");

  let usageMatch;
  while ((usageMatch = usagePattern.exec(beforeDeclaration)) !== null) {
    const fullMatch = usageMatch[0];
    const prefix = usageMatch[1];
    const suffix = usageMatch[2];

    // Replace with lazy version
    const replacement = `${prefix}z.lazy(() => ${varName})${suffix}`;
    content = content.replace(fullMatch, replacement);
  }
});

// Write the fixed content back
fs.writeFileSync(zodFilePath, content);
console.log("✅ Fixed circular dependencies in zod.gen.ts");

[MeCapron]

Hmm so it's still an issue from #2560, no?

[KiwiKilian]

I'm also stuck with 0.83.1 due to this issue. While most circular references ware safely accessed with a getter function, one is used directly.

@alirezas why should this be handled with lazy as it was working properly befor with get functions?