Npm package

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:

   npm i -S garaga

   or

   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 and Node.js installed in you machine.

1. Open your terminal or command prompt.

2. Install wasm-pack by running:

   cargo install wasm-pack

3. Run the following commands:

   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

   npm i -S <path-to-tgz-package-file>

For reproducible builds, one can use instead docker compose. Make sure docker is installed in you machine.

1. Open your terminal or command prompt.

2. Run the following commands:

   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

   npm i -S <path-to-tgz-package-file>

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.

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:

   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:

   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:

   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:

   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 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.)