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

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!