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:

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

[!NOTE] If you're using jco to build components, you should also install componentize-js, which is dynamically imported:

pnpm install @bytecodealliance/componentize-js

Building an example component

Create a TypeScript component project from a WIT file or package directory:

jco scaffold my-component --wit path/to/wit
cd my-component
pnpm install
pnpm check
pnpm test
pnpm build

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.

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

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.