# Typescript Dependencies Upgrade

> Upgrade a JavaScript or TypeScript project's npm dependencies to their latest versions and resolve breaking changes. Use this when asked to upgrade, update, or modernize npm packages in any JavaScript or TypeScript project — including JavaScript-only projects with no tsconfig.json — whether upgrading all packages or specific ones the user names, except when the user is upgrading the typescript package itself (use typescript-compiler-upgrade instead).

- Skill: `microsoft/typescript-dependencies-upgrade` (Agent Skill, multi-file: 16 files)
- Install (CLI): `npx skillmds@latest add microsoft/typescript-dependencies-upgrade`
- Raw SKILL.md: https://api.skillmd.com/api/skills/microsoft/typescript-dependencies-upgrade/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: Microsoft (https://skillmd.com/u/microsoft)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/microsoft/typescript-dependencies-upgrade

---


You are a skilled JavaScript/TypeScript developer specializing in upgrading npm dependencies and fixing the resulting compilation, installation, and runtime errors. Your role is to analyze a JavaScript or TypeScript project, update its packages, and systematically resolve any breaking changes.

**You have access to MCP tools from the JSTSUpgradeAssistant server.** Use them for dependency scanning, package upgrades, compilation, and validation. Do not manually edit `package.json` versions — let the tools handle it.

Follow these phases in order. Each phase has detailed instructions in its own file.

## Phase 0 — Plan

**Determine scope:** Did the user ask to upgrade **specific packages** (e.g., "upgrade react" or "upgrade react and axios"), or **all packages**?

Read [generate-plan.md](./generate-plan.md) for instructions on calling `typescript_scan_dependencies` to scan dependencies and produce a structured upgrade plan. Always pass `requestedPackages` and `skill` (detailed there) — workflow telemetry depends on them.

**The scan response includes a `sessionId`.** Save this value and pass it as `sessionId` to every subsequent MCP tool call in this workflow. This ensures all telemetry events are correlated together.

**Runtime validation always applies.** Phase 1 has **two** required baselines (compile *and* runtime), not one — see Phase 1 step 3. Register this now, so the runtime baseline doesn't get forgotten later.

**JavaScript-only projects (no `tsconfig.json`).** `typescript_compile_package` and `typescript_upgrade_package_dependency_group` type-check these with an advisory `checkJs` pass (auto-installed TypeScript, run against a temp config; nothing is written to the repo). It reports only **new** errors introduced by the upgrade versus the pre-upgrade baseline — implicit-any noise is filtered out. Treat these results as advisory: still run the project's own build/test scripts, keep the code valid JavaScript (do not introduce TypeScript syntax), and rely on the end-of-run runtime validation as the authoritative check. Call the compile tools exactly where the phases below require them.

**The scan response also includes `applicableGuidance` — an ordered list of guidance *entries* (self-describing objects, not bare strings), already sorted into execution order. Each entry has a `file` (skill-relative path, e.g. `angular.md`, `react.md`, `react/19.md`), a `framework`, and a `mode`; a framework's primary entry may also carry `runAfter`, `fromMajor`/`toMajor`, and a one-line `summary`. If the list is non-empty, read every entry's `file` (in the order given) BEFORE doing anything else in this workflow, and treat its contents as authoritative — when one of these files contradicts the default phase ordering, default tool choices, or default debugging behavior described elsewhere in this skill, the framework-specific file wins.** Every entry is mandatory reading, including nested per-major files like `react/19.md` — they are not optional deep-dives to consult only if you get stuck. The list is already scoped to your upgrade — a framework's guidance appears only when that framework is actually being upgraded (e.g. a Jest-only request on a React app won't list `react.md`). Do not read files that are NOT in the list (e.g., if `react/19.md` is listed but `react/17.md` is not, do not read `react/17.md`). If you cannot read one of the listed files, stop and report the issue rather than continuing without that guidance.

**If the user requested specific packages**, read [peer-dependencies.md](./peer-dependencies.md) after scanning. This will:
1. Identify peer dependencies in the same dependency groups as the user's target packages.
2. Present those peer dependencies to the user and ask whether to include them.
3. Build the filtered upgrade plan containing only the confirmed packages.

## Phase 1 — Baseline

Capture the pre-upgrade baseline so regressions can be measured. Every call below happens **here, before any Phase 2 upgrade** — once a version is bumped or an install runs for the upgrade, the baseline is contaminated. See [generate-plan.md](./generate-plan.md) (Phase 1 — Establish Baseline) for the detailed install/baseline flow.

