Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Dart Tooling

WebAssembly components in Dart can be built with the wasm_tools package on pub.dev.

This guide walks through building a Dart component that implements an adder world:

package docs:adder@0.1.0;

interface add {
    add: func(x: u32, y: u32) -> u32;
}

world adder {
    export add;
}

Keep in mind that this is a basic intro. For more examples, please see examples from the wasm_tools package or Creating Runnable Components.

If you still have questions, feel free to open an issue on the repository or reach out on Zulip.

1. Create your Dart project

Begin by creating a fresh Dart project:

dart create -t cli dart_wasm_adder
cd dart_wasm_adder

2. Install Dart Component Model tooling

Warning

Compiling Dart to non-web WebAssembly targets is experimental. This guide requires Dart 3.14.0 or later and Wasmtime 47.0.0 or later.

All tools required to create WebAssembly components from Dart can be installed via dart pub:

dart pub add wasm_components hooks dev:wasm_tools

The wasm_components package provides runtime support for the Component Model (like an allocator or async task management), while wasm_tools contains tools to generate Dart code from .wit interface definitions and to compile Dart to components. The hooks package is needed for the link hook.

Tip

The wasm_tools Dart package is not affiliated with the wasm-tools Bytecode Alliance project. You can install both without conflict, as the Dart package is always invoked through dart run wasm_tools.

3. Generate bindings for the Wasm component

Since we will be implementing the adder world, we can copy the WIT to our project. Create a file named adder.wit and paste the following code into it:

package docs:adder@0.1.0;

interface add {
    add: func(x: u32, y: u32) -> u32;
}

world adder {
    export add;
}

Generate Dart code and required metadata for the compiler with

dart run wasm_tools witgen -i adder.wit

After running the generator, the project structure should look like this:

.
├── adder.wit
├── analysis_options.yaml
├── bin
│   └── dart_wasm_adder.dart
├── CHANGELOG.md
├── lib
│   └── src
│       └── components
│           ├── docs_adder_adder.dart
│           ├── docs_adder_adder.json
│           └── docs_adder.dart
├── pubspec.lock
├── pubspec.yaml
└── README.md

All generated code is in lib/src/components. Specifically,

  • docs_adder.dart contains interfaces (only add in this example).
  • docs_adder_adder.dart contains bindings for the adder world.
  • docs_adder_adder.json contains metadata used to turn WebAssembly modules emitted by dart2wasm into components.

The JSON file describes which component imports and exports a Dart program needs. The toolchain reads it via link hooks.

All packages defining component imports or exports need a link hook, including the dart_wasm_adder package. Create a hook/link.dart file with these contents:

import 'dart:convert';
import 'dart:io';

import 'package:hooks/hooks.dart';
import 'package:wasm_tools/hooks.dart';

void main(List<String> args) => link(args, (input, output) async {
  if (input.config.buildWasmComponent) {
    final abi = input.packageRoot.resolve('lib/src/components/docs_adder_adder.json');

    output.dependencies.add(abi);
    output.assets.webAssemblyComponents.add(
      WasmComponentAsset(
        encoded: json.decode(
          File(abi.toFilePath()).readAsStringSync(),
        ) as Map<String, Object?>,
      ),
    );
  }
});

5. Implement the add function

Part of the docs_adder_adder.dart file generated with dart run wasm_tools witgen is the adderComponent function used to define this component: It receives imported interfaces as parameters (in this case, there aren’t any) and returns the exported interface.

For this example, replace bin/dart_wasm_adder.dart with:

import 'package:dart_wasm_adder/src/components/docs_adder.dart';
import 'package:dart_wasm_adder/src/components/docs_adder_adder.dart';

void main() {
  // For components, main() should only contain a single call to a generated
  // component function.
  adderComponent((_) {
    // This callback returns exported interfaces (only Add in this case). It
    // also receives imports through its parameter, in this example the adder
    // world has none.
    return const _Add();
  });
}

final class const _Add() implements Add {
  @override
  int add({required int x, required int y}) {
    return x + y;
  }
}

6. Running the add component

With all generated bindings set up, the component can be compiled:

dart run wasm_tools compile bin/dart_wasm_adder.dart

This creates bin/dart_wasm_adder.wasm, a component we can invoke from the CLI with wasmtime:

$ wasmtime run --invoke 'add(1, 2)' bin/dart_wasm_adder.wasm
3

With this, we have successfully built and run a basic WebAssembly component with Dart 🎉