Wasm Shell Configuration

Wasm Shell uses two configuration files:

• User configuration that is local to the machine
• Project configuration in the .wash directory at the root of each project

User configuration

By default, user configuration files are found at $HOME/.config/wash/config.json.

Under construction

This section is under active development—please check back soon for a more complete reference.

Project configuration

Projects can be configured via a project config file that resides in the .wash directory at the project root, and which may be expressed in JSON, YAML, or TOML (.json, .yaml, .yml, or .toml).

When you run wash build or wash dev, Wasm Shell will automatically generate a config.yaml file.

Wasm Shell builds WebAssembly component binaries by wrapping language-specific utilities like cargo, go, npm, etc, and project configuration files are commonly used to define configuration for builds.

Configuration for custom builds

Wasm Shell executes the build command for your language toolchain with opinionated defaults. You can override Wasm Shell's default build command by defining a custom build command. For example:

json

{
  "build": {
    "custom": {
      "command": ["cargo", "build", "--target=wasm32-wasip2", "--color=always"]
    }
  }
}

Configuration for TinyGo builds

TinyGo builds require a configuration file in order to specify the WIT world used by the component.

If you attempt to build without a configuration file, wash will generate a config.yaml file at ./.wash/config.yaml and return this message:

text

TinyGo builds require wit_world to be specified in the configuration. A config file has been created at ./.wash/config.yaml with a placeholder. Please update the wit_world field to match your WIT world name.

A simple config.yaml file looks like this:

yaml

version: 2.0.0-rc.5
build:
  tinygo:
    target: wasip2
    build_flags: []
    disable_go_generate: false
    scheduler: asyncify
    gc: conservative
    opt: z
    panic: print
    tags: []
    no_debug: true
    wit_world: PLACEHOLDER_WIT_WORLD
  component_path: build/output.wasm
wit:
  registries: []
  skip_fetch: true
  wit_dir: null
  sources: {}

The same configuration can be expressed in JSON:

json

{
  "build": {
    "tinygo": {
      "target": "wasip2",
      "build_flags": [],
      "disable_go_generate": false,
      "scheduler": "asyncify",
      "gc": "conservative",
      "opt": "z",
      "panic": "print",
      "tags": [],
      "no_debug": true,
      "wit_world": "PLACEHOLDER_WIT_WORLD"
    },
    "artifact_path": "build/output.wasm"
  }
}

The wit_world field of the configuration file should specify the root WIT world in your ./wit subfolder, often contained in a world.wit file.

In the example below, the WIT world is hello:

wit

package wasmcloud:hello;
world hello {
  include wasmcloud:component-go/imports@0.1.0;
  import wasi:logging/logging@0.1.0-draft;
  import wasi:keyvalue/atomics@0.2.0-draft;
  import wasi:keyvalue/store@0.2.0-draft;
  export wasi:http/incoming-handler@0.2.0;
}

The component should compile after updating the configuration file:

json

{
  "build": {
    "tinygo": {
      "target": "wasip2",
      "build_flags": [],
      "disable_go_generate": false,
      "scheduler": "asyncify",
      "gc": "conservative",
      "opt": "z",
      "panic": "print",
      "tags": [],
      "no_debug": true,
      "wit_world": "PLACEHOLDER_WIT_WORLD"
      "wit_world": "hello"
    },
    "artifact_path": "build/output.wasm"
  }
}

TinyGo builds use Go, TinyGo, and wasm-tools. Configuration fields for TinyGo builds include:

• target: Virtual architecture target for the WebAssembly binary. [default: wasip2]
• build_flags: TinyGo build flags
• disable_go_generate: Boolean setting for automatically generating Go bindings from WIT interfaces. [default: false]
• scheduler: Scheduler to use for TinyGo builds. Note: asyncify is a Wasm-specific scheduler and should be used in most cases. (See TinyGo options for more details.) [default: asyncify]
• gc: Memory manager selection. (See TinyGo options for more details.) [default: conservative]
• opt: Optimization level. (See TinyGo options for more details.) [default: z]
• panic: Panic strategy. (See TinyGo options for more details.) [default: print]
• tags: Go build tags
• no_debug: Boolean setting for debug mode [default: true]
• wit_world: Target WIT world
• artifact_path: Target path for WebAssembly binary output [default: build/output.wasm]

Common issues

For solutions to common issues with TinyGo builds, see the Frequently Asked Questions (FAQ).

Configuration for Rust builds

When you build a WebAssembly component from a Rust project, wash automatically generates a config.yaml file at ./.wash/config.yaml:

yaml

version: 2.0.0-rc.5
build:
  rust:
    target: wasm32-wasip2
    cargo_flags: []
    release: false
    features: []
    no_default_features: false

The same configuration can be expressed in JSON:

json

{
  "build": {
    "rust": {
      "target": "wasm32-wasip2",
      "cargo_flags": [],
      "release": false,
      "features": [],
      "no_default_features": false
    }
  }
}

Configuration fields for Rust builds include:

• target: Virtual architecture target for the WebAssembly binary [default: wasm32-wasip2]
• cargo_flags: cargo build flags
• release: Boolean setting for building in release mode [default: false]
• features: Defined features
• no_default_features: Boolean setting for excluding default features [default: false]

Configuration for TypeScript builds

When you build a WebAssembly component from a TypeScript project, wash automatically generates a config.yaml file at ./.wash/config.yaml:

yaml

version: 2.0.0-rc.5
build:
  typescript:
    package_manager: npm
    build_command: build
    build_flags: []
    skip_install: false
    source_maps: false

The same configuration can be expressed in JSON:

json

{
  "build": {
    "typescript": {
      "package_manager": "npm",
      "build_command": "build",
      "build_flags": [],
      "skip_install": false,
      "source_maps": false
    }
  }
}

Configuration fields for TypeScript builds include:

• package_manager: Package manager to use for builds [default: npm]
• build_command: Command to use for builds [default: build]
• build_flags: TypeScript build flags
• skip_install: Boolean setting for skipping initial install step [default: false]
• source_maps: Boolean setting for generating source maps [default: false]