Veramo is Switching to ESM (and pnpm)

There are 2 major module formats in use within the Node.js ecosystem: CommonJS Modules and ESM (an acronym for EcmaScript Modules). CommonJS was the system that was developed originally to support modules within Node.js but it has some drawbacks. ESM is a newer, well-specified standard for modules in Node.js.

While it is possible to build a project that builds both CommonJS and ESM modules, so that it can be easily used in all other projects, this creates a large maintenance risk as well.

To avoid this risk, several projects are switching to “pure ESM” (notably all JS libraries from IPFS / Libp2p). This means that they drop compatibility with the somewhat-deprecated CommonJS format in order to focus on providing more functionality for their developer users.

It is technically still possible to use pure ESM modules within a CommonJS module via “dynamic imports”, but it is often difficult to do so cleanly, as it involves refactoring an import to function asynchronously. You can learn more about dynamic imports here: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/import

Veramo has made the same choice to move to “pure ESM”. We are switching from producing CommonJS Modules to ESM in order to focus on expanding our functionality and integrating cutting-edge technologies (e.g. libp2p).

Version 5.0.0 of Veramo (scheduled to be released Jan 30, 2023) will include a breaking change as we switch to ESM.

Like most Typescript projects, we were already making use of ES syntax (which would then be transpiled into CommonJS by Typescript) in most of our projects, making our upgrade relatively easy. All we had to do was:

• Update `package.json` to include `”type”: “module”` and correct `exports` field
• Refactor all `require` statements to use `import`
• Refactor all relative-path import statements to include `.js` file extension
• Update Babel Configuration in React to support “import assertions”

There are a few other minor changes related to our testing flow (in particular our use of the package `jest-puppeteer`, which currently has a bug related to Node.js version 18), but they are not particularly important.

If you want to see the Pull Request that enables ESM in Veramo, you can find it here: https://github.com/uport-project/veramo/pull/1103

Our documentation (and example projects) for using Veramo in Node.js, React and React Native have all been updated to reflect the small changes required to switch these projects to use ESM.

At the same time, we have decided to switch our package manager from `yarn` to `pnpm`. We were noticing that `yarn` was having some issues with certain dependencies, leading to issues such as https://github.com/uport-project/veramo/issues/1098 and switching to `pnpm` resolved those problems.

We hope that this release does not cause significant problems for our developer community, but if you have any issues, please reach out to us either through our GitHub repo or on our Discord.