componentize-qjs

Convert JavaScript source code into WebAssembly components using QuickJS.

Overview

componentize-qjs takes a JavaScript source file and a WIT definition, and produces a standalone WebAssembly component that can run on any component-model runtime (e.g. Wasmtime).

Under the hood it:

1. Embeds the QuickJS engine (via rquickjs) as the JavaScript runtime.
2. Uses wit-dylib to generate WIT bindings that bridge the component model and the JS engine.
3. Snapshots the initialized JS state with Wizer so startup cost is paid at build time, not at runtime.
4. Prunes explicitly marked one-time setup code with Walrus and strips debug/build metadata from the snapshotted component.

Prerequisites

Rust 1.97 or later is required by Wasmtime (the wasm32-wasip2 target also needs a recent toolchain for PIC support in wasi-libc).

Installation

Rust CLI (crates.io)

cargo install componentize-qjs-cli --locked

This installs the componentize-qjs command.

Rust CLI (from source)

cargo install --path . --locked

Prebuilt CLI binaries

Prebuilt CLI archives are attached to each GitHub release for Linux, macOS, and Windows.

npm package

npm install componentize-qjs

This pulls in the right prebuilt native binding for your platform via the @andreiltd/componentize-qjs-binding-* optional dependencies.

If you want to build from source run:

cd npm && npm install && npm run build

Quick Start

1. Define a WIT interface (hello.wit):

package test:hello;

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

2. Implement it in JavaScript (hello.js):

JavaScript sources are ES modules. Export WIT functions and interfaces directly from the module.

export function greet(name) {
    return `Hello, ${name}!`;
}

3. Build the component:

componentize-qjs --wit hello.wit --js hello.js -o hello.wasm

4. Run it:

wasmtime run --wasm component-model-async=y --invoke 'greet("World")' hello.wasm
# "Hello, World!"

The built-in runtime published with componentize-qjs includes component-model async support. Pass --sync to embed the built-in non-async runtime instead, producing components that run on hosts without component-model async support. A custom runtime can also be supplied with --runtime.

CLI Reference

componentize-qjs [OPTIONS] --wit <WIT> --js <JS>

Cargo features

Build with features:

cargo build --release --features opt-size

Using Imports

WIT imports are available as ES module imports using their fully-qualified WIT interface name:

// imports.wit
package local:test;

interface math {
    add: func(a: s32, b: s32) -> s32;
    multiply: func(a: s32, b: s32) -> s32;
}

world imports {
    import math;
    export double-add: func(a: s32, b: s32) -> s32;
}

// imports.js
import math from "local:test/math";

export function doubleAdd(a, b) {
    const sum = math.add(a, b);
    return math.multiply(sum, 2);
}

JavaScript modules imported by the entry file are resolved during Wizer initialization. Relative imports are resolved from the entry file path passed to --js; bare package imports are resolved under the read-only module root. By default the CLI uses the current directory when the entry file is under it, or the entry file's parent directory otherwise. Use --module-root <PATH> to expose a project root that contains shared files or node_modules.

WIT Type Mappings

Primitive Types

Compound Types

Imported Resources

Imported resources are exposed as JavaScript classes. Resource methods are called on the handle:

import stdin from "wasi:cli/[email protected]";
import stdout from "wasi:cli/[email protected]";

const input = stdin.getStdin();     // an InputStream
const output = stdout.getStdout();  // an OutputStream

// Methods whose WIT return type is result<...> return the ok payload or throw.
const chunk = input.blockingRead(4096);   // method on the resource (len is a number)
output.blockingWriteAndFlush(chunk);

[static] methods are exposed on the resource class and [constructor] makes the class callable with new.

Owned imported resources support [Symbol.dispose]() for deterministic cleanup. Passing one to a WIT own<T> parameter transfers ownership and invalidates the original wrapper. Borrowed wrappers expire when their component call completes and cannot be transferred or disposed as owners. Resources lent to an in-flight import remain alive and cannot be disposed or transferred until that import completes. Ownership is restored for unconsumed stream/future writes and for imported calls cancelled before they start. Await imports using an incoming borrowed resource before returning from its export.

Cancelling Async Imports

A pending async import exposes a cancel() method on its Promise. Calling it requests cancellation of that import. If cancellation succeeds, the original Promise rejects with async import cancelled; a call that finishes first may still resolve normally. The enclosing export remains active, so its catch/finally blocks can await further host operations. Await the original Promise before releasing resources it borrowed. Call cancel() from the same async export invocation that started the import; it has no effect from another export invocation.

Calls that complete immediately may have no cancel method; use optional chaining when completion timing is unknown. Repeated cancellation is harmless, and a saved cancellation function cannot affect a later call that reuses the same runtime handle.

const pending = service.compute(input);
const abort = () => pending.cancel?.();
signal.addEventListener("abort", abort);
try {
    return await pending;
} finally {
    signal.removeEventListener("abort", abort);
    await service.release();
}

Async Exports

Async exports are declared with the async keyword in WIT and implemented as JavaScript async functions:

package example:greeting;

world greeter {
    export greet: async func(name: string) -> string;
}

export async function greet(name) {
    // You can use await here
    await Promise.resolve();
    return `Hello, ${name}!`;
}

