What the agent does
The agent maps where Zod is used and what stands between it and the screen. In a React app like alan2207/bulletproof-react, the Vite app under apps/react-vite asks for zod ^3.23.4, @hookform/resolvers ^3.3.4 and react-hook-form ^7.51.3, and yarn.lock resolves 3.23.6, 3.3.4 and 7.51.3. Nine files import Zod. Four are feature API modules that export an input schema next to their mutation, such as createCommentInputSchema; src/lib/auth.tsx holds the login and registration schemas; src/config/env.ts validates the VITE_APP_ variables when it is imported; and src/components/ui/form/form.tsx is the one place schemas meet forms, typed as Schema extends ZodType<any, any, any> and passed to zodResolver(schema). The remaining two are that component's test and story. Every form in the app goes through that one resolver call.
It records a baseline with the four commands .github/workflows/react-vite-ci.yml runs in that directory after moving .env.example to .env: yarn build, yarn test, yarn lint and yarn check-types. Then it upgrades Zod alone, on purpose, to see what the compiler says. It says nothing. yarn check-types exits 0 on Zod 4 with the old resolver, because every schema here is written with calls that still exist. The test suite is what objects: one test in src/components/ui/form/__tests__/form.test.tsx, the one that submits an empty title and waits for an alert reading Required, fails. The old resolver does not recognise a Zod 4 error, so the ZodError escapes as an exception and no field message renders. In the running app that is every form failing to show validation errors, with a clean type check.
So the upgrade is a pair. The agent reads the resolver's peer ranges from npm and takes a release that lists Zod 4: when this page was written, @hookform/resolvers 7.0.3 declared zod ^3.25.0 || ^4.0.0 and react-hook-form ^7.55.0. With that installed the failing test passes again, and so do the type check, the lint and the build. Yarn only warns that the locked react-hook-form 7.51.3 is under the new peer range, so the agent raises it within its caret to satisfy the resolver and reruns everything, since a warning is the only signal the package manager gives. It runs the Playwright suite the workflow's second job runs, with .env.example-e2e, because e2e/tests/auth.setup.ts registers a user through the real page, which drives the form with the most involved schema from the browser.
Last, it reads the installed typings for what now carries a deprecation note and decides case by case. .email('Invalid email') on a string is deprecated in favour of z.email(), but loginInputSchema chains it after .min(1, 'Required'), and swapping to the top-level form would change which message an empty field shows; the agent leaves it and lists it. parsedEnv.error.flatten() in src/config/env.ts is deprecated and still works; it lists that too. The registration schema's union, whose branches use z.null().default(null), is checked by parsing both shapes before and after the upgrade and comparing the results. Nothing in the pull request rewrites a schema that still behaves the same.
Start it with one API call
POST https://api.phoenix.so/o/{org}/sessions with this body:
{
"agent": "claude",
"input": "Upgrade Zod from 3 to the latest stable 4 in the Vite app under apps/react-vite. Read package.json, yarn.lock (resolved zod, @hookform/resolvers, react-hook-form, typescript and vitest versions), .env.example, vite.config.ts, src/config/env.ts, src/lib/auth.tsx, src/components/ui/form/form.tsx with its test and story, every file under src that imports zod, and .github/workflows/react-vite-ci.yml first. In that directory move .env.example to .env, then run yarn install, yarn build, yarn test --run, yarn lint and yarn check-types and record each result as the baseline. Upgrade zod by itself first and rerun all four: report exactly what fails, and note that a passing type check is not proof. Then read the peer dependencies of @hookform/resolvers from npm, install a release whose range includes Zod 4, raise react-hook-form if that release's peer range requires it, and rerun all four. Run the Playwright suite the workflow's e2e job runs. Parse a valid and an invalid value through loginInputSchema, both branches of registerInputSchema, and the env schema before and after the upgrade and compare the outputs and messages. Do not rewrite schemas to new Zod 4 APIs in this pull request: list each use that now carries a deprecation note in the installed typings, with file and line, and say why you left it. Do not upgrade unrelated packages. Open a pull request with a version table, the four checks before, after Zod alone, and after the resolver, the Playwright result, and the list of deprecated uses.",
"resources": [
{
"url": "https://github.com/your-org/your-app"
}
]
}- Get an API key. In the console, open Settings, then API keys, and create a key for your org. Send it in the Authorization header as a Bearer token.
- Send the request. POST the body in request.json to https://api.phoenix.so/o/{org}/sessions, with your repository as the resources URL. The run starts in its own cloud sandbox.
- Read what came back. Follow the run on its live stream or wait for the run.completed webhook, then read the result and its trajectory.
What comes back
A pull request that changes apps/react-vite/package.json and yarn.lock and, if the checks demand it, nothing else. The description opens with a table of three packages, zod, @hookform/resolvers and react-hook-form, with the version before and after and the peer range that tied them together. The second table is the one to read: build, tests, lint and type check in three columns, the baseline, Zod 4 with the old resolver, and the final state. The middle column shows the type check passing and one test failing, with the test's name and the error, which is the argument for why the resolver had to move in the same commit.
A reviewer starts with the forms, not the diff. They submit one invalid form in a preview build and look for the field message, since that is the behaviour that regressed in the middle state. They read default error messages wherever the app relies on Zod's own wording, because Zod 4 words several of them differently; this app passes its own strings, such as Required, so the visible text holds. And they check the resolver's major jump for anything else that depends on it, such as a second form library or a custom resolver.
Run it on every start of the quarter
Majors of a validation library are rare, and the pairing with a resolver is what makes each one worth a real run. Create an automation in the Project that holds the repository with a schedule trigger whose cron is 0 9 1 */3 * in your timezone, and this page's prompt with one line added: if yarn.lock already resolves the latest stable Zod and a resolver whose peer range includes it, end with one sentence and open nothing. It runs as the member who last changed the automation, and its pull request comes from the branch the run pushed.
A version bot does not cover this. Its pull request would raise zod alone, the type check would pass, and whether anyone notices depends on a single test. Nor can it start this automation through a github trigger, which never fires for a bot's work.
The use case this job follows, with its automation and trigger: Upgrade dependencies weekly.
Why run it on Rush?
The dangerous moment in this upgrade is a state that looks finished: the install succeeds and the compiler is satisfied while every form has stopped showing validation errors. Seeing it takes running the suite at each step, not only at the end, and then the browser tests on top. The agent works through baseline, Zod alone and the paired upgrade in its own sandbox, installs the browsers Playwright needs there, and keeps each command with its output in the session's transcript at GET /o/{org}/sessions/{id}/messages.
It also keeps the pull request small enough to trust. A person doing this by hand tends to fix deprecations along the way, and the diff becomes a mix of version changes and rewritten schemas that no one can review as either. The request draws the line: versions move, behaviour is compared, deprecated calls are listed for a second pass.
Frequently asked questions
Does @hookform/resolvers work with Zod 4?
Only a release that says so in its peer range. The 3.3.4 locked in this app predates Zod 4 and lets its errors escape as exceptions. When this page was written, 7.0.3 listed zod ^3.25.0 || ^4.0.0 and needed react-hook-form ^7.55.0. The agent reads the range from npm at the time of the run.
Why did type checking pass when the forms were broken?
The schemas use calls that exist in both majors, and the resolver's types accept the new schema object. What changed is the error object at runtime, which the old resolver does not recognise. Only executing a failed validation shows it, which is why the request runs the tests after each step.
Do I have to rewrite z.string().email() and other deprecated calls?
Not to upgrade. They still work in Zod 4 and carry a deprecation note. Some replacements change behaviour, such as which message an empty email field shows when .email() followed .min(1), so this request lists them and leaves the rewriting to a separate pull request with its own comparisons.
More Zod jobs
More jobs like this: Upgrade dependencies weekly
- Add cargo-audit to CI for a Rust CLI (Rust CLI)
- Add cargo-audit to CI for a Tokio Application (Tokio)
- Add cargo-deny to a Rust Workspace (Rust)
- Add cargo-deny to a Rust Library Workspace (Rust library)