Overview

Most Profound.js upgrades are a straightforward npm install followed by node complete_install.js (see Upgrade Process). This page covers the two situations where that is not enough and the local npm package store has to be cleared first:

Upgrading past 7.31.2 - A one-time cleanup is required the first time you upgrade from an earlier release;
A corrupted node_modules directory - Rare, but it produces npm errors that a clean install resolves.

Deprecated Transitive Dependencies

Profound Logic’s approach to eliminating the npm WARN deprecated warnings may require clearing packages in node_modules and the package-lock.json. These deprecation warnings often come from transitive dependencies – indirect dependencies – which in many cases cannot be avoided simply by choosing a newer version of a package that Profound.js depends on directly.

The solution for avoiding some of these deprecated packages is:

Profound Logic publishes shims – the minimum parts of those packages that Profound.js needs;
Those packages are hardened and updated as needed;
The Profound.js package.json uses npm aliases so that the Profound Logic versions are installed and used in place of the deprecated, abandoned, or outdated originals.

Special Release Notes for Profound.js 7.31.2 and 7.32.0

These two releases replace Profound.js’s two deprecated transitive dependencies — jpeg-exif and node-domexception — with shims maintained by Profound Logic (@profoundlogic/jpeg-exif and @profoundlogic/node-domexception), consumed through npm aliases. This eliminates the deprecated npm WARN deprecated noise during install, and resolves the Arborist null target crash some customers hit when upgrading past 7.30.0.

Upgrade Instructions

If you are upgrading from any earlier release (7.31.1 or older), run a clean install in your Profound.js instance directory the first time you upgrade to 7.31.2 or higher:

rm -rf node_modules package-lock.json
npm install profoundjs@latest

Deleting package-lock.json removes the record of exactly which versions are installed, and @latest is a floating tag. After a clean install:

Run node complete_install.js so the IBM i Connector library is brought up to the version npm just installed. Skipping this leaves the two halves mismatched and requests from IBM i fail with Version Mismatch (PJS0014);
Check what was actually installed with npm list profoundjs, and pin it with npm install --save-exact profoundjs@<version> if this instance is meant to stay on a fixed release.

The cleanup step is only required the first time you upgrade from below 7.31.2 to at or above it. Subsequent in-place upgrades work normally without any manual cleanup – for example, upgrading 7.32.0 to 7.33.0 does not require a fresh installation.

If you are currently on Profound.js 7.30.0, 7.31.0, or 7.31.1, the cleanup step is especially important. Without it, the upgrade itself may fail with Cannot destructure property 'package' of 'node.target' as it is null.

A fresh npm install – with no prior install in the directory – does not require any special steps.

If You Depend on jpeg-exif

If your project’s package.json depends on jpeg-exif for more than what the shim provides – either directly or transitively – no extra step is needed to keep using that package. npm will choose the actual, deprecated jpeg-exif package over the alias that Profound.js uses.

Minimum Files to Clear

If removing all of node_modules is problematic – for example if you installed Profound.js globally – the following is the minimum that must be cleared before upgrading to Profound.js 7.31.2 or 7.32.0:

# First cd into your Profound.js installation directory, then:
rm -fr package-lock.json \
  node_modules/jpeg-exif/ \
  node_modules/node-domexception/ \
  node_modules/profoundjs

Problems With Packages

Apart from the situations described above, you should normally be able to upgrade your Profound.js instance by following Upgrade Process.

Rarely, however, the node_modules package store installed with Profound.js – the node_modules subdirectory of your Profound.js installation directory – can become corrupted. In that case, the installation can be repaired by removing the package store and reinstalling. From a shell such as Bash, in the Profound.js installation directory:

rm -fr ./node_modules package-lock.json
npm i profoundjs@latest

Follow this with node complete_install.js before restarting the instance, and re-pin the version if this instance is meant to stay on a fixed release (see Installation Process).

Clearing node_modules and package-lock.json causes the npm i command to cleanly install all packages, rather than skipping any that appear to be installed already and that meet the minimum required version in the dependency tree.

Run node complete_install.js after any of these reinstalls to complete the installation (see Installation Process).