百科.dev
全部条目在线工具AI 编程趋势榜开源项目技术资讯提交条目
登录
< 返回工具列表
C

ComponentizeJS

> 编程语言
开源

JS -> WebAssembly 组件

386 stars0 点赞0 次浏览
访问官网GitHub

工具介绍

JS -> WebAssembly 组件

Overview

Provides a Mozilla SpiderMonkey embedding that takes as input a JavaScript source file and a WebAssembly Component WIT World, and outputs a WebAssembly Component binary with the same interface.

Note: This is an experimental project, no guarantees are provided for stability or support and breaking changes may be made in future.

Example

See the end-to-end example workflow for creating a JS component and running it in Wasmtime or Node.js.

Explainer

For background on the concepts involved, see https://bytecodealliance.org/articles/making-javascript-run-fast-on-webassembly.

The goal of this project specifically is to provide a comprehensive dynamic bindings system for creating arbitrary WebAssembly Components from JavaScript. That is, to provide full flexibility over the resultant JS environment and WIT World.

Wizer Pre-Initialization

Adaption follows the standard Wizer technique in pre-initializing a snapshot of the runtime against the source and bindings.

The snapshotting process executes the JS engine initialization, globals and parsing and compiling of the source code. Currently we also evaluate the top-level of the source so that the executed exports of the top-level ES module are provided already initialized.

As a result, at runtime - only the bytecode is being executed, without any initialization costs. This makes on-demand Wasm execution of JS incredibly fast.

SpiderMonkey Embedding

As a dynamic language with quirks, JavaScript cannot be compiled directly into bytecode without including a comprehensive ECMA-262 spec-compliant runtime engine. Componentization of JavaScript thus involves embedding the JS runtime engine into the component itself.

SpiderMonkey is chosen here as a JS engine with first-class WASI build support, using an embedding of the StarlingMonkey Wasm engine. The total embedding size is around 8MB.

One of the security benefits of the component model is complete code isolation apart from the shared-nothing code boundaries between components. By fully encapsulating the engine embedding for each individual component, this maintains comprehensive per-component isolation.

As more components are written in JavaScript, and there exist scenarios where multiple JS components are communicating in the same application, the plan for optimization here is to share the SpiderMonkey engine embedding between them. This can be done without breaking the shared-nothing semantics by having the engine itself loaded as a shared library of the components. Sharing functions via same SpiderMonkey build, not memory.

Establishing this initial prototype as a singular flexible engine foundation that can be turned into a shared library is therefore the focus for this project.

Weval AOT Compilation

Weval ahead-of-time (AOT) compilation can be enabled to improve runtime performance by pre-compiling JavaScript inline caches.

To enable AOT compilation, set the enableAot: true option or use the --aot CLI flag.

AOT compilation can also be configured with the following options:

Option Type Example Description
aotMinStackSizeBytes `number Number bigint

Custom weval binary for AOT

To use a custom (pre-downloaded) weval binary, set the wevalBin option to the path to your desired weval binary.

Platform APIs

The following APIs are available:

  • Legacy Encoding: atob, btoa, decodeURI, encodeURI, decodeURIComponent, encodeURIComponent
  • Streams: ReadableStream, ReadableStreamBYOBReader, ReadableStreamBYOBRequest, ReadableStreamDefaultReader, ReadableStreamDefaultController, ReadableByteStreamController, WritableStream ByteLengthQueuingStrategy CountQueuingStrategy, TransformStream
  • URL: URL, URLSearchParams
  • Console: console
  • Performance: Performance
  • Task: queueMicrotask, setInterval setTimeout clearInterval clearTimeout
  • Location: WorkerLocation, location
  • Encoding: TextEncoder, TextDecoder, CompressionStream, DecompressionStream
  • Structured Clone: structuredClone
  • Fetch: fetch, Request, Response, Headers
  • Forms, Files, and Blobs: FormData, MultipartFormData, File, Blob
  • Crypto: SubtleCrypto, Crypto, crypto, CryptoKey
  • Abort: AbortController, AbortSignal

Usage

Install and run as a Node.js library:

bash
npm install @bytecodealliance/componentize-js
javascript
import { componentize } from '@bytecodealliance/componentize-js';
import { writeFile } from 'node:fs/promises';

const { component } = await componentize(`
  import { log } from 'local:hello/logger';

  export function sayHello (name) {
    log(\`Hello \${name}\`);
  }

`, `
  package local:hello;
  interface logger {
    log: func(msg: string);
  }
  world hello {
    import logger;
    export say-hello: func(name: string);
  }
`);

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

See types.d.ts for the full interface options.

The component itself can be executed in any component runtime, see the example for an end to end workflow in Wasmtime.

Custom wizer binary

To use a custom (pre-downloaded) wizer binary, set the wizerBin option to the path to your desired wizer binary.

Async Support

To support asynchronous operations, all functions may optionally be written as sync or async functions, even though they will always be turned into sync component functions.

For example, to use fetch which requires async calls, we can write the same example component using an async function:

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

ComponentizeJS will automatically resolve promises returned by functions to syncify their return values, running the event loop within the JS component to resolution.

This asynchrony is only supported for exported functions - imported functions can only be synchronous pending component-model-level async support.

CLI

ComponentizeJS can be used as a CLI directly, or via the jco componentize command:

Direct use

bash
npm install -g @bytecodealliance/componentize-js

Example:

bash
componentize-js --wit wit -o component.wasm source.js

See jco componentize --help for more details.

Use via jco componentize

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

Example:

bash
jco componentize source.js --wit wit -o component.wasm

See jco componentize --help for more details.

Features

The set of enabled features in the engine can be customized depending on the target world and expected capabilities.

The default set of features includes:

  • 'stdio': Output to stderr and stdout for errors and console logging, depends on wasi:cli and wasi:io.
  • 'random': Support for cryptographic random, depends on wasi:random. When disabled, random numbers will still be generated but will not be random and instead fully deterministic.
  • 'clocks': Support for clocks and duration polls, depends on wasi:clocks and wasi:io. When disabled, using any timer functions like setTimeout or setInterval will panic.
  • 'http': Support for outbound HTTP via the fetch global in JS.
  • 'fetch-event': Support for fetch based incoming request handling (i.e. addEventListener('fetch', ...))

Setting disableFeatures: ['random', 'stdio', 'clocks', 'http', 'fetch-event'] will disable all features creating a minimal "pure component", that does not depend on any WASI APIs at all and just the target world.

Note that pure components will not report errors and will instead trap, so that this should only be enabled after very careful testing.

Note that features explicitly imported by the target world cannot be disabled - if you target a component to a world that imports wasi:clocks, then disableFeatures: ['clocks'] will not be supported.

Note that depending on your component implementation, some features may be automatically disabled. For example, if using wasi:http/incoming-handler manually, the fetch-event cannot be used.

Using StarlingMonkey's fetch-event

The StarlingMonkey engine provides the ability to use fetchEvent to handle calls to wasi:http/[email protected]#handle.

When targeting worlds that export wasi:http/[email protected] the fetch event will automatically be attached. Alternatively, to override the fetch event with a custom handler, export an explicit incomingHandler or 'wasi:http/[email protected]' object. Using the fetchEvent requires enabling the http feature.

[!WARNING] If using fetch-event, ensure that you do not manually import (i.e. exporting incomingHandler from your ES module).

Modules that export incomingHandler and have the http feature enabled are assumed to be using wasi:http manually.

API

…

Converts a JS source into a component binary.

Imports provides the list of used guest imports only, while the StarlingMonkey engine may pull in additional imports. Direct component analysis should be used to correctly infer the real imports list.

Contributing

To contribute, you'll need to set up the following:

  • git submodule update --init --recursive to update the submodules.
  • Stable Rust with the wasm32-unknown-unknown and wasm32-wasi targets installed.
  • wasi-sdk-20.0 installed at /opt/wasi-sdk/

Building

Building and testing the project can be performed via NPM scripts (see package.json):

bash
npm install
npm run build

Before being able to use componentize-js with AOT support (ex. via npm link, from jco), you'll need to run:

bash
npm run build:weval

(npm run build will also execute the weval build)

This will produce lib/starlingmonkey_embedding_weval.wasm and lib/starlingmonkey_ics.wevalcache.

To clean up a local installation (i.e. remove the installation of StarlingMonkey):

bash
npm run clean

Testing

To run all tests:

bash
npm run test

To run tests with AOT (weval) enabled:

bash
npm run test:weval

Running a specific test

To run a specific test suite, you can pass an argument to vitest:

bash
npm run test -- test/wasi.js

License

This project is licensed under the Apache 2.0 license with the LLVM exception. See LICENSE for more details.

Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in this project by you, as defined in the Apache-2.0 license, shall be licensed as above, without any additional terms or conditions.

Issues· 0 开放

查看全部 Issues在 GitHub 打开

暂无开放 Issues,或尚未同步最近议题。

> 标签

Rust

暂无评论,来聊聊你的看法吧

> 工具信息

发布日期2026年8月1日
最后更新2026年9月17日
分类编程语言
定价开源

> 相关工具

T
TypeScript
JavaScript 的超集,为前端与全栈提供静态类型
P
Python
通用编程语言,广泛用于 Web、数据与 AI
G
Go
Google 推出的简洁高效系统语言