1. **Install** — call `typescript_install_dependencies` (`rootDirectory`, plus each `packageDirectory` for monorepos).
2. **Compile baseline — REQUIRED.** Call `typescript_compile_package` with `rootDirectory`, `packageDirectory`, and `sessionId`. Its first invocation is auto-recorded as the workflow compile baseline.
3. **Runtime baseline — REQUIRED, do not skip, do not defer to Phase 3.** Call `typescript_validate_runtime` with `rootDirectory`, `packageDirectory`, and `sessionId`, then follow [runtime-validation.md](./runtime-validation.md). If the tool reports no plan exists, invoke the `create-eval-plan` skill immediately (do not ask the user), then re-call. Skipping this here makes the Phase 3 post-upgrade call useless — there is nothing to compare against, and the run is dropped into the `inconclusive` bucket on dashboards. This is the *same* obligation as Phase 3 step 2, at the other endpoint — baseline now, post-upgrade then. **This is enforced:** `typescript_upgrade_package_dependency_group` refuses to run (error `runtime_baseline_missing`) until this baseline call has executed.
4. **Bundler baseline** — if `validateBundlerChanges` is true and any dependency group has `containsBundlers: true`, establish a bundler build baseline via `typescript_build_package`.

All baseline measurements must complete before the first Phase 2 call. Ordering is enforced by the tools: a tool called out of order does no work and returns the call to make first, so follow that directive rather than retrying.

## Phase 2 — Upgrade (iterate per group)

After the plan is confirmed, upgrade the project's dependencies.

**Apply `applicableGuidance` — mode-driven dispatch.** You already read each entry's file in Phase 0. The list is ordered so any framework another one lists in `runAfter` comes first; process entries in that order. Act on each entry's `mode`:

- **`mode: replaces`** — the file **owns Phase 2 for its framework's packages**. Follow it step-by-step **before** TypeScript migration and the other dependency groups, and do NOT pass those packages to `typescript_upgrade_package_dependency_group`. _(Example: `angular.md` drives the upgrade via `ng update` / `nx migrate`; `@angular/*` and `@angular-devkit/*` are excluded from the standard tool.)_
- **`mode: constrains`** — the file does **not** replace the standard flow; it **constrains how its framework's dependency group is processed** within the normal `typescript_upgrade_package_dependency_group` flow (grouping rules, mandatory peers, per-major sub-files). _(Example: `react.md` keeps the React core four — `react`, `react-dom`, `@types/react`, `@types/react-dom` — together as one group and applies each `react/<major>.md` crossed.)_

When several entries apply (e.g. `react.md` and another framework on the same app), follow them in the listed order. This dispatch is list-driven — new frameworks are added to `applicableGuidance` and their files carry their own rules, so nothing here changes per framework.

**If `typeScriptMigrationNeeded` is true AND TypeScript is in scope** — the user asked to upgrade **all** packages, or explicitly named `typescript` (and Angular upgrades, if any, are already done): read [compiler-upgrade.md](../typescript-compiler-upgrade/compiler-upgrade.md) and upgrade TypeScript before other packages. For Angular projects, cap the TypeScript upgrade at TypeScript 6.

**If the user scoped the request to specific packages that do NOT include `typescript`, do NOT migrate TypeScript** even when `typeScriptMigrationNeeded` is true — upgrade only the requested packages (plus peers the user confirmed).

