Updating Dependencies Without Breaking Your Next.js App

Updating every package to its newest version can produce a reassuringly modern manifest and an unexpectedly fragile toolchain. A framework, its lint configuration, the parser, and the compiler can each be current without supporting one another.

A useful upgrade process checks the relationships between packages, then verifies the application behavior those packages support. The install command is only the beginning.

Record the working baseline

Before changing versions, inspect the working tree and identify any existing edits. Keep the current lockfile and run the available checks so you know which failures already existed.

Note the Node version, package manager version, and deployment environment. Local success under one runtime is weaker evidence when CI or hosting uses another.

For this portfolio, the relevant baseline includes Node 24 in CI, pnpm declared in packageManager, and separate commands for lint, formatting, and the production build. Those are concrete inputs to an upgrade decision, not incidental setup details.

Read the compatibility graph

Next.js is only one participant. React and React DOM should be aligned, and framework packages such as @next/mdx and eslint-config-next should match the intended Next.js release.

Inspect peer dependency ranges for the tooling underneath them too. A top-level configuration package can accept a broad ESLint range while one of its plugins excludes a newer major.

TypeScript support also belongs to the parser and lint toolchain, not just the framework. The typescript-eslint compatibility reference is useful for checking its currently supported versions. Read the installed package manifests as well, since an online guide can describe a newer release than the one in your lockfile.

Prefer a supported combination over a version contest

When a major upgrade falls outside a peer range, first look for an upstream release that supports it. If that does not exist, keep the affected package on a compatible version and document the constraint.

Do not hide the problem with force flags or peer-dependency overrides just to make installation quiet. Those options change enforcement; they do not prove the APIs still fit together.

A successful lint run is useful evidence, but one execution cannot exercise every rule and file shape. Declared support and observed behavior answer different questions, and a responsible upgrade considers both.

Let pnpm update the lockfile

Edit the intended dependency versions, then let the package manager resolve and record the resulting graph. Avoid manually reconstructing dependency entries or discarding an unrelated developer's lockfile work.

A useful verification sequence is:

pnpm install --strict-peer-dependencies
pnpm install --frozen-lockfile
pnpm audit
pnpm lint
pnpm format:check
pnpm build

The strict install checks the resolved peer relationships. The frozen install verifies that the committed inputs are sufficient without another resolution change. pnpm documents these installation modes in its CLI reference.

Inspect the diff afterward. If a small intended update changes hundreds of unrelated packages, understand why before accepting the result. A lockfile can change significantly for legitimate reasons, but the size of the diff is still a useful review signal.

Investigate warnings as migration clues

A build warning can identify a configuration that still works but is being retired. Do not suppress it automatically or assume a successful exit means the upgrade is finished.

For example, older Open Graph image implementations may explicitly select the Edge Runtime. Current Next.js guidance recommends the default Node.js runtime instead. Removing the obsolete selection can also let eligible image routes prerender statically.

Check the documentation bundled with the installed Next.js version before applying a migration from memory. Keep the fix focused on the deprecated behavior rather than redesigning the surrounding feature during the upgrade.

Test what compilation cannot prove

Start the production server and visit representative routes. Include dynamic pages, MDX content, authentication entry points, feeds, and generated images if the application uses them.

For an image endpoint, check actual PNG bytes and dimensions rather than stopping at HTTP 200. For authentication, distinguish an unauthenticated-session smoke test from a complete OAuth round trip. State that limitation in the verification notes.

Keep security audit findings separate from compatibility failures. A narrow transitive override can be appropriate when a patched compatible release exists, but document why it is needed and when to remove it.

Finish by updating the project instructions to match the verified toolchain. The next upgrade becomes easier when the repository explains its constraints instead of leaving them to be rediscovered.