# Upgrade npm Dependencies in a Turborepo Monorepo

Yes. Each week an agent moves the pnpm catalog and every workspace forward together, builds all apps, holds what breaks and opens one pull request with a table.

[Run this on Rush](https://cloud.getrush.ai/run/upgrade-npm-dependencies/turborepo/). Opens the console with this prompt ready to send, in a Project that has your repository.

## What the agent does

In a monorepo a version lives in one of several places, and the agent maps them before it changes any. In a Turborepo like t3-oss/create-t3-turbo, `pnpm-workspace.yaml` holds a default `catalog:` with the tools every package shares (`eslint`, `prettier`, `typescript`, `tailwindcss`, `zod`, the three `@trpc` packages, `@tanstack/react-query`), a named catalog `react19` with `react` and `react-dom` at exactly `19.1.4`, and an `overrides` block that forces `vite` to `7.1.12` and `lightningcss` to `1.30.1` across the tree. Each package then adds its own ranges: `next` `^16.0.9` in `apps/nextjs`, `drizzle-orm` `^0.44.7` and `drizzle-kit` in `packages/db`, `expo` `~54.0.20` and `react-native` `~0.81.5` in `apps/expo`. The root pins `pnpm@10.19.0` in `packageManager` and Node `^22.21.0` in `engines`, with `.nvmrc` at `22.21.0`.

It then reads what the repository already does about upgrades. `.github/renovate.json` extends `config:base` with `rangeStrategy` `bump` and `automerge` on, and skips the internal `@acme/` packages. But `.github/workflows/ci.yml` has three jobs, `lint`, `format` and `typecheck`: nothing in CI builds an app. So an automerged bump has been type-checked and linted, and no more. The agent's run adds the step CI lacks. After `cp .env.example .env`, the same copy the `lint` job makes, it runs `pnpm build` with `CI` set, which is `turbo run build`: `tsc` in the internal packages, `next build` in `apps/nextjs` and `vite build` in `apps/tanstack-start`. `CI` matters because `apps/nextjs/src/env.ts` and `packages/auth/env.ts` skip validation of `POSTGRES_URL` and the Discord secrets when it is set.

Candidates come from `pnpm outdated -r`, sorted into three groups. Releases inside a declared range are taken, catalog entries first, since one line there moves every package that says `catalog:`. Exact pins are moved only as a set and only when their reason allows it: `vite` appears in both the catalog and `overrides`, so both lines change or neither; `react` and `react-dom` in `react19` stay on the version the Expo app's React Native line accepts, and the `expo-*` packages with tilde ranges move through `npx expo install --check` inside `apps/expo`, not by hand. Prereleases are held by name: `better-auth` and its two companions at `1.4.0-beta.9`, `nitro` at `3.0.1-alpha.1`, `nativewind` at `5.0.0-preview.2`. A newer prerelease is a decision for a person, and the table says which ones exist.

Every group is checked by the same five commands: `pnpm install`, whose `postinstall` runs `pnpm lint:ws`, a `sherif` pass that fails on inconsistent manifests; `pnpm lint`; `pnpm format`; `pnpm typecheck`; and the build. `turbo`, `@turbo/gen` and `eslint-plugin-turbo` move together, since the lint rules and the task runner read the same `turbo.json`. When a command fails, the agent reverts one package at a time until it passes and moves the offender to the held list with the failing command and the first error line. The lockfile is regenerated by pnpm only; the agent does not edit `pnpm-lock.yaml` by hand.

## Start it with one API call

`POST https://api.phoenix.so/o/{org}/sessions`

```json
{
  "agent": "claude",
  "input": "Upgrade the dependencies of this Turborepo monorepo. Read the root package.json, pnpm-workspace.yaml including its catalogs and overrides, every workspace package.json, turbo.json, .github/renovate.json and .github/workflows/ci.yml first. Use the Node version in .nvmrc and the pnpm version in packageManager. Copy .env.example to .env and set CI=1 so env validation is skipped. Run pnpm outdated -r. Take releases inside the declared ranges, changing catalog entries in pnpm-workspace.yaml where a package uses catalog:. Move an exact pin only together with every other place that names it (the catalog and overrides for vite), keep react and react-dom on the version the Expo app accepts, and check the expo packages with npx expo install --check inside apps/expo. Hold every prerelease pin and list any newer prerelease. Keep turbo, @turbo/gen and eslint-plugin-turbo on one version. After each group run pnpm install, pnpm lint, pnpm lint:ws, pnpm format, pnpm typecheck and pnpm build. If a command fails, revert one package at a time until it passes and hold that package with the command and its first error line. Do not edit pnpm-lock.yaml by hand and do not change renovate.json. Open one pull request with a table of every dependency: where it is declared, before, after or held, and why, followed by the output of the final run of each command.",
  "resources": [
    {
      "url": "https://github.com/your-org/your-app"
    }
  ]
}
```

1. **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.
2. **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.
3. **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

One pull request that changes `pnpm-workspace.yaml`, the `package.json` files whose own ranges moved, and `pnpm-lock.yaml`. Its description is a table with a row per dependency: the file that declares it (the catalog, a named catalog, `overrides` or a package), the version before, the version after or `held`, and the reason. Held rows carry the failing command and its first error line, or `prerelease` with the newer versions that exist.

Under the table is the output of the final `pnpm lint`, `pnpm lint:ws`, `pnpm format`, `pnpm typecheck` and `pnpm build`. The first four are what the repository's CI will run on the pull request; the build is the part CI does not do, so its output in the description is the only record that `next build` and `vite build` passed on these versions.

A reviewer reads the held list first, then two things the run cannot judge. A build proves the apps compile, not that a screen still works, so a bump of `next`, `expo` or `@tanstack/react-start` deserves a manual look at the app. And nothing here starts the Expo app on a device, so React Native changes are checked by the Expo version check and the type checker only.

## Run it on every Monday morning

An automation in the Project that holds the repository takes this prompt and a `schedule` trigger with `cron` set to `0 7 * * 1` and the team's `timezone`. Each Monday it starts one run, which opens one pull request on its own branch. With Renovate's `automerge` still on, the two overlap; the usual split is to leave Renovate the patch releases and let this run take the catalog and anything that needs a build to trust.

To start it from your own scheduler instead, send this body to `POST /o/{org}/sessions` with a `request_id` that is a UUID v5 of the repository and the week's date, so a job that fires twice returns the run already started. A `webhook_url` on the key then receives `run.completed` with `session_url`, where the pull request is named.

## Why run it on Rush?

The slow part of a monorepo upgrade is the loop: install, four checks, two app builds, revert one package, again. On a laptop that loop holds the machine and a working tree for as long as it takes. In a Rush sandbox it runs to the end unattended, and a second repository's upgrade runs beside it in a separate sandbox.

The result is checkable after the fact. The table in the pull request says what moved; the run's transcript at `GET /o/{org}/sessions/{id}/messages` has each command and its output, the reverted attempts included, so a held package can be traced to the exact error that held it.

## Frequently asked questions

### We already run Renovate. Why add this?

Renovate proposes versions and your CI decides. In a repository like this one CI lints, formats and type-checks but never builds, so `automerge` merges on less evidence than it appears to. The agent's run builds every app in its sandbox and reverts what fails, and it leaves `renovate.json` untouched.

### Does it understand pnpm catalogs?

Yes. It edits the version in `pnpm-workspace.yaml` when a package declares the dependency as `catalog:` or `catalog:react19`, and the package file only when the range is its own. The table names which file each row changed.

### Will it move a beta or alpha pin to a stable release?

Not on its own. A project pins a prerelease for a reason the manifest does not record, so the agent holds those pins and lists the newer prereleases and any stable release that has appeared. Ask for the move in a follow-up message to the same session and it runs the same checks on it.

### What does it do about the Expo app?

It runs `npx expo install --check` in `apps/expo`, which compares the installed packages with what the Expo SDK in use expects, and keeps React on the version that app accepts. It does not start a simulator, so anything only visible on a device is for the reviewer.

## More Turborepo jobs

- [Write Vitest Tests for a Turborepo Monorepo](https://getrush.ai/run/write-vitest-tests/turborepo/)
- [Add Remote Caching to a Turborepo Monorepo](https://getrush.ai/run/add-remote-caching/turborepo/)
- [Review Pull Requests on a Turborepo Monorepo](https://getrush.ai/run/review-pull-requests/turborepo/)

## The same job on other stacks

- [Upgrade npm Dependencies in a Vite React App](https://getrush.ai/run/upgrade-npm-dependencies/vite-react/)
- [Upgrade npm Dependencies in a Vue App](https://getrush.ai/run/upgrade-npm-dependencies/vue/)
- [Upgrade npm Dependencies in a Chrome Extension Project](https://getrush.ai/run/upgrade-npm-dependencies/chrome-extension/)

## Keep reading

- [How a Rush run works on your repository, from request to pull request](https://getrush.ai/cloud/)
- [Compare cloud agents, agent sandboxes and AI code review](https://getrush.ai/compare/)
- [Rush pricing: Free, Pro and Max](https://getrush.ai/pricing/)
