bump zod version and add pathing spec (#944)

seanmcguire12 · miguelg719 · web-flow · commit 8de7bd8635c2 · 2025-08-06T15:03:38.000-07:00
# why
To enable compatibility with Zod v4

# what changed
Added v3 pathing spec and allowed zod peer dependency to be `"zod":
"&gt;=3.25.0 &lt;4.1.0"`

# test plan

---------

Co-authored-by: miguel &lt;miguelg71921@gmail.com&gt;
diff --git a/.changeset/clear-clouds-build.md b/.changeset/clear-clouds-build.md
@@ -0,0 +1,5 @@
+---
+"@browserbasehq/stagehand": patch
+---
+
+Bump zod version compatibility and add pathing spec
diff --git a/docs/examples/nextjs.mdx b/docs/examples/nextjs.mdx
@@ -47,7 +47,7 @@ Next, let's define our `main` function as a server action in `app/stagehand/main
 "use server";
 
 import { Stagehand } from "@browserbasehq/stagehand";
-import { z } from "zod";
+import { z } from "zod/v3";
 import { Browserbase } from "@browserbasehq/sdk";
 
 /**
diff --git a/docs/get_started/quickstart.mdx b/docs/get_started/quickstart.mdx
@@ -206,7 +206,7 @@ Create a file `index.ts`:
 // index.ts
 import { Stagehand, ConstructorParams } from "@browserbasehq/stagehand";
 import dotenv from "dotenv";
-import { z } from "zod";
+import { z } from "zod/v3";
 
 dotenv.config();
 
diff --git a/docs/package.json b/docs/package.json
@@ -13,7 +13,7 @@
   "dependencies": {
     "mintlify": "^4.0.401",
     "tsx": "^4.19.2",
-    "zod": "^3.24.1"
+    "zod": "^3.25.0"
   },
   "packageManager": "pnpm@9.15.0+sha512.76e2379760a4328ec4415815bcd6628dee727af3779aaa4c914e3944156c4299921a89f976381ee107d41f12cfa4b66681ca9c718f0668fa0831ed4c6d8ba56c"
 }
diff --git a/evals/deterministic/tests/Errors/apiKeyError.test.ts b/evals/deterministic/tests/Errors/apiKeyError.test.ts
@@ -1,7 +1,7 @@
 import { test, expect } from "@playwright/test";
 import { Stagehand } from "@browserbasehq/stagehand";
 import StagehandConfig from "@/evals/deterministic/stagehand.config";
-import { z } from "zod";
+import { z } from "zod/v3";
 
 test.describe("API key/LLMClient error", () => {
   test("Should confirm that we get an error if we call extract without LLM API key or LLMClient", async () => {
diff --git a/evals/llm_clients/hn_aisdk.ts b/evals/llm_clients/hn_aisdk.ts
@@ -1,6 +1,6 @@
 import { Stagehand } from "@browserbasehq/stagehand";
 import { EvalFunction } from "@/types/evals";
-import { z } from "zod";
+import { z } from "zod/v3";
 
 export const hn_aisdk: EvalFunction = async ({
   debugUrl,
diff --git a/evals/llm_clients/hn_customOpenAI.ts b/evals/llm_clients/hn_customOpenAI.ts
@@ -1,5 +1,5 @@
 import { EvalFunction } from "@/types/evals";
-import { z } from "zod";
+import { z } from "zod/v3";
 import { CustomOpenAIClient } from "@/examples/external_clients/customOpenAI";
 import OpenAI from "openai";
 import { Stagehand } from "@browserbasehq/stagehand";
diff --git a/evals/llm_clients/hn_langchain.ts b/evals/llm_clients/hn_langchain.ts
@@ -1,5 +1,5 @@
 import { EvalFunction } from "@/types/evals";
-import { z } from "zod";
+import { z } from "zod/v3";
 import { LangchainClient } from "@/examples/external_clients/langchain";
 import { ChatOpenAI } from "@langchain/openai";
 import { Stagehand } from "@browserbasehq/stagehand";
diff --git a/evals/tasks/allrecipes.ts b/evals/tasks/allrecipes.ts
@@ -1,5 +1,5 @@
 import { EvalFunction } from "@/types/evals";
-import { z } from "zod";
+import { z } from "zod/v3";
 
 export const allrecipes: EvalFunction = async ({
   logger,
diff --git a/evals/tasks/arxiv.ts b/evals/tasks/arxiv.ts
@@ -1,5 +1,5 @@
 import { EvalFunction } from "@/types/evals";
-import { z } from "zod";
+import { z } from "zod/v3";
 
 export const arxiv: EvalFunction = async ({
   logger,
diff --git a/evals/tasks/combination_sauce.ts b/evals/tasks/combination_sauce.ts
@@ -1,5 +1,5 @@
 import { EvalFunction } from "@/types/evals";
-import { z } from "zod";
+import { z } from "zod/v3";
 
 export const combination_sauce: EvalFunction = async ({
   logger,
diff --git a/evals/tasks/costar.ts b/evals/tasks/costar.ts
@@ -1,5 +1,5 @@
 import { EvalFunction } from "@/types/evals";
-import { z } from "zod";
+import { z } from "zod/v3";
 
 export const costar: EvalFunction = async ({
   logger,
diff --git a/evals/tasks/extract_aigrant_companies.ts b/evals/tasks/extract_aigrant_companies.ts
@@ -1,4 +1,4 @@
-import { z } from "zod";
+import { z } from "zod/v3";
 import { EvalFunction } from "@/types/evals";
 
 export const extract_aigrant_companies: EvalFunction = async ({
diff --git a/evals/tasks/extract_aigrant_targeted.ts b/evals/tasks/extract_aigrant_targeted.ts
@@ -1,4 +1,4 @@
-import { z } from "zod";
+import { z } from "zod/v3";
 import { EvalFunction } from "@/types/evals";
 
 export const extract_aigrant_targeted: EvalFunction = async ({
diff --git a/evals/tasks/extract_aigrant_targeted_2.ts b/evals/tasks/extract_aigrant_targeted_2.ts
@@ -1,4 +1,4 @@
-import { z } from "zod";
+import { z } from "zod/v3";
 import { EvalFunction } from "@/types/evals";
 
 export const extract_aigrant_targeted_2: EvalFunction = async ({
diff --git a/evals/tasks/extract_apartments.ts b/evals/tasks/extract_apartments.ts
@@ -1,4 +1,4 @@
-import { z } from "zod";
+import { z } from "zod/v3";
 import { EvalFunction } from "../../types/evals";
 
 export const extract_apartments: EvalFunction = async ({
diff --git a/evals/tasks/extract_area_codes.ts b/evals/tasks/extract_area_codes.ts
@@ -1,5 +1,5 @@
 import { EvalFunction } from "@/types/evals";
-import { z } from "zod";
+import { z } from "zod/v3";
 
 export const extract_area_codes: EvalFunction = async ({
   logger,
diff --git a/evals/tasks/extract_baptist_health.ts b/evals/tasks/extract_baptist_health.ts
@@ -1,6 +1,6 @@
 import { EvalFunction } from "@/types/evals";
 import { compareStrings } from "@/evals/utils";
-import { z } from "zod";
+import { z } from "zod/v3";
 
 export const extract_baptist_health: EvalFunction = async ({
   logger,
diff --git a/evals/tasks/extract_capacitor_info.ts b/evals/tasks/extract_capacitor_info.ts
@@ -1,6 +1,6 @@
 import { EvalFunction } from "@/types/evals";
 import { normalizeString } from "@/evals/utils";
-import { z } from "zod";
+import { z } from "zod/v3";
 
 export const extract_capacitor_info: EvalFunction = async ({
   logger,
diff --git a/evals/tasks/extract_collaborators.ts b/evals/tasks/extract_collaborators.ts
@@ -1,5 +1,5 @@
 import { EvalFunction } from "@/types/evals";
-import { z } from "zod";
+import { z } from "zod/v3";
 
 export const extract_collaborators: EvalFunction = async ({
   logger,
diff --git a/evals/tasks/extract_csa.ts b/evals/tasks/extract_csa.ts
@@ -1,5 +1,5 @@
 import { EvalFunction } from "@/types/evals";
-import { z } from "zod";
+import { z } from "zod/v3";
 
 export const extract_csa: EvalFunction = async ({
   debugUrl,
diff --git a/evals/tasks/extract_geniusee.ts b/evals/tasks/extract_geniusee.ts
@@ -1,4 +1,4 @@
-import { z } from "zod";
+import { z } from "zod/v3";
 import { EvalFunction } from "@/types/evals";
 
 export const extract_geniusee: EvalFunction = async ({
diff --git a/evals/tasks/extract_geniusee_2.ts b/evals/tasks/extract_geniusee_2.ts
@@ -1,4 +1,4 @@
-import { z } from "zod";
+import { z } from "zod/v3";
 import { EvalFunction } from "@/types/evals";
 
 export const extract_geniusee_2: EvalFunction = async ({
diff --git a/evals/tasks/extract_github_commits.ts b/evals/tasks/extract_github_commits.ts
@@ -1,5 +1,5 @@
 import { EvalFunction } from "@/types/evals";
-import { z } from "zod";
+import { z } from "zod/v3";
 
 export const extract_github_commits: EvalFunction = async ({
   logger,
diff --git a/evals/tasks/extract_github_stars.ts b/evals/tasks/extract_github_stars.ts
@@ -1,5 +1,5 @@
 import { EvalFunction } from "@/types/evals";
-import { z } from "zod";
+import { z } from "zod/v3";
 
 export const extract_github_stars: EvalFunction = async ({
   logger,
diff --git a/evals/tasks/extract_hamilton_weather.ts b/evals/tasks/extract_hamilton_weather.ts
@@ -1,5 +1,5 @@
 import { EvalFunction } from "@/types/evals";
-import { z } from "zod";
+import { z } from "zod/v3";
 import { compareStrings } from "@/evals/utils";
 
 export const extract_hamilton_weather: EvalFunction = async ({
diff --git a/evals/tasks/extract_jfk_links.ts b/evals/tasks/extract_jfk_links.ts
@@ -1,5 +1,5 @@
 import { EvalFunction } from "@/types/evals";
-import { z } from "zod";
+import { z } from "zod/v3";
 
 export const extract_jfk_links: EvalFunction = async ({
   logger,
diff --git a/evals/tasks/extract_jstor_news.ts b/evals/tasks/extract_jstor_news.ts
@@ -1,5 +1,5 @@
 import { EvalFunction } from "@/types/evals";
-import { z } from "zod";
+import { z } from "zod/v3";
 
 export const extract_jstor_news: EvalFunction = async ({
   logger,
diff --git a/evals/tasks/extract_memorial_healthcare.ts b/evals/tasks/extract_memorial_healthcare.ts
@@ -1,5 +1,5 @@
 import { EvalFunction } from "@/types/evals";
-import { z } from "zod";
+import { z } from "zod/v3";
 import { compareStrings } from "@/evals/utils";
 
 export const extract_memorial_healthcare: EvalFunction = async ({
diff --git a/evals/tasks/extract_nhl_stats.ts b/evals/tasks/extract_nhl_stats.ts
@@ -1,6 +1,6 @@
 import { EvalFunction } from "@/types/evals";
 import { normalizeString } from "@/evals/utils";
-import { z } from "zod";
+import { z } from "zod/v3";
 
 export const extract_nhl_stats: EvalFunction = async ({
   debugUrl,
diff --git a/evals/tasks/extract_partners.ts b/evals/tasks/extract_partners.ts
@@ -1,5 +1,5 @@
 import { EvalFunction } from "@/types/evals";
-import { z } from "zod";
+import { z } from "zod/v3";
 
 export const extract_partners: EvalFunction = async ({
   debugUrl,
diff --git a/evals/tasks/extract_press_releases.ts b/evals/tasks/extract_press_releases.ts
@@ -1,5 +1,5 @@
 import { EvalFunction } from "@/types/evals";
-import { z } from "zod";
+import { z } from "zod/v3";
 import { compareStrings } from "@/evals/utils";
 
 export const extract_press_releases: EvalFunction = async ({
diff --git a/evals/tasks/extract_professional_info.ts b/evals/tasks/extract_professional_info.ts
@@ -1,6 +1,6 @@
 import { EvalFunction } from "@/types/evals";
 import { normalizeString } from "@/evals/utils";
-import { z } from "zod";
+import { z } from "zod/v3";
 
 export const extract_professional_info: EvalFunction = async ({
   debugUrl,
diff --git a/evals/tasks/extract_public_notices.ts b/evals/tasks/extract_public_notices.ts
@@ -1,5 +1,5 @@
 import { EvalFunction } from "@/types/evals";
-import { z } from "zod";
+import { z } from "zod/v3";
 import { compareStrings } from "@/evals/utils";
 
 export const extract_public_notices: EvalFunction = async ({
diff --git a/evals/tasks/extract_recipe.ts b/evals/tasks/extract_recipe.ts
@@ -1,5 +1,5 @@
 import { EvalFunction } from "@/types/evals";
-import { z } from "zod";
+import { z } from "zod/v3";
 
 export const extract_recipe: EvalFunction = async ({
   debugUrl,
diff --git a/evals/tasks/extract_regulations_table.ts b/evals/tasks/extract_regulations_table.ts
@@ -1,5 +1,5 @@
 import { EvalFunction } from "@/types/evals";
-import { z } from "zod";
+import { z } from "zod/v3";
 
 export const extract_regulations_table: EvalFunction = async ({
   debugUrl,
diff --git a/evals/tasks/extract_resistor_info.ts b/evals/tasks/extract_resistor_info.ts
@@ -1,6 +1,6 @@
 import { EvalFunction } from "@/types/evals";
 import { normalizeString } from "@/evals/utils";
-import { z } from "zod";
+import { z } from "zod/v3";
 
 export const extract_resistor_info: EvalFunction = async ({
   debugUrl,
diff --git a/evals/tasks/extract_rockauto.ts b/evals/tasks/extract_rockauto.ts
@@ -1,5 +1,5 @@
 import { EvalFunction } from "@/types/evals";
-import { z } from "zod";
+import { z } from "zod/v3";
 
 export const extract_rockauto: EvalFunction = async ({
   debugUrl,
diff --git a/evals/tasks/extract_single_link.ts b/evals/tasks/extract_single_link.ts
@@ -1,5 +1,5 @@
 import { EvalFunction } from "@/types/evals";
-import { z } from "zod";
+import { z } from "zod/v3";
 
 export const extract_single_link: EvalFunction = async ({
   logger,
diff --git a/evals/tasks/extract_snowshoeing_destinations.ts b/evals/tasks/extract_snowshoeing_destinations.ts
@@ -1,4 +1,4 @@
-import { z } from "zod";
+import { z } from "zod/v3";
 import { EvalFunction } from "@/types/evals";
 
 export const extract_snowshoeing_destinations: EvalFunction = async ({
diff --git a/evals/tasks/extract_staff_members.ts b/evals/tasks/extract_staff_members.ts
@@ -1,4 +1,4 @@
-import { z } from "zod";
+import { z } from "zod/v3";
 import { EvalFunction } from "@/types/evals";
 
 export const extract_staff_members: EvalFunction = async ({
diff --git a/evals/tasks/extract_zillow.ts b/evals/tasks/extract_zillow.ts
@@ -1,4 +1,4 @@
-import { z } from "zod";
+import { z } from "zod/v3";
 import { EvalFunction } from "../../types/evals";
 
 export const extract_zillow: EvalFunction = async ({
diff --git a/evals/tasks/homedepot.ts b/evals/tasks/homedepot.ts
@@ -1,5 +1,5 @@
 import { EvalFunction } from "@/types/evals";
-import { z } from "zod";
+import { z } from "zod/v3";
 
 export const homedepot: EvalFunction = async ({
   debugUrl,
diff --git a/evals/tasks/iframe_hn.ts b/evals/tasks/iframe_hn.ts
@@ -1,5 +1,5 @@
 import { EvalFunction } from "@/types/evals";
-import { z } from "zod";
+import { z } from "zod/v3";
 
 export const iframe_hn: EvalFunction = async ({
   debugUrl,
diff --git a/evals/tasks/imdb_movie_details.ts b/evals/tasks/imdb_movie_details.ts
@@ -1,5 +1,5 @@
 import { EvalFunction } from "@/types/evals";
-import { z } from "zod";
+import { z } from "zod/v3";
 
 export const imdb_movie_details: EvalFunction = async ({
   debugUrl,
diff --git a/evals/tasks/peeler_complex.ts b/evals/tasks/peeler_complex.ts
@@ -1,5 +1,5 @@
 import { EvalFunction } from "@/types/evals";
-import { z } from "zod";
+import { z } from "zod/v3";
 
 export const peeler_complex: EvalFunction = async ({
   debugUrl,
diff --git a/evals/tasks/sciquest.ts b/evals/tasks/sciquest.ts
@@ -1,5 +1,5 @@
 import { EvalFunction } from "@/types/evals";
-import { z } from "zod";
+import { z } from "zod/v3";
 
 export const sciquest: EvalFunction = async ({
   debugUrl,
diff --git a/evals/tasks/ted_talk.ts b/evals/tasks/ted_talk.ts
@@ -1,6 +1,6 @@
 import { EvalFunction } from "@/types/evals";
 import { normalizeString } from "@/evals/utils";
-import { z } from "zod";
+import { z } from "zod/v3";
 
 export const ted_talk: EvalFunction = async ({
   debugUrl,
diff --git a/evals/tasks/wichita.ts b/evals/tasks/wichita.ts
@@ -1,5 +1,5 @@
 import { EvalFunction } from "@/types/evals";
-import { z } from "zod";
+import { z } from "zod/v3";
 
 export const wichita: EvalFunction = async ({
   debugUrl,
diff --git a/examples/2048.ts b/examples/2048.ts
@@ -1,5 +1,5 @@
 import { Stagehand } from "@browserbasehq/stagehand";
-import { z } from "zod";
+import { z } from "zod/v3";
 
 async function example() {
   console.log("🎮 Starting 2048 bot...");
diff --git a/examples/custom_client_aisdk.ts b/examples/custom_client_aisdk.ts
@@ -8,7 +8,7 @@
 import { Stagehand } from "@browserbasehq/stagehand";
 import StagehandConfig from "@/stagehand.config";
 import { AISdkClient } from "./external_clients/aisdk";
-import { z } from "zod";
+import { z } from "zod/v3";
 import { openai } from "@ai-sdk/openai";
 
 async function example() {
diff --git a/examples/custom_client_langchain.ts b/examples/custom_client_langchain.ts
@@ -3,7 +3,7 @@
  *
  * You will need to reference the Langchain Client in /external_clients/langchain.ts
  */
-import { z } from "zod";
+import { z } from "zod/v3";
 import { Stagehand } from "@browserbasehq/stagehand";
 import StagehandConfig from "@/stagehand.config";
 import { LangchainClient } from "./external_clients/langchain";
diff --git a/examples/custom_client_openai.ts b/examples/custom_client_openai.ts
@@ -6,7 +6,7 @@
  * You will need to reference the Custom OpenAI Client in /external_clients/customOpenAI.ts
  */
 import { Stagehand } from "@browserbasehq/stagehand";
-import { z } from "zod";
+import { z } from "zod/v3";
 import { CustomOpenAIClient } from "./external_clients/customOpenAI";
 import StagehandConfig from "@/stagehand.config";
 import OpenAI from "openai";
diff --git a/examples/external_clients/customOpenAI.ts b/examples/external_clients/customOpenAI.ts
@@ -22,7 +22,7 @@ import type {
   ChatCompletionSystemMessageParam,
   ChatCompletionUserMessageParam,
 } from "openai/resources/chat/completions";
-import { z } from "zod";
+import { z } from "zod/v3";
 import { CreateChatCompletionResponseError } from "@/types/stagehandErrors";
 
 function validateZodSchema(schema: z.ZodTypeAny, data: unknown) {
diff --git a/examples/parameterizeApiKey.ts b/examples/parameterizeApiKey.ts
@@ -1,5 +1,5 @@
 import { Stagehand } from "@browserbasehq/stagehand";
-import { z } from "zod";
+import { z } from "zod/v3";
 
 /**
  * This example shows how to parameterize the API key for the LLM provider.
diff --git a/lib/StagehandPage.ts b/lib/StagehandPage.ts
diff --git a/lib/api.ts b/lib/api.ts
diff --git a/lib/handlers/extractHandler.ts b/lib/handlers/extractHandler.ts
diff --git a/lib/index.ts b/lib/index.ts
diff --git a/lib/inference.ts b/lib/inference.ts
diff --git a/lib/llm/LLMClient.ts b/lib/llm/LLMClient.ts
diff --git a/lib/utils.ts b/lib/utils.ts
diff --git a/package.json b/package.json
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
diff --git a/types/evals.ts b/types/evals.ts
diff --git a/types/model.ts b/types/model.ts
diff --git a/types/operator.ts b/types/operator.ts
diff --git a/types/page.ts b/types/page.ts
diff --git a/types/stagehand.ts b/types/stagehand.ts
diff --git a/types/stagehandErrors.ts b/types/stagehandErrors.ts

Original file line number	Diff line number	Diff line change
`@@ -13,7 +13,7 @@`
`13`	`13`	`"dependencies": {`
`14`	`14`	`"mintlify": "^4.0.401",`
`15`	`15`	`"tsx": "^4.19.2",`
`16`		`- "zod": "^3.24.1"`
	`16`	`+ "zod": "^3.25.0"`
`17`	`17`	`},`
`18`	`18`	`"packageManager": "[email protected]+sha512.76e2379760a4328ec4415815bcd6628dee727af3779aaa4c914e3944156c4299921a89f976381ee107d41f12cfa4b66681ca9c718f0668fa0831ed4c6d8ba56c"`
`19`	`19`	`}`