Skip to main content
Version: v2.0.0-rc

Developer Guide

Wasm Shell (wash) is the comprehensive command-line tool for developing, building, and publishing WebAssembly components.

In this guide, you'll learn how to:

  • Create a new WebAssembly component project in Rust, Go (TinyGo), or JavaScript (TypeScript)
  • Start a development loop for your component project
  • Compile your project to a WebAssembly component binary
  • Publish your component to an OCI registry

Prerequisites​

This guide requires Wasm Shell (wash) and the language toolchain for your language of choice.

To get started:

Create a new component project​

Let's create a component that accepts an HTTP request and responds with "Hello from Rust!"

Use wash new to create a new component project from an example in a Git repository:

shell
wash new https://github.com/wasmCloud/wash.git --name hello --subfolder examples/http-hello-world

This command...

  • Creates a new project named hello...
  • Based on an example found in the wasmCloud/wash Git repository...
  • In the subfolder examples/http-hello-world

Navigate to the new hello directory and take a look at the generated project.

Anatomy of a component project​

Component projects are made up of three primary parts:

  • Application code in your language of choice
  • Interfaces: language-agnostic APIs that enable components to interact
  • Bindings that translate your interfaces to the language of your application code

Anatomy of a component

Interfaces​

Interfaces are APIs written in WebAssembly Interface Type (WIT). The WIT files (.wit) that make up an interface are typically stored in a /wit folder at the root of a project.

Interfaces define contracts between entities that ultimately express a piece of functionality in terms of imports and exports:

  • Imports express a dependency: "I need another entity to fulfill this functionality."
  • Exports express a function exposed to other entities: "I can take care of this functionality."

For example, a component exporting on an HTTP Incoming Handler interface is exposing a function with an assertion that it can handle incoming HTTP requests.

By contrast, a component importing a Key-Value Storage interface is expressing that it requires another entity to expose key-value functionality on the same interface.

The WebAssembly System Interface (WASI) is a group of standards-track interface specifications under development by the WASI Subgroup in the W3C WebAssembly Community Group. WASI interfaces provide standard, namespaced APIs for common functionality, such as wasi:http.

We'll be using wasi:http throughout the rest of this tutorial.

Note: In the definitions above, "entities" often means other WebAssembly components, but not always—any piece of software could theoretically interact over a WIT interface, and common imports like wasi:io or wasi:logging are often fulfilled by WebAssembly runtime environments.

Further reading

Bindings​

Interfaces defined in WIT are language-agnostic, so they must be translated to a given language via bindings.

Bindings are generated a bit differently across different languages, but ultimately wash and the underlying language toolchain will handle binding generation automatically when you run wash dev or wash build.

info

If you use an IDE that comes with code completion and hover-tooltips, you'll be able to see documentation and get strongly-typed guidance as you develop code to interact with WASI interfaces and language-specific bindings. For more Wasm developer tooling, see Useful WebAssembly Tools.

Explore the code​

A component's imports and exports are defined in a WIT world. You can find this project's WIT world at ./wit/world.wit:

wit
package wasmcloud:hello;

world hello {
   export wasi:http/incoming-handler@0.2.2;
}

This component exports on one interface: wasi:http/incoming-handler. This means it can only interact with other entities by handling incoming HTTP requests, according to contracts defined in v0.2.2 of the wasi:http interface.

It also means that the component must export on this interface in order to compile successfully.

Now let's take a look at the application code.

The file src/lib.rs imports the wstd crate and consists of three simple async functions. We'll walk through these sections in detail.

rust
use wstd::http::{Body, Request, Response, StatusCode};

The wstd crate is an async Rust standard library for Wasm components and WASI 0.2 hosted by the Bytecode Alliance. Importing wstd means that we can use wstd::http rather than working directly with Rust bindings of the wasi:http interface.

info

You do not need to use wstd to build components with Rust, but it is standard ecosystem tooling that can help simplify development. This example will work directly with any WebAssembly runtime that supports the Wasm Component Model.

Whenever an incoming HTTP request is received, the main function returns a response depending on whether the endpoint is / or not found.

rust
#[wstd::http_server]
async fn main(req: Request<Body>) -> Result<Response<Body>, wstd::http::Error> {
    match req.uri().path_and_query().unwrap().as_str() {
        "/" => home(req).await,
        _ => not_found(req).await,
    }
}

async fn home(_req: Request<Body>) -> Result<Response<Body>, wstd::http::Error> {
    // Return a simple response with a string body
    Ok(Response::new("Hello from wasmCloud!\n".into()))
}

async fn not_found(_req: Request<Body>) -> Result<Response<Body>, wstd::http::Error> {
    Ok(Response::builder()
        .status(StatusCode::NOT_FOUND)
        .body("Not found\n".into())
        .unwrap())
}

Within the home and not_found functions, the application creates appropriate responses, and the component returns those responses back to the requesting HTTP client (such as a curl command or a web browser).

Something's missing

Note what's not included in this code:

  • The code is not tightly coupled to any particular HTTP server. It returns an abstraction of an HTTP response.
  • You don't see the port number or server configuration options anywhere in the code.

This style of interface driven development enables you to write application logic in the language of your choice without having to worry about the non-functional requirements of your application.

Start a development loop​

Now we'll start a development loop that runs the component, watches for modifications to the code, and refreshes when we make changes.

shell
wash dev

Now we can send a request to localhost:8000 with curl (in a new tab), or by visiting the address in our browser.

shell
curl localhost:8000

You should see:

text
Hello from <your language>

You can stop the development loop with CTRL+C.

Next steps​

In the next section, we'll compile a component to a .wasm binary and publish the artifact to an OCI registry.