NPM 6, Peer Dependencies and Capacitor

At the end of April 2023, NPM 6 and Node.js 14 will transition to “end of life” status. This should not affect Cordova projects, but Capacitor projects may experience dependency issues. In this article, we explain the dependency issues and how to update your project. We also discuss how we’re supporting users who can’t update their projects.

The Problem

NPM 7 differs from NPM 6 in how peer dependencies get installed. In previous versions (v3-6), NPM prompted users to install peer dependencies themselves. NPM 7 and later versions install peer dependencies automatically.

In the context of Capacitor, plugins use peer dependencies to specify supported versions of the Capacitor Core. Many projects that work fine have unknown dependency conflicts. One plugin might depend on Capacitor Core v3, another on Capacitor Core v4. These conflicts cause NPM 7 (and later versions) to fail when installing dependencies.

We’ve seen quite a few Capacitor projects in this very position. Until now, many projects opted to stay on NPM 6 to avoid this issue. Starting in May, this will no longer be an option, leaving many of you wondering: how do we solve this problem?

Solutions

There are two solutions to this problem: a quick fix and a long-term solution. The quick fix is simple, but does not resolve the problem and may lead to more issues as you update plugins. The long-term solution solves the problem, but takes more time and effort.

A Short Term Fix

The quick fix is to include –legacy-peer-deps when you are installing using a recent version of NPM. For example: npm install --legacy-peer-deps. This will use the older NPM 6 style peer dependency resolution algorithm.

To use this solution in VoltBuilder, add the following to your voltbuilder.json:

"capacitor": {
  "installLegacyPeerDeps": true
}

A Long-Term Fix

The long-term fix is iterative. First, run npm install. When it fails, read the error message. Then, upgrade the offending dependency. Repeat until the install succeeds.

An example

After running npm install, you see the following error:

npm ERR! Conflicting peer dependency: @types/react@18.0.35
npm ERR! node_modules/@types/react
npm ERR!   peerOptional @types/react@"^17.0.0 || ^18.0.0" from @mui/material@5.11.14
npm ERR!   node_modules/@mui/material
npm ERR!     @mui/material@"^5.11.13" from the root project

This error means that the package @mui/material has a peer dependency of @types/react version 17 or 18. You check your package.json and see this:

"@types/react": "^16.14.35",

To resolve this error, you update the @types/react package to version 17 or later. Continue running npm install and resolving errors until the install runs successfully.

As a final step, run a thorough test to check if anything in your project is broken. This is especially important if you’ve updated many dependencies.

This approach takes more time, but leaves your project in a more maintainable state and reduces future dependency issues.

If you get stuck, you can always contact VoltBuilder Support and we’ll do our best to get you building again!

What VoltBuilder Does

VoltBuilder converts your web projects into native Android and iOS apps. VoltBuilder is a wrapper for Apache Cordova and Ionic Capacitor, so you can add native features to your apps via Cordova and Capacitor plugins.

VoltBuilder's Key features:

Produces native executables — for easy testing & app store publishing.
Publish in minutes — VoltBuilder uploads directly to Google Play and the Apple App Store.
Easily generate certificates — VoltSigner makes Android and iOS certificates. No Mac needed!
Nothing to install — just head to the Uploads page to get building.
Nothing to store — we don't keep your passwords, certs, or code in our cloud.
Always up-to-date — we install and maintain the latest SDKs and tooling so you don't have to.