Quickstart
wasmCloud enables you to build polyglot applications out of reusable WebAssembly (Wasm) components and run them everywhere—across any cloud, Kubernetes, datacenter, or edge.
In this tutorial:
- We'll use the wasmCloud Shell (
wash
) CLI to build a simple "Hello world" HTTP server application from a WebAssembly component—written in the language of your choice. - Along the way, we'll start a developer loop that automatically deploys our application to a local wasmCloud environment.
Install wash
First, we need to install the latest version of wash
.
- macOS
- Ubuntu and Debian
- Windows
On macOS, you can use Homebrew to install wash
:
brew install wasmcloud/wasmcloud/wash
On Ubuntu and Debian Linux, you can use apt
to install wash
:
curl -s https://packagecloud.io/install/repositories/wasmcloud/core/script.deb.sh | sudo bash
sudo apt install wash
For the smoothest experience, we recommend that Windows users run wasmCloud with Windows Subsystem for Linux (WSL) and follow the Ubuntu/Debian instructions throughout this guide.
Microsoft provides documentation for getting started with WSL and using WSL with Visual Studio Code.
When using WSL, we recommend choosing the Ubuntu
distro (wsl --install -d Ubuntu
).
You may need to update git
to the latest version using the Ubuntu Git Maintainers' Personal Package Archive (PPA):
sudo add-apt-repository ppa:git-core/ppa
sudo apt-get update
sudo apt-get install git
When your WSL environment is ready, you can use the standard Ubuntu/Debian installation method:
curl -s https://packagecloud.io/install/repositories/wasmcloud/core/script.deb.sh | sudo bash
sudo apt install wash
If you are unable to use WSL, you can find native Windows installation instructions on the Installation page, but note that native Windows support is experimental.
We support other package managers and the option to install from source. If you'd like to use a different installation method, see the Installation page.
Verify that wash
is installed by running:
wash --version
Choose your language
wasmCloud supports building WebAssembly components from any language that supports the WASI 0.2 target, including Go, Rust, TypeScript, and others.
wash
depends on your local language toolchain for your language of choice.
- Choose the language you would like to use.
- Install the toolchain or verify that you have the correct versions.
- Go
- Rust
- TypeScript
- My Language Isn't Listed
Install the Go toolchain
Requirements:
- Go 1.23.0+
- TinyGo 0.33.0+:
wasm-tools
1.219+
You can use Homebrew to install the Go toolchain:
brew install go
brew install tinygo-org/tools/tinygo
You will also need the wasm-tools
utility. You can use brew
:
brew install wasm-tools
If you have the Rust toolchain, you can use cargo
to install wasm-tools
:
cargo install wasm-tools
Otherwise, download the binary for the latest version of wasm-tools
for your architecture and add it to your PATH.
Install the Rust toolchain
Requirements:
- The Rust toolchain
- The
wasm32-wasip2
target for Rust
You can use the official install script to download rustup
, which will automatically install the Rust toolchain:
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
Once you've installed the Rust toolchain, use rustup
to add the wasm32-wasip2
target:
rustup target add wasm32-wasip2
Install the TypeScript toolchain
Requirements:
- npm v10.8+
- TypeScript v5.6+
You can use Homebrew to install npm
(and Node.js):
brew install node
Once you've installed Node.js and npm
, you can use npm
to install TypeScript:
npm install -g typescript
If you prefer working in a language that isn't listed here, let us know!
Create a new component
Now that we've installed wash
and our language toolchain, it's time to create a new component project.
- Go
- Rust
- TypeScript
In your terminal, run:
wash new component hello --template-name hello-world-tinygo
After a moment, wash
will create a new directory called hello
with all of the required project files for building a component from your chosen language.
Navigate to the hello
project directory:
cd hello
In your terminal, run:
wash new component hello --template-name hello-world-rust
After a moment, wash
will create a new directory called hello
with all of the required project files for building a component from your chosen language.
Navigate to the hello
project directory:
cd hello
In your terminal, run:
wash new component hello --template-name hello-world-typescript
After a moment, wash
will create a new directory called hello
with all of the required project files for building a component from your chosen language.
Navigate to the hello
project directory:
cd hello
Install the npm packages for your project:
npm install
Start your developer loop
From our project directory, we'll run:
wash dev
The wash dev
command automatically builds your WebAssembly component and deploys it to a local wasmCloud environment. This will take a moment, and the terminal output will update you on the process. The last step should look like this:
✅ Successfully started host, logs writing to /home/.wash/dev/kSKCGi/wasmcloud.log
🚧 Building project...
...
✨ HTTP Server: Access your application at http://127.0.0.1:8000
👀 Watching for file changes (press Ctrl+c to stop)...
By default, the application will run on our local port 8000. In a new terminal tab, we can curl
our application:
curl localhost:8000
The application should return:
Hello from <language>!
You just ran a WebAssembly application in wasmCloud!
Make the application yours
Now we'll make a change to our code and see how the running application updates automatically.
- Go
- Rust
- TypeScript
- My Language Isn't Listed
Modify main.go
The Go code for our component is found in hello/main.go
.
Open the file in your code editor and change the "Hello" message in the handleRequest
function. You might modify the message to say hello from WebAssembly, your own name, or whatever else you like.
// Send HTTP response
func handleRequest(w http.ResponseWriter, r *http.Request) {
fmt.Fprintf(w, "Hello from Go!\n")
fmt.Fprintf(w, "Hello from Wasm!\n")
}
Modify lib.rs
The Rust code for our component is found in hello/src/lib.rs
.
Open the file in your code editor and change the "Hello" message on line 19. You might modify the message to say hello from WebAssembly, your own name, or whatever else you like.
use wasmcloud_component::http;
struct Component;
http::export!(Component);
impl http::Server for Component {
fn handle(
_request: http::IncomingRequest,
) -> http::Result<http::Response<impl http::OutgoingBody>> {
Ok(http::Response::new("Hello from Rust!\n"))
Ok(http::Response::new("Hello from Wasm!\n"))
}
}
Modify http-hello-world.ts
The TypeScript code for our component is found in hello/http-hello-world.ts
.
Open the file in your code editor and change the "Hello" message on line 23. You might modify the message to say hello from WebAssembly, your own name, or whatever else you like.
// Write hello world to the response stream
outputStream.blockingWriteAndFlush(
new Uint8Array(new TextEncoder().encode('Hello from Typescript!\n'))
new Uint8Array(new TextEncoder().encode('Hello from Wasm!\n'))
);
If you prefer working in a language that isn't listed here, let us know!
Save the modified file. The wash dev
automatically builds and deploys the updated component.
In the terminal, curl
the application again:
curl localhost:8000
Hello from Wasm!
Next steps
We installed wash
, built our first component, and ran our application locally with wash dev
.
In our next tutorial, we'll add pluggable, reusable capabilities like key-value storage to our application.