mandeser0/tarawasm repository overview

⁠tarawasm

Build WebAssembly components directly from WIT contracts using Python, Go, JavaScript, Rust, or C/C++.

All languages share the same workflow:

tarawasm init --lang python --wit ./wit --world calculator .
tarawasm bind
tarawasm build

The final validated WebAssembly Component Model binary is written to:

dist/<world>.wasm

Source code and examples are available on GitHub⁠.

⁠Quick start

Create a helper function that runs tarawasm inside Docker:

tarawasm() {
  docker run --rm \
    -v "$PWD:/work" \
    -w /work \
    mandeser0/tarawasm:latest "$@"
}

Create wit/calculator.wit:

package example:[email protected];

world calculator {
    export add: func(a: s32, b: s32) -> s32;
}

Initialize the project:

tarawasm init \
    --lang python \
    --wit ./wit \
    --world calculator \
    .

Generate bindings and build the component:

tarawasm bind
tarawasm build

The result is:

dist/calculator.wasm

Tarawasm generates a starter source file from the selected world's exports. Implement the generated functions and run tarawasm build again.

⁠Supported languages

The Docker image includes all required compilers, SDKs, binding generators, and WebAssembly tools.

⁠Go requirement

TinyGo's wasip2 target requires the selected world to import the complete versioned wasi:cli/[email protected] interface set.

Tarawasm validates these imports before invoking TinyGo and reports any missing interfaces.

⁠Initialize a project from WIT

tarawasm init \
    --lang <python|go|js|rust|c> \
    --wit <wit-file-or-directory> \
    [--world <world>] \
    [project-directory]

--wit accepts either:

• a single .wit file;
• a directory containing a WIT package.

If the package contains exactly one world, --world may be omitted. If several worlds are available, tarawasm lists them and requires an explicit selection.

Preview initialization without changing the filesystem:

tarawasm init \
    --lang rust \
    --wit ./wit \
    --world calculator \
    --dry-run \
    .

Initialization validates the WIT package before writing files. Existing user source files are not overwritten.

⁠Import an existing component

Use tarawasm import when starting from an existing WebAssembly component:

tarawasm import \
    --lang python \
    --component ./service.wasm \
    --world service \
    ./service-project

The input must be a WebAssembly Component Model binary. Core WebAssembly modules are rejected.

Extracted WIT is stored in:

.tarawasm/imported-wit

The original component is never modified or treated as a generated artifact.

⁠Build commands

Generate language bindings:

tarawasm bind

Build the final component:

tarawasm build

Run both steps:

tarawasm all

Use a custom output path:

tarawasm build --out ./release/service.wasm

Preview commands without changing the project:

tarawasm bind --dry-run
tarawasm build --dry-run

Pass arguments directly to the underlying language tool after --:

tarawasm build -- --verbose

Display help for the selected backend tool:

tarawasm build --tool-help

⁠Install Python dependencies

Python dependencies can be installed into the mounted project without rebuilding the Docker image:

tarawasm pip install requests
tarawasm build

Install dependencies from a file:

tarawasm pip install -r requirements.txt
tarawasm build

Packages are stored in:

.tarawasm/site-packages

They persist in the mounted project and are automatically used by componentize-py.

To select another location, pass TARAWASM_PY_SITE_PACKAGES consistently during installation and build:

docker run --rm \
  -v "$PWD:/work" \
  -w /work \
  -e TARAWASM_PY_SITE_PACKAGES=/work/vendor \
  mandeser0/tarawasm:latest \
  pip install -r requirements.txt

docker run --rm \
  -v "$PWD:/work" \
  -w /work \
  -e TARAWASM_PY_SITE_PACKAGES=/work/vendor \
  mandeser0/tarawasm:latest \
  build

⁠WIT dependencies

Tarawasm uses Bytecode Alliance wkg and wkg.lock for reproducible dependency resolution.

Resolve dependencies:

tarawasm deps resolve

List locked dependencies:

tarawasm deps list

Explicitly update dependency versions:

tarawasm deps update

Downloaded packages are cached under:

.tarawasm/deps/cache

Regular bind and build commands do not update the lock file.

⁠Project layout

A typical Python project looks like this:

calculator/
├── tarawasm.json
├── wit/
│   └── calculator.wit
├── main.py
├── .tarawasm/
│   ├── artifacts.json
│   ├── build/
│   │   └── python/
│   ├── deps/
│   │   └── cache/
│   └── site-packages/
└── dist/
    └── calculator.wasm

Intermediate build files are kept under .tarawasm/build.

Only the final Component Model binary is placed in dist.

⁠Safe cleanup

Remove generated artifacts with:

tarawasm clean

Tarawasm records generated files in .tarawasm/artifacts.json.

Cleanup removes only registered generated artifacts. It does not scan for arbitrary *.wasm files and does not delete user-owned directories such as target or internal.

⁠File ownership

The container detects the owner of the bind-mounted /work directory and runs build commands using the corresponding UID and GID.

Generated files therefore remain writable by the host user. The project directory is not made world-writable.

⁠Run without a shell helper

Every command can also be invoked directly:

docker run --rm \
  -v "$PWD:/work" \
  -w /work \
  mandeser0/tarawasm:latest \
  build

For interactive toolchain inspection:

docker run --rm -it \
  -v "$PWD:/work" \
  -w /work \
  --entrypoint /bin/bash \
  mandeser0/tarawasm:latest

⁠Examples

Ready-to-build examples for all supported languages are available in the repository:

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

See the complete examples guide⁠ for ready-project, WIT-first, and component import workflows.

⁠Links

• GitHub repository⁠
• WIT documentation⁠
• WebAssembly Component Model⁠