ComponentizeJS Documentation

ComponentizeJS allows you to write exported functions as async functions, even though they are converted into synchronous component functions at the Wasm level.

When an exported function returns a Promise (e.g., when using fetch), ComponentizeJS automatically resolves the promise by running the event loop within the JS component until the value is ready.

Note: This asynchrony is only supported for exported functions. Imported functions must remain synchronous as component-model-level async support is not yet available.

export async function sayHello (name) {
  const text = await (await fetch(`http://localhost:8080/${name}`)).text();
  console.log(text);
}

When targeting worlds that export wasi:http/incoming-handler@0.2.0, the fetch-event is automatically attached. This allows you to handle incoming requests using addEventListener('fetch', ...).

Requirements:

• The http feature must be enabled.

Warning: If you use fetch-event, do not manually export an incomingHandler or a 'wasi:http/incoming-handler@0.2.0' object from your ES module. If both are present, the engine assumes you are managing wasi:http manually.

To create a WebAssembly component from JavaScript, you need a .wit file defining the interface (world) and a .js file that implements that interface. Use the componentize function from @bytecodealliance/componentize-js to transform the JavaScript source and WIT definition into a .wasm component.

1. Define your interface in a .wit file.
2. Implement the interface in a .js file.
3. Use the componentize API to generate the component buffer.

import { componentize } from '@bytecodealliance/componentize-js';
import { readFile, writeFile } from 'node:fs/promises';

const jsSource = await readFile('hello.js', 'utf8');
const witSource = await readFile('hello.wit', 'utf8');

const { component } = await componentize(jsSource, witSource);

await writeFile('hello.component.wasm', component);

To build a WebAssembly component from a Javascript (ES) module, you must first ensure your module conforms to a WebAssembly Interface Types (WIT) interface. The JS exports are implicitly mapped to the WIT world exports.

For example, if your hello.wit defines:

package local:hello;

world component {
  export hello: func(name: string) -> string;
}

Your hello.js should export a function with the same name:

export function hello (name) {
  return `Hello ${name}`;
}

To build the component:

1. Navigate to the guest directory.
2. Install dependencies using npm install.
3. Run the build process using node componentize.js or the pre-configured npm run build script.

Because components may not always export a standardized execution interface (like WASI CLI), you may need to use a custom host embedding a runtime like wasmtime.

To run the component manually using the provided Rust host:

1. Navigate to the host directory.
2. Execute cargo run to run the custom embedding.

To build the project locally using NPM:

npm install
npm run build

If you need to use componentize-js with AOT support (for example, via npm link or jco), you must also build weval:

npm run build:weval

This produces lib/starlingmonkey_embedding_weval.wasm and lib/starlingmonkey_ics.wevalcache.

To clean up a local installation and remove StarlingMonkey:

npm run clean

Use the following commands to run tests:

• All tests: npm run test
• Tests with AOT (weval) enabled: npm run test:weval
• Specific test suite: Pass the file path as an argument to vitest via npm:

npm run test -- test/wasi.js

You can install ComponentizeJS as a Node.js library for programmatic use, or install it globally to use it as a CLI tool.

As a Node.js library:

npm install @bytecodealliance/componentize-js

As a global CLI tool:

npm install -g @bytecodealliance/componentize-js

Via jco:

npm install -g @bytecodealliance/jco @bytecodealliance/componentize-js

To run the generated .wasm component in Wasmtime, you must set up a Rust host environment.

1. Configure your Cargo.toml as shown in the examples/hello-world/host/ directory.
2. Implement the host logic in src/main.rs following the examples/hello-world/host/src/main.rs template.
3. Build and run the host binary using cargo build --release.

cargo build --release
./target/release/wasmtime-test

The project uses interface_name_from_string to derive JavaScript-friendly names from Wasm interface identifiers.

1. It extracts the part after the last /.
2. It identifies the version/alias part after the @ symbol.
3. The base name is converted to lowerCamelCase.
4. If a version/alias exists (e.g., name@version), the resulting name is formatted as {alias}_{version_with_underscores} (where dots and dashes in the version are replaced by underscores).

fn interface_name_from_string(name: &str) -> Option<String> {
    // ... implementation details ...
}