Zodv4

[tkattkat]

why

we currently use zod v3, but there is a newer version v4

what changed

migrates from zod v3 to zod v4

test plan

tested locally & on api

[changeset-bot]

🦋 Changeset detected

Latest commit: ad1e461

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 2 packages

Name	Type
@browserbasehq/stagehand	Patch
@browserbasehq/stagehand-evals	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[greptile-apps]

Greptile Overview

Greptile Summary

This PR successfully migrates the codebase from Zod v3 to v4. The migration addresses all breaking API changes systematically across 89 files.

Key Changes:

• Updated Zod dependency from v3 to ^4.1.8 in both core and evals packages
• Removed zod-to-json-schema dependency (replaced with Zod v4's built-in z.toJSONSchema())
• Refactored utils.ts to access Zod v4's internal structure via _zod.def.type instead of _def.typeName
• Replaced all ZodFirstPartyTypeKind enum usage with string-based type checks
• Updated 87 import statements from zod/v3 to zod across examples and library files
• Added helper type ZodWithInternals<T> to safely access Zod v4 internals

Minor Concerns:

• The LangChain example now requires @ts-expect-error suppressions due to Zod v4's more complex type inference causing "Type instantiation is excessively deep" errors
• While the migration appears complete, the TypeScript errors suggest potential type compatibility issues that may surface in complex use cases

The migration follows a clear pattern and all imports have been updated consistently.

Confidence Score: 4/5

• This PR is generally safe to merge with local and API testing completed, though the TypeScript errors in examples warrant attention
• The migration is thorough and systematic, with all Zod v3 references successfully updated. The core logic changes in utils.ts properly handle Zod v4's new internal API structure. However, the addition of @ts-expect-error comments in the LangChain example indicates unresolved type complexity issues that could indicate broader type safety concerns with Zod v4's inference. The developer reports testing locally and on API, which is positive, but the TypeScript errors suggest edge cases may exist.
• Pay attention to packages/core/examples/custom_client_langchain.ts which has TypeScript errors requiring suppressions, and verify packages/core/lib/utils.ts thoroughly as it contains the most complex migration logic

Important Files Changed

File Analysis

Filename	Score	Overview
packages/core/package.json	5/5	Updated Zod dependency from v3 to ^4.1.8 and removed zod-to-json-schema dependency (no longer needed with Zod v4's built-in JSON schema conversion)
packages/core/lib/utils.ts	4/5	Major refactor to support Zod v4's new internal structure: replaced _def.typeName with _zod.def.type, added type wrappers for accessing internals, and updated all type string checks from ZodFirstPartyTypeKind enum to plain strings
packages/core/lib/v3/llm/LLMClient.ts	5/5	Updated import from zod/v3 to zod, added LLMParsedResponse type definition, and improved createChatCompletion method overloads for better type safety
packages/core/lib/v3/api.ts	5/5	Replaced zodToJsonSchema with Zod v4's native z.toJSONSchema() method and updated import from zod/v3 to zod
packages/core/examples/custom_client_langchain.ts	3/5	Updated import from zod/v3 to zod, but added two @ts-expect-error comments for "Type instantiation is excessively deep and possibly infinite" errors introduced by Zod v4

Sequence Diagram

sequenceDiagram
    participant Dev as Developer
    participant Pkg as package.json
    participant Zod as Zod v3 → v4
    participant Utils as utils.ts
    participant API as Core API Files
    participant Examples as Examples & Evals
    
    Dev->>Pkg: Update zod: ^3 → ^4.1.8
    Dev->>Pkg: Remove zod-to-json-schema dependency
    
    Dev->>Zod: Migrate to v4 API
    Note over Zod: Breaking Changes:<br/>- _def.typeName → _zod.def.type<br/>- ZodFirstPartyTypeKind → string types<br/>- Built-in toJSONSchema()
    
    Dev->>Utils: Refactor getZodType()
    Utils-->>Utils: Access _zod.def.type instead of _def.typeName
    Dev->>Utils: Update transformSchema()
    Utils-->>Utils: Add ZodWithInternals type helper
    Utils-->>Utils: Import from zod/v4/core for internals
    
    Dev->>API: Replace zodToJsonSchema()
    API-->>API: Use z.toJSONSchema() instead
    
    Dev->>Examples: Update all imports
    Examples-->>Examples: Change from "zod/v3" to "zod"
    
    Note over Examples: Known Issue:<br/>LangChain example requires<br/>@ts-expect-error for deep types

Loading

Additional Comments (1)

1. packages/core/examples/custom_client_langchain.ts, line 12-21 (link)

   style: Two @ts-expect-error suppressions added for "Type instantiation is excessively deep" errors. This is a known issue with Zod v4's more complex type inference. Consider if this is acceptable for an example file or if types can be simplified.

_{88 files reviewed, 1 comment}

_{Edit Code Review Agent Settings | Greptile}