Exported resource methods and static methods may also be async. Implement them as async members on the exported JavaScript class; resource constructors remain synchronous:

package example:counter;

interface counter-api {
    resource counter {
        constructor(initial: u32);
        add: async func(value: u32) -> u32;
        create: static async func(initial: u32) -> counter;
    }
}

world counter {
    export counter-api;
}

class Counter {
    constructor(initial) { this.value = initial; }
    async add(value) { this.value += value; return this.value; }
    static async create(initial) { return new this(initial); }
}

export const counterApi = { Counter };

Streams

Streams transfer a sequence of values between components. Lifted WIT streams implement the JavaScript async-iterable protocol, and async or synchronous iterables are lowered to WIT streams automatically. The stream type is inferred from the function parameter or result:

package example:streaming;

world streaming {
    export uppercase: async func(input: stream<string>) -> stream<string>;
}

export async function uppercase(input) {
    return (async function* () {
        for await (const value of input) {
            yield value.toUpperCase();
        }
    })();
}

Async iteration yields one element at a time, except for stream<u8>, which yields bounded Uint8Array chunks to avoid one promise per byte.

Use the wit.Stream factory when direct access to both endpoints is needed. If only one stream type exists in the WIT world, the type may be omitted:

const { readable, writable } = wit.Stream(wit.Stream.U8);
await writable.writeAll(new Uint8Array([1, 2, 3]));
writable.drop();

wit.Stream.from adapts an iterable explicitly and exposes a completion promise:

const source = (async function* () {
    yield "one";
    yield "two";
})();
const { readable, completion } = wit.Stream.from(source, wit.Stream.STRING);

Available type constants (populated from WIT metadata):

All constructors return { readable, writable }.

Complex element types are also supported. The type constant is generated recursively from the WIT type structure:

// stream<result<string, u32>>
wit.Stream(wit.Stream.RESULT_STRING_U32);

// stream<option<u32>>
wit.Stream(wit.Stream.OPTION_U32);

// stream<tuple<u32, string>>
wit.Stream(wit.Stream.TUPLE_U32_STRING);

// Named record types use their WIT name:
// record point { x: f64, y: f64 }
// stream<point>
wit.Stream(wit.Stream.POINT);

Explicit WIT stream aliases are also exposed as constants:

type prompt-stream = stream<message-chunk>;

wit.Stream(wit.Stream.PROMPT_STREAM);

Use wit.Stream.types or wit.Future.types to discover all available type constants at runtime.

StreamReadable methods:

StreamWritable methods:

Futures

Futures transfer a single value. They work like streams but carry exactly one value:

package example:async-value;

world async-value {
    export compute: async func() -> future<string>;
}

export async function compute() {
    const { readable, writable } = wit.Future();

    // Write the value (fire-and-forget; completes when reader reads)
    writable.write("computed result");

    return readable;
}

Future type constants follow the same pattern: wit.Future.U32, wit.Future.STRING, etc.

Future handles are deliberately not thenable: use await readable.read() to obtain the payload. This keeps return readable in an async export from implicitly consuming the future, and preserves nested future handles. Repeated read() calls share the same Promise; a cancelled read rejects that Promise and allows a subsequent read to retry.

wit.Future.from(value, type) adapts a value or Promise and returns { readable, completion }. Return its readable from an async export rather than returning the payload Promise directly, which JavaScript would await.

FutureReadable methods:

FutureWritable methods:

Resource Cleanup

Owned imported resources, stream endpoints, and future endpoints support Explicit Resource Management via Symbol.dispose. In environments that support using:

{
    const stream = wit.Stream();
    using writable = stream.writable;
    using readable = stream.readable;
    // Each endpoint is disposed when leaving scope.
}

The factory's { readable, writable } pair is not itself disposable. Complete an endpoint's pending operation (or cancel it and await its settlement) before leaving its using scope or calling .drop(). Host-requested task cancellation retains pending ABI buffers until the host acknowledges each operation's completion or cancellation.

Otherwise, call .drop() explicitly to release handles.

Snapshot Initialization

Snapshot creation uses a 1 GiB host-call copy budget to accommodate large module graphs. This allowance belongs to the build-time initializer; execution hosts continue to choose their own budgets for instantiated components.

Node.js API

The npm package exposes both a CLI and a programmatic API.

CLI

npx componentize-qjs --wit hello.wit --js hello.js -o hello.wasm

(Or, if you installed the package globally, just componentize-qjs ....)

Usage

import { componentize } from "componentize-qjs";

const { component } = await componentize({
    witPath: "hello.wit",
    jsSource: "export function greet(name) { return `Hello, ${name}!`; }",
    optSize: true,
});
// component is a Buffer containing the WebAssembly component bytes

Runtime selection is available through optSize, sync, runtime, or runtimeBytes. optSize and sync may be combined to select the non-async opt-size runtime, but neither can be combined with a custom runtime/runtimeBytes. The runtime option is a path to a custom QuickJS runtime Wasm module.

Acknowledgments

This project builds on ideas and code from:

• ComponentizeJS by Joel Dice
• lua-component-demo by Alex Crichton

License

Licensed under Apache-2.0.