Repository files navigation

Jco provides a fully native JS toolchain for working withWebAssembly Components in JavaScript.

Features include:

• "Transpiling" Wasm Component binaries into ES modules that can run in any JS environment.
• WASI Preview2 support in Node.js & browsers (experimental).
• Component builds ofWasm Tools helpers, available for use as a library or CLI commands for use in native JS environments, as well as optimization helper for Components via Binaryen.
• Run and serve commands like Wasmtime, as JS implementations of the Command and HTTP Proxy worlds.
• "Componentize" command to easily create components written in JavaScript (wrapper ofComponentizeJS).

For creating components in other languages, see theCargo Component project for Rust andWit Bindgen for various guest bindgen helpers.

npm install @bytecodealliance/jco

Jco can be used as either a library import or as a CLI via thejco command.

See theExample Workflow page for a full usage example.

Usage: jco<command> [options]jco - WebAssembly JS Component Tools      JS Component Transpilation Bindgen& Wasm Toolsfor JSOptions:  -V, --version                         output the version number  -h, --help                            displayhelpforcommandCommands:  componentize [options]<js-source>    Create a component from a JavaScript module  transpile [options]<component-path>  Transpile a WebAssembly Component to JS + core Wasmfor JavaScript execution  types [options]<wit-path>            Generate typesfor the given WIT  guest-types [options]<wit-path>      (experimental) Generate guest typesfor the given WIT  run [options]<command> [args...]     Run a WASI Command component  serve [options]<server> [args...]    Serve a WASI HTTP component  opt [options]<component-file>        optimizes a Wasm component, including running wasm-opt Binaryen optimizations  wit [options]<component-path>        extract the WIT from a WebAssembly Component [wasm-tools component wit]  print [options]<input>               print the WebAssembly WAT textfor a binary file [wasm-tools print]  metadata-show [options] [module]      extract the producer metadatafor a Wasm binary [wasm-tools metadata show]  metadata-add [options] [module]       add producer metadatafor a Wasm binary [wasm-tools metadata add]  parse [options]<input>               parses the Wasm text format into a binary file [wasm-tools parse]  new [options]<core-module>           create a WebAssembly component adapted from a component core Wasm [wasm-tools component new]  embed [options] [core-module]         embed the component typing section into a core Wasm module [wasm-tools component embed]help [command]                        displayhelpforcommand

For help with individual command options, usejco <cmd> --help.

See theTranspiling Docs for more background and info.

To directly call into the transpilation in Rust, the bindgen used in Jco is also available on crates.io asjs-component-bindgen.

For Wasm components that implement the WASI Command world, ajco run utility is provided to run these applications in Node.js.

jco run cowasy.component.wasm hello

Using the preview2-shim WASI implementation, full access to the underlying system primitives is provided, including filesystem and environment variable permissions.

For HTTP Proxy components,jco serve provides a JS server implementation:

jco serve --port 8080 server.wasm

Wasmtime generally provides the most performant implementation for executing command and proxy worlds to use. These implementations are rather for when JS virtualization is required or the most convenient approach.

Note:jco componentize is considered experimental, and breaking changes may be made without notice.

To componentize a JS file run:

jco componentize app.js --wit wit -n world-name -o component.wasm

Creates a component from a JS module implementing a WIT world definition, via a Spidermonkey engine embedding.

SeeComponentizeJS for more details on this process.

Transpile a Component to JS.

Optimize a Component with theBinaryen Wasm-opt project.

Extract the WIT world from a component binary.

Print the WAT for a Component binary.

Extract the producer toolchain metadata for a component and its nested modules.

Parse a compoment WAT to output a Component binary.

"WIT Component" Component creation tool, optionally providing a set of named adapter binaries.

"WIT Component" Component embedding tool, for embedding component types into core binaries, as an advanced use case of component generation.

Add new producer metadata to a component or core Wasm binary.

See theContributing chapter of the Jco book.

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

Unless you explicitly state otherwise, any contribution intentionally submittedfor 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.