tarawasm

A simple CLI for WebAssembly component workflow.

Supported guest languages

• Python
• Go
• Rust
• JavaScript
• C/C++

---

Table of Contents

• Quickstart
• Manual installation
  • 1. System packages (Debian/Ubuntu)
  • 2. Go 1.24.3
  • 3. Rust
  • 4. TinyGo
  • 5. Python packages
  • 6. WASM tools (Cargo)
  • 7. Node.js 22.x
  • 8. JavaScript tools (npm)
  • 9. WASI SDK
• Using Docker
• Usage
  • Providing WIT definitions
  • Initializing a project
  • Generating bindings
  • Building the WASM component
• Available Commands
• Formatting and linting
• Running tests

---

Quickstart

1. Install everything automatically

make install

This will:

• Install system packages (via apt-get)
• Install Go 1.24.3
• Install Rust (via rustup)
• Install TinyGo 0.37.0
• Install Python packages from requirements.txt
• Install WASM tools (wkg, wasm-tools, cargo-component)
• Install Node.js 22.x and JS tools (jco, componentize-js)

2. Verify your setup

make check

Runs both:

• make system-check — checks Go, Rust, TinyGo, Node.js, Python, clang (wasi-sdk)
• make sdk-check — checks installed CLI tools (jco, wkg, wasm-tools, cargo-component) and Python packages

3. Build your project

make build

---

Manual installation

If you prefer to install dependencies manually, follow these steps.

1. System packages (Debian/Ubuntu)

sudo apt-get update
sudo apt-get install -y \
  build-essential ca-certificates cmake curl git gnupg \
  lld llvm patchelf python3 python3-dev python3-pip wget

2. Go 1.24.3

wget https://go.dev/dl/go1.24.3.linux-amd64.tar.gz
sudo rm -rf /usr/local/go
sudo tar -C /usr/local -xzf go1.24.3.linux-amd64.tar.gz
rm go1.24.3.linux-amd64.tar.gz
export PATH="/usr/local/go/bin:$PATH"

3. Rust

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y
. "$HOME/.cargo/env"

4. TinyGo

wget https://github.com/tinygo-org/tinygo/releases/download/v0.37.0/tinygo_0.37.0_amd64.deb
sudo dpkg -i tinygo_0.37.0_amd64.deb
rm tinygo_0.37.0_amd64.deb

5. Python packages

python3 -m pip install --upgrade pip
python3 -m pip install --no-cache-dir -r requirements.txt

6. WASM tools (Cargo)

cargo install --locked --root /usr/local wkg --version 0.10.0
cargo install --locked --root /usr/local wasm-tools
cargo install --locked --root /usr/local cargo-component --version 0.21.1

7. Node.js 22.x

curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt-get install -y nodejs

8. JavaScript tools (npm)

npm install -g @bytecodealliance/jco@1.9.1 \
               @bytecodealliance/componentize-js@0.7.0

9. WASI SDK

wget -q https://github.com/WebAssembly/wasi-sdk/releases/download/wasi-sdk-25/wasi-sdk-25.0-x86_64-linux.deb
sudo apt install -y ./wasi-sdk-25.0-x86_64-linux.deb
rm wasi-sdk-25.0-x86_64-linux.deb

# Add /opt/wasi-sdk/bin to PATH
export WASI_SDK_PATH=/opt/wasi-sdk
export PATH=$WASI_SDK_PATH/bin:$PATH

---

Using Docker

You can avoid installing all dependencies locally by using the official Docker image:

docker pull mandeser0/tarawasm:latest

Convenient alias

Add this alias to your shell config (~/.bashrc or ~/.zshrc):

alias tarawasm='docker run --rm -v "$PWD":/work -w /work mandeser0/tarawasm'

Installing additional Python packages inside the Docker container

When working on Python-based components, the base Docker image may not include all Python libraries you need. If you encounter missing dependencies, you can install them directly inside the container using:

tarawasm pip install <your-package>

This will run pip install inside the Docker container, making the package available for subsequent tarawasm build commands.

---

Usage

Providing WIT definitions

Before starting, you need WIT definitions. Example:

wkg wit build --wit-dir=<path-to-your-wit-files>

Move the resulting .wasm file into your project directory.

---

Initializing a project

tarawasm init --lang <language> --wasm-file <your-wasm-file> <world-name>

You can optionally specify a custom source file:

tarawasm init --lang <language> --wasm-file <your-wasm-file> \
  --src-file <your-source-file> <world-name>

Generating bindings

tarawasm bind

Building the WASM component

tarawasm build

Available Commands

Command	Description
tarawasm init	Initialize project and save config
tarawasm bind	Generate bindings from WIT
tarawasm build	Compile source to WASM component
tarawasm clean	Remove build artifacts
tarawasm all	Run clean, bind, and build
tarawasm strip	Remove custom sections from the WASM binary

The strip command helps reduce the size of the generated WASM component by removing unnecessary custom sections. This is especially useful for Python-based components, where it can reduce the final binary size by up to 2x.

---

Formatting and linting

To install development dependencies and set up pre-commit hooks:

python3 -m pip install -r requirements-dev.txt
pre-commit install

Run Ruff for code style checks:

ruff .

Run Black for formatting:

black .

Or run all pre-commit hooks:

pre-commit run --all-files

---

Running tests

The test suite mirrors the Docker workflow and requires a WebAssembly runtime.

Set the WASM_RUNTIME environment variable to your runtime binary (defaults to wasmtime):

export WASM_RUNTIME=wasmtime

Tests for the C example will only run if clang --version reports the wasm32-unknown-wasi target (see WASI SDK).

Run tests:

pytest