jco

JavaScript tooling for WebAssembly Components

A Bytecode Alliance project

Contributing | Chat on Zulip

Overview

Jco (jco) provides a Javascript-native toolchain for working with WebAssembly Components.

Jco aims to be a convenient multi-tool for the JS WebAssembly ecosystem.

With Jco (and related projects in this repository), you can:

• Scaffold a new JavaScript or TypeScript component project from a WIT world with jco scaffold
• Build WebAssembly components from Javascript/Typescript with componentize-js or componentize-qjs
• "Transpile" WebAssembly components into ES modules that can run in environments like NodeJS and the browser, combining platform-native WebAssembly core support with the advanced features of WebAssembly Components
• Run WebAssembly components whether single-shot applications or web servers (similar to wasmtime run/wasmtime serve)
• Reuse WebAssembly component workflows (e.g. building components, transpiling, etc) from your own JS projects
• Utilize wasm-tools as a library from JS

Organization

As Jco aims to do many things, it contains many subprojects that are organized in this repository:

Subproject	Language	Directory	Description
jco	Javascript	packages/jco	The jco CLI
jco-transpile	Javascript	packages/jco-transpile	WebAssembly Component Transpilation functionaltiy
jco-std	Javascript	packages/jco-std	A "standard library" for Jco which provides integrations for popular JS frameworks/paradigms
jco-node-fs	Rust/JS	packages/jco-node-fs	Native Node.js filesystem helpers used by Jco's WASI shims
preview2-shim	Javascript	packages/preview2-shim	Library that provides a mapping of WASI Preview 2 for NodeJS and Browsers
preview3-shim	Javascript	packages/preview3-shim	Library that provides a mapping of WASI Preview 3 for NodeJS
rolldown-plugin-jco	Javascript	packages/rolldown-plugin-jco	Rolldown and Rollup plugin for importing WebAssembly Components through Jco
js-component-bindgen	Rust	crates/js-component-bindgen	Enables jco transpile and other features, reusing the Rust WebAssembly ecosystem
js-component-bindgen-component	Rust	crates/js-component-bindgen-component	WebAssembly component that (when transpiled) makes js-component-bindgen available in JS jco
wasm-tools-component	Rust	crates/wasm-tools-component	WebAssembly component containing pieces of wasm-tools used by jco

Quickstart

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

To install it, use pnpm:

pnpm install @bytecodealliance/jco

Building an example component

Create a TypeScript component project using Jco's built-in WASI CLI world:

pnpm exec jco scaffold my-command --wit builtin:wasi-command

# Note that you can also scaffold from an existing WIT package
# directory instead:
# jco scaffold my-component --wit path/to/wit

Scaffolding the project wil create a folder called my-command (the first argument to jco scaffold), and you can swith to that folder and instantly build the component:

cd my-command
pnpm install
pnpm check
pnpm test
pnpm build

Note

To see examples of common patterns, check out the example components folder (examples/components).

Jco bundles three common starting points, which default to WASI 0.3:

• builtin:wasi-command uses the wasi:cli/command world from the upstream WASI CLI WIT interfaces
• builtin:wasi-reactor uses the wasi:cli/imports world from the upstream WASI CLI WIT interfaces
• builtin:wasi-proxy uses the wasi:http/service world from the upstream WASI HTTP WIT interfaces

Add the @0.2.x suffix to use the bundled WASI 0.2 interfaces instead, for example builtin:wasi-command@0.2.x. You can also pass a WIT file or package directory to --wit for a custom world.

The generated repository includes everything you need to get started:

• Guest (component) typescript declarations
• Implementation skeleton code
• Node.js & web type-check and build scripts
• Configuration files
• README

Note

See the Jco Book for language, world, target, and package-manager options.

For more instructions on how to build an example component, see the Component model section on Javascript.

Learn more

For a deeper guide on the intricacies of Jco, read the Jco Book.

Installation quirks

Supported NodeJS test matrix

jco and jco-transpile are tested against the current stable version (even numbered release) of NodeJS and two versions before that one (e.g. if the current NodeJS version is 26.x, 24.x and 22.x are covered under CI)

Node 18.x

If installing on Node 18.x with a version of @bytecodealliance/componentize-js 0.18.3 or above, you may need to install oxc-parser manually.

For example, on linux this would mean the following:

pnpm install oxc-parser --ignore-engines
pnpm install @oxc-parser/binding-linux-x64-gnu --ignore-engines

It may be necessary to replace @oxc-parser/binding-linux-x64-gnu with whatever platform is appropriate.

Note

If you are using pnpm instaed of pnpm, similar installation issues may occur when using an npm version older than 11.3.0, due to npm bugs related to optional dependencies

License

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

Contributing

See the Contributing chapter of the Jco book.

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.