Do You Need to Manually Update Dependencies When Upgrading React?

No, npm does not automatically update dependency version strings in your 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 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 and individual packages nested under the packages/ directory.

Root vs. Package-Level Dependencies

The root 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). 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 within the packages/ directory. For example, packages/react/package.json defines React's public API and version (line 7), while 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 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, 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 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—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 does not cascade to 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 files directly:

1. Update the version field in 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 and other packages accordingly.
3. Modify the peerDependencies in dependent packages (e.g., lines 36‑41 in 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. 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 in the monorepo, including all dependencies and peerDependencies.

To execute the automation:

# From the repository root

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

This approach ensures that packages/react/package.json, 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.

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:

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 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 or using the automated release script at scripts/release/prepare-release-from-npm.js.
• Always run 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, but it does not automatically rewrite those version strings to reflect newer releases. The package.json file remains unchanged unless you manually edit it or use a release automation script like 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 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, 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 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 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 validates that every intra-repo dependency matches the expected ranges, preventing mismatched releases.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}