Skip to main content

Troubleshooting

Veramo is a toolbox that can be used in an uncountable number of ways. This is fantastic! But, it also means that things can go wrong in ways that can be surprising.

You can mix and match plugins depending on needs, but for most Verifiable Credential workflows you will most likely use most packages present in the Veramo repository. That also means a lot of dependencies, and setting up a Veramo deployment with all the bells and whistles may put your project in a conflicting state, or some of your dependencies may refuse to install. Other times, issues may arise at runtime due to the wrong dependency getting resolved and bundled.

Dependency issues​

ESM vs CommonJS​

We have adopted ESM syntax for the Veramo codebase, mostly because of dependencies that we use that have taken a "pure ESM" stance. See this article for details.

Additional info regarding ESM can be found at the following links:

The jsonld ecosystem​

Some of the Veramo packages that have to do with Verifiable Credentials (like @veramo/credential-ld) depend on a set of libraries from the jsonld ecosystem which weren't designed with the same multi-platform targets in mind. Forks of these dependencies exist, that work in all environments where Veramo should work, but you have to aid your package manager in finding them.

The solution is to add a resolutions (or overrides) block to your package.json file and replacing the problematic dependencies:

// filename: package.json
{
  // ...
  "resolutions": {
    "jsonld": "npm:@digitalcredentials/jsonld@^6.0.0"
  }
}

Different package managers use different configurations for such overrides:

See this issue for more details

React Native / Expo apps​

If your project is a react-native app, then you will also benefit from replacing isomorphic-webcrypto with the fork maintained by Sphereon:

// filename: package.json
{
  // ...
  "resolutions": {
    "isomorphic-webcrypto": "npm:@sphereon/isomorphic-webcrypto@^2.4.0"
  }
}

Example React Native open-source production apps using Veramo​

Checkout the following projects to see how they have successfully configured their production-level React Native apps using Veramo: