From 91f1552a8892bea98de0fefc8d99d30b0c414a0f Mon Sep 17 00:00:00 2001 From: Lorexia Date: Mon, 2 Oct 2023 17:29:21 +0200 Subject: [PATCH] Add bundling pages and details for ESbuild and Webpack --- sdk/typescript/docs/pages/_meta.json | 4 +- sdk/typescript/docs/pages/bundling.mdx | 134 ------------------ sdk/typescript/docs/pages/bundling/_meta.json | 6 + .../docs/pages/bundling/bundling.mdx | 54 +++++++ .../docs/pages/bundling/esbuild.mdx | 25 ++++ .../docs/pages/bundling/webpack.mdx | 82 +++++++++++ .../pages/{guides => examples}/_meta.json | 0 .../pages/{guides => examples}/cosmos-kit.mdx | 8 +- .../pages/{guides => examples}/mix-fetch.mdx | 8 +- .../pages/{guides => examples}/mixnet.mdx | 8 +- .../nym-smart-contracts.mdx | 9 +- 11 files changed, 186 insertions(+), 152 deletions(-) delete mode 100644 sdk/typescript/docs/pages/bundling.mdx create mode 100644 sdk/typescript/docs/pages/bundling/_meta.json create mode 100644 sdk/typescript/docs/pages/bundling/bundling.mdx create mode 100644 sdk/typescript/docs/pages/bundling/esbuild.mdx create mode 100644 sdk/typescript/docs/pages/bundling/webpack.mdx rename sdk/typescript/docs/pages/{guides => examples}/_meta.json (100%) rename sdk/typescript/docs/pages/{guides => examples}/cosmos-kit.mdx (92%) rename sdk/typescript/docs/pages/{guides => examples}/mix-fetch.mdx (93%) rename sdk/typescript/docs/pages/{guides => examples}/mixnet.mdx (92%) rename sdk/typescript/docs/pages/{guides => examples}/nym-smart-contracts.mdx (96%) diff --git a/sdk/typescript/docs/pages/_meta.json b/sdk/typescript/docs/pages/_meta.json index d0a3f5cdfc..8c91360078 100644 --- a/sdk/typescript/docs/pages/_meta.json +++ b/sdk/typescript/docs/pages/_meta.json @@ -3,9 +3,9 @@ "overview": "SDK overview", "installation": "Installation", "start": "Getting started", - "guides": "Examples", + "examples": "Step-by-step examples", "playground": "Live Playground", - + "bundling": "Bundling", "contact": { "title": "Contact ↗", diff --git a/sdk/typescript/docs/pages/bundling.mdx b/sdk/typescript/docs/pages/bundling.mdx deleted file mode 100644 index 026fefc81f..0000000000 --- a/sdk/typescript/docs/pages/bundling.mdx +++ /dev/null @@ -1,134 +0,0 @@ -# Troubleshooting Bundling - -You might need some help bundling packages from the Nym Typescript SDK into your package. - -Here are some things that could go wrong: - -## WebAssembly (WASM) and web worker not included in output bundle - -### Webpack - -You might need to use the CopyPlugin by adding this to your Webpack config: - -```js -const CopyPlugin = require('copy-webpack-plugin'); - -... - -module.exports = { - ... - plugins: [ - ... - new CopyPlugin({ - patterns: [ - { - from: path.resolve(path.dirname(require.resolve('@nymproject/mix-fetch/package.json')), '*.wasm'), - to: '[name][ext]', - }, - { - from: path.resolve(path.dirname(require.resolve('@nymproject/mix-fetch/package.json')), '*worker*.js'), - to: '[name][ext]', - }, - ], - }), - ], -} -``` - -How does this work? The statement `require.resolve('@nymproject/mix-fetch/package.json')` finds the disk location of -the Nym SDK package, and resolve the directory name is `path.dirname`, the add the `*.wasm` glob to the search pattern -list. Use `[name][ext]` to preserve the output filename, because the package expects the filename to stay the same. - -## ESM not supported - -If your bundler does not support ECMAScript Modules (ESM) we provide CommonJS packages for most parts of the SDK. - -For those that don't have ESM versions, you will need to use a tool like [Babel](https://babeljs.io/) to convert -ESM to CommonJS. - -## CSP prevents loading - -If you are using a `*-full-fat` package, or if you inline WASM or web workers, you may not be able to load them if the -[CSP](https://developer.mozilla.org/en-US/docs/Web/HTTP/CSP) prevents WASM from being instantiated from a string. - -You'll have to experiment with either adjusting the CSP or use another variant that is unbundled. - -## Webpack > 5 ESM - -You´ll need the following rule in your `webpack.config.js` above version 5: -```json -{ - test: /\.(m?js)$/, - resolve: { - fullySpecified: false - } -} -``` - -### Nextjs - -NextJS doesn´t allow you access to the webpack config without ejecting, which you override as follows: - -```bash -npx create-react-app nymapp --template typescript -cd nymapp -``` - -#### Install contract-clients dependencies - -```bash -npm install @nymproject/contract-clients @cosmjs/cosmwasm-stargate @cosmjs/proto-signing -``` - -#### polyfilling - -Copy the following to your terminal and run: - -```bash -npm install react-app-rewired -npm install --save-dev crypto-browserify stream-browserify assert stream-http https-browserify os-browserify url buffer process -cat < config-overrides.js -const webpack = require('webpack'); -const path = require('path') - -module.exports = function override(config) { - const fallback = config.resolve.fallback || {}; - Object.assign(fallback, { - "crypto": require.resolve("crypto-browserify"), - "stream": require.resolve("stream-browserify"), - "assert": require.resolve("assert"), - "http": require.resolve("stream-http"), - "https": require.resolve("https-browserify"), - "os": require.resolve("os-browserify"), - "url": require.resolve("url") - }) - config.resolve.fallback = fallback; - config.plugins = (config.plugins || []).concat([ - new webpack.ProvidePlugin({ - process: 'process/browser', - Buffer: ['buffer', 'Buffer'] - }) - ]) - config.module.rules = (config.module.rules || []).concat([ - { - test: /\.(m?js)$/, - resolve: { - fullySpecified: false - } - } - ]) - return config; -} -EOF -``` - -#### Edit the `package.json` file as follows: - -```json - "scripts": { - "start": "react-app-rewired start", - "build": "react-app-rewired build", - "test": "react-app-rewired test", - "eject": "react-scripts eject" - }, -``` \ No newline at end of file diff --git a/sdk/typescript/docs/pages/bundling/_meta.json b/sdk/typescript/docs/pages/bundling/_meta.json new file mode 100644 index 0000000000..5ee55efacc --- /dev/null +++ b/sdk/typescript/docs/pages/bundling/_meta.json @@ -0,0 +1,6 @@ +{ + "bundling": "General troubleshooting", + "esbuild": "ESbuild", + "webpack": "Webpack" +} + \ No newline at end of file diff --git a/sdk/typescript/docs/pages/bundling/bundling.mdx b/sdk/typescript/docs/pages/bundling/bundling.mdx new file mode 100644 index 0000000000..1fda031869 --- /dev/null +++ b/sdk/typescript/docs/pages/bundling/bundling.mdx @@ -0,0 +1,54 @@ +# Troubleshooting Bundling + +You might need some help bundling packages from the Nym Typescript SDK into your package. + +Here are some things that could go wrong: + +## WebAssembly (WASM) and web worker not included in output bundle + +### Webpack + +You might need to use the CopyPlugin by adding this to your Webpack config: + +```js +const CopyPlugin = require('copy-webpack-plugin'); + +... + +module.exports = { + ... + plugins: [ + ... + new CopyPlugin({ + patterns: [ + { + from: path.resolve(path.dirname(require.resolve('@nymproject/mix-fetch/package.json')), '*.wasm'), + to: '[name][ext]', + }, + { + from: path.resolve(path.dirname(require.resolve('@nymproject/mix-fetch/package.json')), '*worker*.js'), + to: '[name][ext]', + }, + ], + }), + ], +} +``` + +How does this work? The statement `require.resolve('@nymproject/mix-fetch/package.json')` finds the disk location of +the Nym SDK package, and resolve the directory name is `path.dirname`, the add the `*.wasm` glob to the search pattern +list. Use `[name][ext]` to preserve the output filename, because the package expects the filename to stay the same. + +## ESM not supported + +If your bundler does not support ECMAScript Modules (ESM) we provide CommonJS packages for most parts of the SDK. + +For those that don't have ESM versions, you will need to use a tool like [Babel](https://babeljs.io/) to convert +ESM to CommonJS. + +## CSP prevents loading + +If you are using a `*-full-fat` package, or if you inline WASM or web workers, you may not be able to load them if the +[CSP](https://developer.mozilla.org/en-US/docs/Web/HTTP/CSP) prevents WASM from being instantiated from a string. + +You'll have to experiment with either adjusting the CSP or use another variant that is unbundled. diff --git a/sdk/typescript/docs/pages/bundling/esbuild.mdx b/sdk/typescript/docs/pages/bundling/esbuild.mdx new file mode 100644 index 0000000000..2732aea63f --- /dev/null +++ b/sdk/typescript/docs/pages/bundling/esbuild.mdx @@ -0,0 +1,25 @@ +# Troubleshooting bundling with ESbuild + +If you've been following the steps outlined in the Examples section, your development environment should be configured as follows: + +#### Environment Setup +Begin by creating a directory and configuring your application environment: + +Create your directory and set-up your app environment: +```bash +npm create vite@latest +``` +During the environment setup, choose React and subsequently opt for Typescript if you want your application to function smoothly following this tutorial. Next, navigate to your application directory and run the following commands: +```bash +cd < YOUR_APP > +npm i +npm run dev +``` + +##### Installation +Install the required package: +```bash +npm install @nymproject/< PACKAGE_NAME > +``` + +By implementing the provided code for the various components in the step-by-step examples section, you should be able to set-up and run your application without encountering any bundling challenges! \ No newline at end of file diff --git a/sdk/typescript/docs/pages/bundling/webpack.mdx b/sdk/typescript/docs/pages/bundling/webpack.mdx new file mode 100644 index 0000000000..d52815f95f --- /dev/null +++ b/sdk/typescript/docs/pages/bundling/webpack.mdx @@ -0,0 +1,82 @@ + +# Troubleshooting bundling with Webpack + +## Webpack > 5 ESM + +You´ll need the following rule in your `webpack.config.js` above version 5: +```json +{ + test: /\.(m?js)$/, + resolve: { + fullySpecified: false + } +} +``` + +### Create-react-app + +Create-react-app doesn´t allow you access to the Webpack config without ejecting, which you override as follows: + +```bash +npx create-react-app nymapp --template typescript +cd nymapp +``` + +#### Install contract-clients dependencies + +```bash +npm install @nymproject/contract-clients @cosmjs/cosmwasm-stargate @cosmjs/proto-signing +``` + +#### Polyfilling + +Copy the following to your terminal and run: + +```bash +npm install react-app-rewired +npm install --save-dev crypto-browserify stream-browserify assert stream-http https-browserify os-browserify url buffer process +cat < config-overrides.js +const webpack = require('webpack'); +const path = require('path') + +module.exports = function override(config) { + const fallback = config.resolve.fallback || {}; + Object.assign(fallback, { + "crypto": require.resolve("crypto-browserify"), + "stream": require.resolve("stream-browserify"), + "assert": require.resolve("assert"), + "http": require.resolve("stream-http"), + "https": require.resolve("https-browserify"), + "os": require.resolve("os-browserify"), + "url": require.resolve("url") + }) + config.resolve.fallback = fallback; + config.plugins = (config.plugins || []).concat([ + new webpack.ProvidePlugin({ + process: 'process/browser', + Buffer: ['buffer', 'Buffer'] + }) + ]) + config.module.rules = (config.module.rules || []).concat([ + { + test: /\.(m?js)$/, + resolve: { + fullySpecified: false + } + } + ]) + return config; +} +EOF +``` + +#### Edit the `package.json` file as follows: + +```json + "scripts": { + "start": "react-app-rewired start", + "build": "react-app-rewired build", + "test": "react-app-rewired test", + "eject": "react-scripts eject" + }, +``` \ No newline at end of file diff --git a/sdk/typescript/docs/pages/guides/_meta.json b/sdk/typescript/docs/pages/examples/_meta.json similarity index 100% rename from sdk/typescript/docs/pages/guides/_meta.json rename to sdk/typescript/docs/pages/examples/_meta.json diff --git a/sdk/typescript/docs/pages/guides/cosmos-kit.mdx b/sdk/typescript/docs/pages/examples/cosmos-kit.mdx similarity index 92% rename from sdk/typescript/docs/pages/guides/cosmos-kit.mdx rename to sdk/typescript/docs/pages/examples/cosmos-kit.mdx index 2d197f71d7..52af063bd5 100644 --- a/sdk/typescript/docs/pages/guides/cosmos-kit.mdx +++ b/sdk/typescript/docs/pages/examples/cosmos-kit.mdx @@ -7,14 +7,14 @@ Nym, these include: - using the [Ledger hardware wallet](https://docs.cosmoskit.com/integrating-wallets/ledger) from the browser - any wallet that supports [Wallet Connect v2.0](https://docs.cosmoskit.com/integrating-wallets/adding-new-wallets) -##### Set-up your environment +##### Environment Setup +Begin by creating a directory and configuring your application environment: -Create your directory and set-up your app environment: ```bash npm create vite@latest ``` -Select `React` and later `Typescript` as you go to your environment set-up if you want your app to work off the bat following this tutorial. -Then, + +During the environment setup, choose React and subsequently opt for Typescript if you want your application to function smoothly following this tutorial. Next, navigate to your application directory and run the following commands: ```bash cd < YOUR_APP > npm i diff --git a/sdk/typescript/docs/pages/guides/mix-fetch.mdx b/sdk/typescript/docs/pages/examples/mix-fetch.mdx similarity index 93% rename from sdk/typescript/docs/pages/guides/mix-fetch.mdx rename to sdk/typescript/docs/pages/examples/mix-fetch.mdx index 62826d2b75..83d3a4a15e 100644 --- a/sdk/typescript/docs/pages/guides/mix-fetch.mdx +++ b/sdk/typescript/docs/pages/examples/mix-fetch.mdx @@ -55,14 +55,14 @@ const mixFetchOptions: SetupMixFetchOps = { }; ``` -##### Set-up your environment +##### Environment Setup +Begin by creating a directory and configuring your application environment: -Create your directory and set-up your app environment: ```bash npm create vite@latest ``` -Select `React` and later `Typescript` as you go to your environment set-up if you want your app to work off the bat following this tutorial. -Then, + +During the environment setup, choose React and subsequently opt for Typescript if you want your application to function smoothly following this tutorial. Next, navigate to your application directory and run the following commands: ```bash cd < YOUR_APP > npm i diff --git a/sdk/typescript/docs/pages/guides/mixnet.mdx b/sdk/typescript/docs/pages/examples/mixnet.mdx similarity index 92% rename from sdk/typescript/docs/pages/guides/mixnet.mdx rename to sdk/typescript/docs/pages/examples/mixnet.mdx index 290f55b0f6..50fef0e394 100644 --- a/sdk/typescript/docs/pages/guides/mixnet.mdx +++ b/sdk/typescript/docs/pages/examples/mixnet.mdx @@ -10,14 +10,14 @@ Replying can be done in two ways: - reveal the sender's address to the recipient (as part of the payload) - use a SURB (single use reply block) that allows the recipient to reply to the sender without compromising the identity of either party -##### Set-up your environment +##### Environment Setup +Begin by creating a directory and configuring your application environment: -Create your directory and set-up your app environment: ```bash npm create vite@latest ``` -Select `React` and later `Typescript` as you go to your environment set-up if you want your app to work off the bat following this tutorial. -Then, + +During the environment setup, choose React and subsequently opt for Typescript if you want your application to function smoothly following this tutorial. Next, navigate to your application directory and run the following commands: ```bash cd < YOUR_APP > npm i diff --git a/sdk/typescript/docs/pages/guides/nym-smart-contracts.mdx b/sdk/typescript/docs/pages/examples/nym-smart-contracts.mdx similarity index 96% rename from sdk/typescript/docs/pages/guides/nym-smart-contracts.mdx rename to sdk/typescript/docs/pages/examples/nym-smart-contracts.mdx index 305bee00ea..2322ba6a16 100644 --- a/sdk/typescript/docs/pages/guides/nym-smart-contracts.mdx +++ b/sdk/typescript/docs/pages/examples/nym-smart-contracts.mdx @@ -23,14 +23,15 @@ Depending on your app or project's architecture, this could be any of the ESM or This and the following examples will use the ESbuild bundler. If you'd like to use another one, we will document different bundlers and polyfills in the [bundling](https://sdk.nymtech.net/bundling) page. -##### Set-up your environment -Create your directory and set-up your app environment: +##### Environment Setup +Begin by creating a directory and configuring your application environment: + ```bash npm create vite@latest ``` -Select `React` and later `Typescript` as you go to your environment set-up if you want your app to work off the bat following this tutorial. -Then, + +During the environment setup, choose React and subsequently opt for Typescript if you want your application to function smoothly following this tutorial. Next, navigate to your application directory and run the following commands: ```bash cd < YOUR_APP > npm i