From cbc3b7d772b02f11a5a145c2de4f9944d7d8297d Mon Sep 17 00:00:00 2001 From: Mircea Nistor Date: Thu, 1 Aug 2024 17:27:43 +0200 Subject: [PATCH] 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 | 26 ++++--- .../react_native_3_create_credentials.md | 8 ++- docs/react_tutorials/react_setup_resolver.md | 50 ++++++++++---- docs/troubleshooting.md | 69 +++++++++++++++++++ sidebars.js | 1 + 5 files changed, 132 insertions(+), 22 deletions(-) create mode 100644 docs/troubleshooting.md diff --git a/docs/node_tutorials/node_setup_identifiers.md b/docs/node_tutorials/node_setup_identifiers.md index 10cd7b56..60359b67 100644 --- a/docs/node_tutorials/node_setup_identifiers.md +++ b/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,14 +194,16 @@ 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 > > ``` > -> 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. @@ -204,7 +211,8 @@ 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` diff --git a/docs/react_native_tutorials/react_native_3_create_credentials.md b/docs/react_native_tutorials/react_native_3_create_credentials.md index d0032d64..9c32567f 100644 --- a/docs/react_native_tutorials/react_native_3_create_credentials.md +++ b/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 diff --git a/docs/react_tutorials/react_setup_resolver.md b/docs/react_tutorials/react_setup_resolver.md index baf07978..0fabe65d 100644 --- a/docs/react_tutorials/react_setup_resolver.md +++ b/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. diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md new file mode 100644 index 00000000..b277c006 --- /dev/null +++ b/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" + } +} +``` diff --git a/sidebars.js b/sidebars.js index 4d6f7323..4f5f72fe 100644 --- a/sidebars.js +++ b/sidebars.js @@ -83,6 +83,7 @@ module.exports = { 'community/contributing', ], }, + 'troubleshooting' // { // type: 'category', // label: 'Resources',