docs: describe some troubleshooting steps for dependency issues (#147)

* docs: describe some troubleshooting steps for dependency issues

* docs: update react_native_3_create_credentials.md

* docs: update node_setup_identifiers.md

* docs: add a troubleshooting guide

docs/node_tutorials/node_setup_identifiers.md

@@ -8,9 +8,11 @@ This guide covers setting up an agent and creating identifiers in Node.
 
 #### Note
 
-A finished example of this tutorial can be found on github at [https://github.com/veramolabs/veramo-nodejs-tutorial](https://github.com/veramolabs/veramo-nodejs-tutorial)
+A finished example of this tutorial can be found on GitHub
+at [https://github.com/veramolabs/veramo-nodejs-tutorial](https://github.com/veramolabs/veramo-nodejs-tutorial)
 
-This tutorial has been updated to reflect the switch to ESM. Please take care to ensure you use proper ESM syntax in imports and commands. Also please carefully note `package.json` and `tsconfig.json`.
+This tutorial has been updated to reflect the switch to ESM. Please take care to ensure you use proper ESM syntax in
+imports and commands. Also, please carefully note `package.json` and `tsconfig.json`.
 
 Additional info regarding ESM can be found at the following links:
 [https://www.typescriptlang.org/docs/handbook/esm-node.html](https://www.typescriptlang.org/docs/handbook/esm-node.html)
@@ -19,8 +21,8 @@ Additional info regarding ESM can be found at the following links:
 
 ### Prerequisites
 
-You need to have Node v14 or later installed. In this example, we use yarn as the package manager, but you can also use
-npm.
+You need to have Node v14 or later installed. In this example, we use `yarn` as the package manager, but you can also
+use `npm`.
 
 Start by creating a directory for our project and initializing the npm package.
 
@@ -43,10 +45,12 @@ Install dev dependencies
 yarn add typescript ts-node --dev
 ```
 
+> ℹ️ **Note:** In case you run into issues check out the [Troubleshooting](../troubleshooting.md) page for some options.
+
 Install Veramo core and plugins
 
 ```bash
-yarn add @veramo/core @veramo/credential-w3c @veramo/data-store @veramo/did-manager @veramo/did-provider-ethr @veramo/did-resolver @veramo/key-manager @veramo/kms-local ethr-did-resolver web-did-resolver did-resolver
+yarn add @veramo/core @veramo/credential-w3c @veramo/data-store @veramo/did-manager @veramo/did-provider-ethr @veramo/did-resolver @veramo/key-manager @veramo/kms-local ethr-did-resolver web-did-resolver
 ```
 
 Install `sqlite`
@@ -80,7 +84,8 @@ Add a tsconfig.json to your project
 
 ## Bootstrap Veramo
 
-We bootstrap Veramo by creating a setup file and initializing the agent. Create a setup file in `src/veramo/setup.ts` and import the following dependencies:
+We bootstrap Veramo by creating a setup file and initializing the agent. Create a setup file in `src/veramo/setup.ts`
+and import the following dependencies:
 
 Note: In this file we'll use that secret key that we generated in an earlier step, so have it handy.
 
@@ -189,22 +194,25 @@ export const agent = createAgent<
 
 > **Note:**
 >
-> The types you specify for agent creation are optional, but may be very helpful when writing TypeScript, as long as they
+> The types you specify for agent creation are optional, but may be very helpful when writing TypeScript, as long as
+> they
 > match the plugins that you add to the agent.
 >
 > ```typescript
 > <IDIDManager & IKeyManager & IDataStore & IDataStoreORM & IResolver & ICredentialPlugin>
 > ```
 >
-> These types help the typescript compiler to figure out what plugin methods get exposed by the agent and what parameters
+> These types help the typescript compiler to figure out what plugin methods get exposed by the agent and what
+> parameters
 > those methods require. These types are also very helpful for development in VSCode, or other IDEs that provide
 > auto-complete.
 
 That's one possible agent setup. Let's use it to create and list identifiers.
 
 ## App Logic
 
-Create 4 files `./src/create-identifier.ts`, `./src/list-identifiers.ts`, `./src/create-credential.ts` and `./src/verify-credential.ts`
+Create 4 files `./src/create-identifier.ts`, `./src/list-identifiers.ts`, `./src/create-credential.ts`
+and `./src/verify-credential.ts`
 
 Add the following code to `./src/list-identifiers.ts`
 

docs/react_native_tutorials/react_native_3_create_credentials.md

@@ -9,7 +9,13 @@ sidebar_label: Create Credentials
 The veramo list of "core" packages contains a W3C Credential plugin. This plugin allows us to
 create and verify credentials with JWT proof type.
 
-`npm install @veramo/credential-w3c`
+Now add the credential package:
+
+```bash
+npm install @veramo/credential-w3c`
+```
+
+> ℹ️ **Note:** In case you run into issues check out the [Troubleshooting](../troubleshooting.md) page for some options.
 
 ## Setup
 

docs/react_tutorials/react_setup_resolver.md

@@ -5,13 +5,15 @@ sidebar_label: Setup & Resolver
 ---
 
 Veramo core runs natively in the browser. The plugins you use also need to be browser compatible. This guide will set up
-a DID resolver to work in an application created with [Create React App](https://create-react-app.dev/) but uses [CRACO](https://craco.js.org/)
+a DID resolver to work in an application created with [Create React App](https://create-react-app.dev/) but
+uses [CRACO](https://craco.js.org/)
 to allow use of babel config required for ESM.
 It is possible to add your own identity, key management, and storage plugins that are browser compatible.
 
 #### Note
 
-A finished example of this tutorial can be found on github at [https://github.com/veramolabs/veramo-react-app-tutorial](https://github.com/veramolabs/veramo-react-app-tutorial)
+A finished example of this tutorial can be found on github
+at [https://github.com/veramolabs/veramo-react-app-tutorial](https://github.com/veramolabs/veramo-react-app-tutorial)
 
 ### Initialize app
 
@@ -85,17 +87,17 @@ Open `src/App.css` and add the following styles to the top of the file:
 
 ```css
 pre {
-  font-family: monospace;
-  white-space: pre;
+    font-family: monospace;
+    white-space: pre;
 }
 
 #result {
-  text-align: left;
-  width: 900px;
-  background-color: #24232d;
-  color: #25c2a0;
-  padding: 15px;
-  overflow: scroll;
+    text-align: left;
+    width: 900px;
+    background-color: #24232d;
+    color: #25c2a0;
+    padding: 15px;
+    overflow: scroll;
 }
 ```
 
@@ -138,6 +140,8 @@ And that's it! When you `yarn start` you should see a DID document being resolve
 
 ## Troubleshooting
 
+### Outdated templates
+
 If after running `create-react-app`, you see the following message:
 
 ```
@@ -146,6 +150,28 @@ Please note that global installs of create-react-app are no longer supported.
 You can fix this by running npm uninstall -g create-react-app or yarn global remove create-react-app before using create-react-app again.
 ```
 
+Errors
+
 Be sure to follow the instructions in that message, and then run the `npx` command again. If you still the
-message, [this answer may help](https://stackoverflow.com/questions/59188624/template-not-provided-using-create-react-app)
-.
+message, [this answer may help](https://stackoverflow.com/questions/59188624/template-not-provided-using-create-react-app).
+
+### Dependency issues
+
+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` block to your `package.json` file and replacing the problematic dependencies:
+
+```json5
+// filename: package.json
+{
+  // ...
+  "resolutions": {
+    "jsonld": "npm:@digitalcredentials/jsonld@^6.0.0"
+  }
+}
+```
+
+Take a look at the [`Troubleshooting page`](../troubleshooting.md) for additional options.

docs/troubleshooting.md

@@ -0,0 +1,69 @@
+---
+id: troubleshooting
+title: Troubleshooting
+sidebar_label: 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](https://medium.com/veramo/veramo-is-switching-to-esm-and-pnpm-57cf8e841ffa) for details.
+
+Additional info regarding ESM can be found at the following links:
+
+* [https://www.typescriptlang.org/docs/handbook/esm-node.html](https://www.typescriptlang.org/docs/handbook/esm-node.html)
+* [https://nodejs.org/api/esm.html](https://nodejs.org/api/esm.html)
+* [https://caniuse.com/?search=modules](https://caniuse.com/?search=modules)
+
+### 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:
+
+```json5
+// filename: package.json
+{
+  // ...
+  "resolutions": {
+    "jsonld": "npm:@digitalcredentials/jsonld@^6.0.0"
+  }
+}
+```
+
+Different package managers use different configurations for such overrides:
+* [npm overrides](https://docs.npmjs.com/cli/v10/configuring-npm/package-json#overrides)
+* [yarn v2+ resolutions](https://yarnpkg.com/configuration/manifest#resolutions)
+* [yarn v1 resolutions](https://classic.yarnpkg.com/lang/en/docs/selective-version-resolutions/)
+* [pnpm resolutions](https://pnpm.io/package_json#resolutions)
+
+See [this issue for more details](https://github.com/decentralized-identity/veramo/issues/1407)
+
+### Expo apps
+
+If your project is a react-native app, then you will also benefit from replacing `isomorphic-webcrypto` with the [fork
+made by Sphereon](https://github.com/Sphereon-Opensource/isomorphic-webcrypto):
+
+```json5
+// filename: package.json
+{
+  // ...
+  "resolutions": {
+    "isomorphic-webcrypto": "npm:@sphereon/isomorphic-webcrypto@^2.4.0"
+  }
+}
+```

sidebars.js

@@ -83,6 +83,7 @@ module.exports = {
         'community/contributing',
       ],
     },
+    'troubleshooting'
     // {
     //   type: 'category',
     //   label: 'Resources',