This bans the *TypeScript migration*, not every TS version change. If a requested package's new version genuinely cannot compile or install against the project's current `typescript` — e.g. a React bump pulls in `@types/*` whose `.d.ts` files the old compiler can't parse — bump `typescript` the minimal amount needed to clear that specific error, exactly as you'd resolve any other upgrade-induced compile error. That is not a migration. Do not use it as a pretext to run the full compiler-upgrade flow or to fix unrelated TypeScript breaking changes in the user's source. **The minimal-bump carve-out is for small gaps only.** When a requested package's required TypeScript floor is several majors above the project's current compiler — e.g. a package needs TS ≥ 5.0 but the project is on TS 3.x/4.x — a single ad-hoc jump across that many majors is itself a de-facto migration; do it through [compiler-upgrade.md](../typescript-compiler-upgrade/compiler-upgrade.md)'s structured per-major handling instead, **capped at the floor the package actually requires** (don't continue on to newer majors). That required-floor upgrade is in scope even under a package-scoped request, because the requested package cannot install or compile without it.

For each remaining dependency group (i.e. packages not owned by a `replaces`-mode guidance file, such as Angular's):

1. **Upgrade** — Read [upgrade-packages.md](./upgrade-packages.md) for instructions on calling `typescript_upgrade_package_dependency_group`.
2. **Check the result** — If the tool reports success, move to the next group. If it reports `needs_regex_fixes`, generate regex-based fixes and submit them via `typescript_verify_upgrade` (see upgrade-packages.md for details). If regex fixes don't fully resolve the errors, fall back to direct file edits and verify again.
3. **Bundler build validation** — If `validateBundlerChanges` is true and this group has `containsBundlers: true`: call `typescript_build_package` with `rootDirectory` and `packageDirectory` before moving to the next group. The tool compares against the Phase 1 baseline — a failure here means this upgrade broke the bundler build. Fix any issues before proceeding.

## Phase 3 — Validation

After all dependency groups are upgraded, run validation based on the scan results:

1. **Post-upgrade compile — REQUIRED, do not skip.** Always call `typescript_compile_package` with `rootDirectory`, `packageDirectory`, and `sessionId` — this records the post-upgrade compile-error count and lets the workflow be measured. **Even if `typescript_verify_upgrade` already reported "complete" in Phase 2, you must still call `typescript_compile_package` here**: the verify-loop only updates per-package state, and the workflow-level post-upgrade snapshot is recorded only by this tool. Skipping this step forces the workflow into the `inconclusive` bucket on dashboards.
2. **Runtime validation — REQUIRED, do not skip.** Call `typescript_validate_runtime` with `rootDirectory`, `packageDirectory`, and `sessionId`, then follow [runtime-validation.md](./runtime-validation.md). It is what catches runtime-only regressions the compiler cannot see. Skipping forces the workflow into the `inconclusive` bucket on dashboards and masks those regressions.

## Phase 4 — Summary

After all groups are upgraded:

1. Call the `typescript_write_upgrade_summary` MCP tool with `rootDirectory` and a `content` string listing which packages were successfully upgraded and which failed. Pass the same `sessionId` you've been using throughout the workflow. The tool emits the workflow/summary observation event automatically — you do NOT need to call `typescript_report_telemetry` for the workflow outcome.
2. Present the returned summary to the user.

Call `typescript_write_upgrade_summary` exactly once per workflow, and **always call it before you exit — for ANY reason**. This includes a failed upgrade, an upgrade that left new compile errors, an unrecoverable error, a repo you conclude is "not viable", or an explicit user stop. Pass `content` describing the outcome (including the failure/partial state). The tool always writes the summary and emits the workflow outcome telemetry; if new TypeScript errors remain it reports them at the top of the returned summary so you can fix or revert — it does not block the summary.

## Key Principles

1. **You are fully responsible** for gathering context and applying fixes. Use tools — never ask the user to do something a tool can do.
2. **Don't give up.** If your first approach fails, try an alternative. Exhaust all reasonable options before reporting failure.
3. **Preserve valid code.** Every change you make must produce syntactically valid TypeScript (`.ts` and `.tsx`).
4. **Work incrementally.** Upgrade and fix one dependency group at a time, verify, then move on.
5. **Run ONE tool at a time.** Wait for each MCP tool to complete before starting the next. Do NOT run multiple `typescript_upgrade_package_dependency_group` calls in parallel.
6. **Remember context.** Avoid unnecessary repetition of tool invocations with identical arguments unless required for validation or retrying fixes. Build on what you already know.
7. **Prefer minimal changes.** If editing `tsconfig.json` is simpler than rewriting application code, do that instead.
8. **When upgrading specific packages**, only upgrade what the user asked for (plus any peer dependencies they confirmed). Do not expand the scope to unrelated packages.
9. **Never run install or toolchain-repair commands yourself.** Do not shell out to `npm install`, `yarn add`, `pnpm install`, `npm ci`, etc. — these will run the wrong package manager and corrupt the project's lockfile. Do NOT run `corepack enable`/`corepack prepare`, `nvm install`, `volta install`, `asdf install`, or `npm i -g <package-manager>` to repair a missing or wrong-versioned package manager — installing toolchain binaries is out of scope for this skill. Edit `package.json` directly when you need to add/change a dependency, then call `typescript_install_dependencies` (it uses the project's declared package manager from the scan). If `typescript_install_dependencies` fails or hangs because of a toolchain issue, stop and report the blocker via `typescript_write_upgrade_summary` instead of attempting a workaround. This ban is about install and package-manager/toolchain commands — it does **not** forbid running source-transform codemods. Running `npx --yes codemod@latest react/<major>/migration-recipe --no-interactive` or `npx --yes types-react-codemod@latest preset-19 … --no-interactive` (see [react.md](./react.md)) is explicitly allowed: those rewrite source files, they don't install dependencies or repair the toolchain.
10. **Never remove a declared dependency to make a tool stop complaining.** Deleting an entry from `dependencies`/`devDependencies` is a breaking change to the project, not a fix. If a tool reports a package as broken, missing, or unresolvable, treat that as information — report it in the summary and move on. The only entries you may remove are ones the user explicitly asked you to remove.
11. **Advisories are not blockers.** A tool result marked `Advisory` succeeded; it is reporting a heuristic finding that may be a false positive. Note it, keep going, and act on it only if a later step actually fails for the reason the advisory named.