Skip to main content

Developing Wasm Components

Cosmonic Control separates developer and operator concerns: operators use standard cloud-native pipelines and tooling to manage deployments, while Wasm component developers use the tooling that makes sense for them.

The Wasm Shell (wash) CLI is the simplest way to develop Wasm components across languages including Go, TypeScript, and Rust.

In this section for developers, you'll learn...

What is wash?​

A number of different tools and language toolchains offer ways to compile WebAssembly components, but the simplest way to develop components is the open source Wasm Shell (wash) CLI, which consolidates many utilities including...

  • Component templating and compilation across multiple languages
  • Interface package management
  • Hot-reloading development loop
  • Pushing to registries
warning

Wasm Shell is a next-generation version of wasmCloud's existing wash utility, open source and intended for upstreaming to the wasmCloud project. All references to wash on this page refer to the next-generation fork hosted at Cosmonic Labs.

How to install wash​

Use the install script to get up and running quickly:

curl -fsSL https://raw.githubusercontent.com/cosmonic-labs/wash/refs/heads/main/install.sh | bash
info

You'll also want to add wash to your PATH to run it easily. Refer to instructions specific to your operating system for how to do this.

Verify that wash is installed:

wash --help

How to check for Wasm component build dependencies​

Use the wash doctor command to check your system for language toolchain-specific Wasm component development dependencies.

wash doctor

How to start a new Wasm component project with wash​

Create a new project:

wash new component

The CLI will provide a set of templates that you can choose to use as the foundation of your project.

How to start a development loop with wash​

From the root of your Wasm component project directory, run wash dev to start a local development loop:

wash dev

The wash dev command will:

  • Compile the Wasm component in your working directory
  • Run the compiled Wasm component
  • Infer and initialize requirements to run the component locally
  • Watch your code for changes and re-deploy when necessary

The development loop currently supports WASI 0.2 interfaces, wasi:config/runtime, and wasi:logging/logging.

Using runtime configuration with wash dev​

You can define runtime configuration values during your development loop with the --runtime-config argument:

wash dev --runtime-config name=value

How to compile a component with wash​

Use the wash build command from the root of a project directory to compile the component into a .wasm binary:

wash build

How to push a component to an OCI registry​

Components are packaged as standard OCI artifacts. You can push straight from wash, or use a tool like oras to push a component to an OCI registry. (wash uses the oras library for its OCI functionality.)

wash supports loading credentials from Docker credentials, so the best path to authenticate is to docker login with your registry.

Push the component to your registry:

wash oci push ghcr.io/cosmonic-labs/components/hello:0.2.0 ./dist/http-hello-world.wasm

Further reading​