From 584cad66d067aa6c04447fe06a00c7be99bc2445 Mon Sep 17 00:00:00 2001 From: Rodrigo Ferreira Date: Wed, 16 Oct 2024 01:24:13 -0300 Subject: [PATCH] NPM package documentation (#213) --- docs/gitbook/installation/npm-package.md | 123 ++++++++++++++++++++++- 1 file changed, 122 insertions(+), 1 deletion(-) diff --git a/docs/gitbook/installation/npm-package.md b/docs/gitbook/installation/npm-package.md index 7ae32e34..e823d343 100644 --- a/docs/gitbook/installation/npm-package.md +++ b/docs/gitbook/installation/npm-package.md @@ -1,3 +1,124 @@ # Npm package -soon +## Installation via NPM Registry (recommended) + +The easiest way to install Garaga is via your prefered Node.js package manager, such as `npm` or `yarn`. + +1. Open your terminal or command prompt. +2. Run the following command: + + ```bash + npm i -S garaga + ``` + + or + + ```bash + yarn add garaga + ``` + +## Building the package from source code + +The package can be build directly from source code by cloning the garaga repository. Make sure you have both [Rust](https://www.rust-lang.org/tools/install) and [Node.js](https://nodejs.org/en/learn/getting-started/how-to-install-nodejs) installed in you machine. + +1. Open your terminal or command prompt. +2. Install `wasm-pack` by running: + + ```bash + cargo install wasm-pack + ``` + +3. Run the following commands: + + ```bash + git clone https://github.com/keep-starknet-strange/garaga.git + cd tools/npm/garaga_ts + npm ci + npm run build + npm pack + ``` + +4. The .tgz file with the package contents will be available in the current folder. +5. Install the .tgz file in your project + + ```bash + npm i -S + ``` + +For reproducible builds, one can use instead docker compose. Make sure [docker](https://docs.docker.com/engine/install/) is installed in you machine. + +1. Open your terminal or command prompt. +2. Run the following commands: + + ```bash + git clone https://github.com/keep-starknet-strange/garaga.git + cd tools/npm/garaga_ts + docker compose up --build + ``` + +3. The .tgz file with the package contents will be available in the current folder. +4. Install the .tgz file in your project + + ```bash + npm i -S + ``` + +## Development notes + +The Garaga NPM package is a mixed package. It is implemented in TypeScript but also reuses Rust code targeted to WebAssembly (WASM) with the help of [`wasm-pack`](https://rustwasm.github.io/wasm-pack/). + +The `src` folder is organized into two subfolders: `node` which contains the implementation in TypeScript; and `wasm` which has the interoperabilty code produced by `wasm-pack`. + +Changes to the TypeScript library should only be made to files under the `node` subfolder. Changes to the Rust implementation requires regenerating files under the `wasm` subfolder. + +Onces changes are in place they can be made permanent into the repository by committing the contents of both folders. Here is the bulk of the process: + +1. Open your terminal or command prompt. +2. Use `git` to clone the repository: + + ```bash + git clone https://github.com/keep-starknet-strange/garaga.git + cd tools/npm/garaga_ts + npm ci + ``` + +3. If you make TypeScript only changes, you can quickly rebuild the package using the `build:node` NPM script: + + ```bash + npm run build:node + npm pack + ``` + +4. If instead you make Rust changes, it is necessary to generate the WASM interoperability code using the `build` NPM script: + + ```bash + npm run build + npm pack + ``` + +5. However, before commiting changes, it is necessary to generate the WASM interoperability code in a reproducible manner using docker: + + ```bash + docker compose up --build + git commit . + ``` +### How `wasm-pack` is used to achieve interoperability + +Internaly the `build` NPM script uses `wasm-pack` to produce the WASM interoperability code. This is achieved by running + + ```bash + cd tools/garaga_rs && wasm-pack build --target web --out-dir ../npm/garaga_ts/src/wasm/pkg --release --no-default-features + cd tools/npm/garaga_ts && node patch.wasm.cjs + ``` +Let's unpack it. + +In the Rust source folder we run `wasm-pack` in `--target web` mode. This generates TypeScript code targeting web pages. +The `--release` option is required to minimize the size of the WASM module. +And the `--no-default-features` disables the need to build non WASM features of garaga_rs. + +Once the `wasm-pack` is done, the code is generated under the folder `src/wasm/pkg` of garaga_ts that houses the TypeScript source code. + +We then run a custom script `patch.wasm.cjs` which makes minimal changes to the code generated by wasm-pack to facilitate seamless support of the WASM module in both the browser and Node.js. +Basically it converts the WASM module to a [Base64](https://en.wikipedia.org/wiki/Base64) string that can be loaded in a portable way in both environments, amongst other minor tweaks. + +(It is important to note that the use of a custom script is only required so long `wasm-pack` itself does not provide a more portable/universal target mode.)