NPM 6, Peer Dependencies and Capacitor

At the end of April 2023, NPM 6 and Node.js 14 will officially transition to “end of life” status. While this should not affect Cordova users, we’ve seen many Capacitor projects struggling with dependencies from the NPM 6 era. This article will explain a bit about what’s going on with those dependencies, what you can do to update your project, and what we’re doing to support users who are unable to update.

The Problem

NPM 7 was released over two years ago and brought many changes - the most significant being a change to how peer dependencies are installed. In the context of Capacitor, plugins use peer dependencies to specify what versions of the Capacitor Core are supported.

Previous versions of NPM (v3-6) would not automatically install peer dependencies, just emit a warning and leave it up to the end user. With the release of NPM 7, peer dependencies were automatically installed. Unfortunately, many projects that were working just fine also unknowingly had dependency conflicts. Essentially, one plugin might depend on Capacitor Core v3 and another on Capacitor Core v4. This would cause NPM 7 (and later versions) to fail when installing dependencies.

We’ve seen quite a few Capacitor projects in this very position. Up until this point, many of these projects opted to stay on NPM 6 and continue using its older algorithm for installing dependencies. Starting in May this will no longer be an option, prompting the question: how do you solve this problem?

Solutions

There are two solutions to this - a quick fix and a longer more involved fix. The quick fix simply requires that you 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. However, it’s important to note that this doesn’t resolve the problem and could lead to issues as you update your plugins. This is a band-aid to keep you going in the moment and isn’t viable in the long-term.

When you’re using VoltBuilder to build your Capacitor project, you can include the --legacy-peer-deps option by adding the following to your voltbuilder.json:

"capacitor": {
  "installLegacyPeerDeps": true
}

A Long-Term Fix

The more involved fix requires an iterative approach. Essentially you attempt to run npm install, observe the error message and then upgrade the offending dependency to resolve that particular error. For example, upon installing you might notice the following error message:

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 is saying that the package @mui/material has a peer dependency of @types/react version 17 or 18. However, in our example, the package.json contains this:

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

This is the reason for the error. The solution is to update this package to version 17 or later. After each change to package.json you’ll want to run npm install once again and deal with the next error. Once you’ve resolved all the errors it’s entirely likely a few things will be broken with your project. You’ll want to run a thorough test, especially if you’ve updated many dependencies.

While this approach takes more time in the long run, it will leave your project in a more maintainable state and you’ll have fewer dependency issues in the future.

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

What VoltBuilder does

To start testing your app right away check out VoltBuilder!

VoltBuilder is a wrapper for Apache Cordova and Ionic Capacitor. We make it easy for you to build native executables (e.g., .apk, .aab, and .ipa) for Android and iOS from web apps. You can augment these executables with native code plugins to extend your app’s capabilities far beyond what is possible in Web Apps and PWAs.

Using VoltBuilder simplifies and speeds up your workflow while keeping things framework neutral. As a web service, there is nothing you need to install. We also keep everything up to date so you can focus on building to the latest standards, and make sure to keep you in the loop on things that might affect your build process.

The way VoltBuilder works is simple. Zip your project, upload it to VoltBuilder, and download your Android or iOS executable.

Getting Started With VoltBuilder

If you haven’t already, sign up and select the VoltBuilder plan that best fits your needs and budget. You can use the Free plan for limited testing, or get more builds by trying out our Indy or Pro plans with a 15 day free trial!

Then, check out our Docs Section to learn how to integrate VoltBuilder into your development process.

When you’re ready to upload your first project, watch our video tutorial (or read the tutorial in our docs). The Docs section has plenty of other helpful resources, like Migration Guides, sample projects, and tips to get you started! If you need extra help, stop by our Support Forum!