# Do You Need to Manually Update Dependencies When Upgrading React?

> Learn whether to manually update dependencies when upgrading React. Discover how npm handles version strings and understand the best approach for synchronization.

- Repository: [Meta/react](https://github.com/facebook/react)
- Tags: how-to-guide
- Published: 2026-02-18

---

**No, npm does not automatically update dependency version strings in your [`package.json`](https://github.com/facebook/react/blob/main/package.json) files when upgrading React; you must either manually edit the version fields or use React's official release automation scripts to synchronize inter-package dependencies.**

When working with the `facebook/react` repository—a monorepo managed via Yarn workspaces—upgrading React requires careful coordination across multiple [`package.json`](https://github.com/facebook/react/blob/main/package.json) files. While npm and Yarn install the versions you declare, they do not automatically rewrite those declarations when you perform a repository upgrade. This guide explains how to properly update dependencies when upgrading React, whether through manual editing or the automated release scripts provided in the repository.

## How React's Monorepo Structures Dependencies

The React codebase organizes code as a monorepo with a root [`package.json`](https://github.com/facebook/react/blob/main/package.json) and individual packages nested under the `packages/` directory.

### Root vs. Package-Level Dependencies

The root [`package.json`](https://github.com/facebook/react/blob/main/package.json) declares the workspace layout and development dependencies required for building and testing the entire repository (see lines 3‑5 in the root [`package.json`](https://github.com/facebook/react/blob/main/package.json)). These **dev-dependencies** include build tools, test runners, and linting utilities that apply to the whole monorepo but are not shipped to end users.

In contrast, each published package maintains its own [`package.json`](https://github.com/facebook/react/blob/main/package.json) within the `packages/` directory. For example, [`packages/react/package.json`](https://github.com/facebook/react/blob/main/packages/react/package.json) defines React's public API and version (line 7), while [`packages/react-dom/package.json`](https://github.com/facebook/react/blob/main/packages/react-dom/package.json) contains the renderer-specific configuration.

### Inter-Package Dependencies and Peer Dependencies

Individual packages declare their relationships through two critical fields:

- **`dependencies`**: Runtime requirements between packages. For instance, `react-dom` depends on `scheduler`, as shown in [`packages/react-dom/package.json`](https://github.com/facebook/react/blob/main/packages/react-dom/package.json) lines 19‑22.
- **`peerDependencies`**: Compatibility constraints on the React version expected. The `react-dom` package declares `react` as a peer dependency in lines 36‑41 of its [`package.json`](https://github.com/facebook/react/blob/main/package.json), ensuring the renderer matches the core library version.

When you upgrade React, these version strings must remain synchronized across all packages. If `react` bumps to `19.3.0`, `react-dom` must update its `peerDependencies` to require `^19.3.0` and its own `version` field must reflect the new release.

## Why npm Does Not Automatically Update Dependencies

Package managers like npm and Yarn resolve and install the versions declared in your [`package.json`](https://github.com/facebook/react/blob/main/package.json) files, but they **do not** automatically rewrite those declarations when you perform a repository upgrade.

When you run `npm update` or `yarn upgrade`, the package manager consults the existing version ranges and installs the latest compatible versions within those ranges. However, the actual strings in [`package.json`](https://github.com/facebook/react/blob/main/package.json)—such as `"react": "^19.2.0"`—remain unchanged unless you explicitly modify them or use a helper script.

In the context of the React monorepo, this means that bumping the version in [`packages/react/package.json`](https://github.com/facebook/react/blob/main/packages/react/package.json) does not cascade to [`packages/react-dom/package.json`](https://github.com/facebook/react/blob/main/packages/react-dom/package.json) or other dependent packages. You must explicitly update the `version`, `dependencies`, and `peerDependencies` fields to reflect the new release.

## Two Methods to Update Dependencies When Upgrading React

React maintainers use two primary approaches to synchronize version numbers across the monorepo: manual editing or the official release automation scripts.

### Manual Editing of package.json Files

You can manually update each package's metadata by editing the relevant [`package.json`](https://github.com/facebook/react/blob/main/package.json) files directly:

1. Update the `version` field in [`packages/react/package.json`](https://github.com/facebook/react/blob/main/packages/react/package.json) (line 7) to the new release number (e.g., `19.3.0`).
2. Update the `version` field in [`packages/react-dom/package.json`](https://github.com/facebook/react/blob/main/packages/react-dom/package.json) and other packages accordingly.
3. Modify the `peerDependencies` in dependent packages (e.g., lines 36‑41 in [`packages/react-dom/package.json`](https://github.com/facebook/react/blob/main/packages/react-dom/package.json)) to require the new React version.
4. Update any `dependencies` between packages (e.g., `scheduler` references in `react-dom`) to ensure they match the new release.

While straightforward for small patches, this approach becomes error-prone across React's many packages (`react`, `react-dom`, `react-reconciler`, `scheduler`, etc.).

### Using the Official Release Automation Script

The React team provides an automated solution via [`scripts/release/prepare-release-from-npm.js`](https://github.com/facebook/react/blob/main/scripts/release/prepare-release-from-npm.js). This script orchestrates the promotion of a "next" build to a stable release while automatically updating all version strings.

The script executes the following workflow (starting at line 44):

1. **`getLatestNextVersion`**: Retrieves the most recent "next" build from npm.
2. **`guessStableVersionNumbers`**: Generates proposed stable version numbers based on the next build.
3. **`confirmStableVersionNumbers`**: Prompts the maintainer to confirm or adjust the proposed versions.
4. **`updateStableVersionNumbers`**: Writes the confirmed version numbers back to every [`package.json`](https://github.com/facebook/react/blob/main/package.json) in the monorepo, including all `dependencies` and `peerDependencies`.

To execute the automation:

```bash

# From the repository root

node scripts/release/prepare-release-from-npm.js --version=19.3.0

```

This approach ensures that [`packages/react/package.json`](https://github.com/facebook/react/blob/main/packages/react/package.json), [`packages/react-dom/package.json`](https://github.com/facebook/react/blob/main/packages/react-dom/package.json), and all other packages receive synchronized version bumps without manual editing.

## Validating Dependency Consistency

After updating versions—whether manually or via script—you should verify that all inter-package dependencies remain consistent. React provides a validation utility at [`scripts/release/check-release-dependencies.js`](https://github.com/facebook/react/blob/main/scripts/release/check-release-dependencies.js).

This script contains a `checkDependency` function (lines 48‑55) that validates every intra-repo dependency satisfies the expected semver range. If any package references an outdated version of another monorepo package, the script throws an error and halts the release process.

Run the validation:

```bash
node scripts/release/check-release-dependencies.js

```

This safety check prevents publishing packages with mismatched dependencies, ensuring that `react-dom` always declares compatible `peerDependencies` on the corresponding `react` version.

## Summary

- **npm does not automatically update** the version strings in [`package.json`](https://github.com/facebook/react/blob/main/package.json) files when you upgrade React; it only installs the versions already declared.
- React's monorepo structure requires synchronizing versions across multiple packages (`react`, `react-dom`, `scheduler`, etc.) including both `dependencies` and `peerDependencies`.
- You have two options for updating: **manual editing** of each [`package.json`](https://github.com/facebook/react/blob/main/package.json) or using the **automated release script** at [`scripts/release/prepare-release-from-npm.js`](https://github.com/facebook/react/blob/main/scripts/release/prepare-release-from-npm.js).
- Always run [`scripts/release/check-release-dependencies.js`](https://github.com/facebook/react/blob/main/scripts/release/check-release-dependencies.js) to validate that all inter-package version ranges are consistent before publishing.

## Frequently Asked Questions

### Does npm update package.json automatically when I run npm update?

No, npm installs the latest versions that satisfy the existing ranges in your [`package.json`](https://github.com/facebook/react/blob/main/package.json), but it does not automatically rewrite those version strings to reflect newer releases. The [`package.json`](https://github.com/facebook/react/blob/main/package.json) file remains unchanged unless you manually edit it or use a release automation script like [`prepare-release-from-npm.js`](https://github.com/facebook/react/blob/main/prepare-release-from-npm.js) in the React repository.

### What happens if I forget to update peerDependencies when upgrading React?

If you forget to update `peerDependencies` in packages like `react-dom`, npm will issue warnings or errors when users try to install the packages, indicating that the required React version is missing or incompatible. In the React monorepo, the [`check-release-dependencies.js`](https://github.com/facebook/react/blob/main/check-release-dependencies.js) script catches these mismatches by validating that all `peerDependencies` satisfy the expected semver ranges before any release is published.

### Can I use npm instead of Yarn for React's release scripts?

While the React monorepo uses Yarn workspaces for dependency management as defined in the root [`package.json`](https://github.com/facebook/react/blob/main/package.json), the release scripts themselves are Node.js scripts that can be executed directly. However, the underlying package management during the release process assumes the Yarn workspaces structure. For consistency with the React team's workflow, Yarn is recommended, but the scripts at [`scripts/release/prepare-release-from-npm.js`](https://github.com/facebook/react/blob/main/scripts/release/prepare-release-from-npm.js) do not strictly require the `yarn` CLI to run.

### How does React ensure all packages stay in sync during a release?

React ensures synchronization through the [`prepare-release-from-npm.js`](https://github.com/facebook/react/blob/main/prepare-release-from-npm.js) automation script, which updates the `version`, `dependencies`, and `peerDependencies` fields across all packages simultaneously. This script uses helper functions—`getLatestNextVersion`, `guessStableVersionNumbers`, `confirmStableVersionNumbers`, and `updateStableVersionNumbers`—to orchestrate the version bump consistently. Afterward, [`check-release-dependencies.js`](https://github.com/facebook/react/blob/main/check-release-dependencies.js) validates that every intra-repo dependency matches the expected ranges, preventing mismatched releases.