\n\n## Overview\n\nJco provides a fully native JS toolchain for working with [WebAssembly Components](https://github.com/WebAssembly/component-model) in JavaScript.\n\nFeatures include:\n\n- \"Transpiling\" Wasm Component binaries into ES modules that can run in any JS environment.\n- WASI Preview2 support in Node.js & browsers.\n- Component builds of [Wasm Tools](https://github.com/bytecodealliance/wasm-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.\n- Run and serve commands like Wasmtime, as JS implementations of the Command and HTTP Proxy worlds.\n- \"Componentize\" command to easily create components written in JavaScript (wrapper of [ComponentizeJS](https://github.com/bytecodealliance/ComponentizeJS)).\n\nFor creating components in other languages, see the [Component Model Book](https://component-model.bytecodealliance.org/language-support.html) and [Wit Bindgen](https://github.com/bytecodealliance/wit-bindgen) for various guest bindgen helpers.\n\n## Installation\n\n```shell\npnpm install @bytecodealliance/jco\n```\n\nJco can be used as either a library import or as a CLI via the `jco` command.\n\n## Example\n\nSee the [Example Workflow](https://bytecodealliance.github.io/jco/example.html) page for a full usage example.\n\n## CLI\n\n```shell\nUsage: jco [options]\n\njco - WebAssembly JS Component Tools\n JS Component Transpilation Bindgen & Wasm Tools for JS\n\nOptions:\n -V, --version output the version number\n -h, --help display help for command\n\nCommands:\n scaffold [options] Create a JavaScript or TypeScript WebAssembly component or host-plugin project\n componentize [options] Create a component from a JavaScript or TypeScript module\n transpile [options] Transpile a WebAssembly Component to JS + core Wasm for JavaScript execution\n types [options] Generate types for the given WIT\n guest-types [options] (experimental) Generate guest types for the given WIT\n run [options] [args...] Run a WASI Command component\n serve [options] [args...] Serve a WASI HTTP component\n opt [options] optimizes a Wasm component, including running wasm-opt Binaryen optimizations\n wit [options] extract the WIT from a WebAssembly Component [wasm-tools component wit]\n print [options] print the WebAssembly WAT text for a binary file [wasm-tools print]\n metadata-show [options] [module] extract the producer metadata for a Wasm binary [wasm-tools metadata show]\n metadata-add [options] [module] add producer metadata for a Wasm binary [wasm-tools metadata add]\n parse [options] parses the Wasm text format into a binary file [wasm-tools parse]\n new [options] create a WebAssembly component adapted from a component core Wasm [wasm-tools component new]\n tool Low-level WebAssembly conversion utilities\n embed [options] [core-module] embed the component typing section into a core Wasm module [wasm-tools component embed]\n help [command] display help for command\n```\n\nFor help with individual command options, use `jco --help`.\n\n### Scaffold a new component project\n\n`jco scaffold` creates a regular Node.js project whose source skeleton matches an existing WIT world. By default,\nTypescript, `pnpm`, and both NodeJS and Web targets are used:\n\n```console\njco scaffold my-component --wit path/to/wit\n```\n\n`--wit` accepts a self-contained `.wit` file or WIT package directory and copies it into the project. If dealing with a\nWIT file that contains multiple worlds, supply the `--world` option as well.\n\nIt can also pull a versioned WASI package from the Bytecode Alliance OCI registry. The package and its embedded dependencies are\nexpanded into the generated project's `wit/` directory, so subsequent builds do not access the registry:\n\n```console\njco scaffold my-command --wit wasi:cli@0.3.0 --world wasi:cli/command@0.3.0\n```\n\nUse an `oci://` reference to scaffold from an arbitrary OCI registry package, including WIT-only components:\n\n```console\njco scaffold my-adder --wit oci://ghcr.io/bytecodealliance/docs/adder:0.1.0 --world docs:adder/adder@0.1.0\n```\n\nFor a quick WASI starting point, use one of Jco's bundled WIT packages:\n\n```console\njco scaffold my-command --wit builtin:wasi-command\njco scaffold my-http-service --wit builtin:wasi-proxy\njco scaffold my-reactor --wit builtin:wasi-reactor\n```\n\nThese aliases default to WASI 0.3.0. Use the `@0.2.x` suffix, for example\n`builtin:wasi-command@0.2.x`, to select the latest bundled WASI 0.2 release (currently 0.2.12). Jco copies the bundled\nofficial WASI sources into the generated project's `wit/` directory, so scaffolding does not require network access.\n\nImmediately, you should be able to install and build the component:\n\n```console\ncd my-component\npnpm install\npnpm check\npnpm test\npnpm build\n```\n\nYou can configure scaffolding in various ways:\n\n- `--host` to generate a plugin that provides the selected world's imports for use with `instantiate` (the default\n generates a guest that implements its exports)\n- `--language javascript` to generate a Javscript scaffold (the default is Typescript)\n- `--package-manager npm`/`--package-manager yarn` to use a separate package manager (`pnpm` is the default)\n- `--target nodejs`/`--target web` (can be repeated) to explicitly enable targets (by default both targets are supported)\n\n### Transpile\n\nSee the [Transpiling Docs](https://bytecodealliance.github.io/jco/transpiling.html) for more background and info.\n\n#### Bindgen Crate\n\nTo directly call into the transpilation in Rust, the bindgen used in Jco is also available on crates.io as [js-component-bindgen](https://crates.io/crates/js-component-bindgen).\n\n### Run & Serve\n\nFor Wasm components that implement the WASI Command world, a `jco run` utility is provided to run these applications in Node.js.\n\n```\njco run cowasy.component.wasm hello\n```\n\nBy default, `jco run` retains its historical behavior and gives the component access to the host\nfilesystem, environment, and network. Pass `--sandbox` to deny those capabilities, then grant\nonly those the component needs:\n\n```console\njco run command.wasm --sandbox \\\n --sandbox-env-set HOME=/guest \\\n --sandbox-fs-preopen ./data::/data \\\n --sandbox-net-inherit\n```\n\n`--sandbox-env-set NAME` inherits one variable from the host, while `--sandbox-env-inherit` inherits\nthem all. `--sandbox-fs-preopen HOST[::GUEST]` exposes a directory (using the host path as the guest\npath when it is omitted). The environment and preopen options may be repeated; values are applied\nin command-line order.\n\nUsing the preview2-shim WASI implementation, full access to the underlying system primitives is provided, including filesystem and environment variable permissions.\n\nFor HTTP Proxy components, `jco serve` provides a JS server implementation:\n\n> **Warning:** `jco serve` is intended for development and testing only. It is not production ready.\n\n```\njco serve --port 8080 server.wasm\n```\n\nBy default, the server reuses one component instance for all requests. Pass `--isolate-requests`\nto run every request in a fresh Node.js worker thread (equivalent to\n`--isolate-requests=worker`):\n\n```\njco serve --isolate-requests --port 8080 server.wasm\n```\n\nWorker isolation gives each request a separate V8 isolate, JavaScript global scope, module cache, and\ncomponent instance. Request and response bodies are streamed through a local HTTP proxy. For lower\noverhead, `--isolate-requests=instance` creates fresh component memories, tables, globals, and resource\ntables while sharing the JavaScript isolate and module cache. Neither mode is a security sandbox or\nisolates external filesystem and network side effects. Both modes have a significant performance cost,\nespecially worker isolation. Instance isolation is generally the faster isolation mechanism; worker\nisolation trades additional worker startup and HTTP proxy overhead for separate JavaScript globals and\nmodule caches. To reduce per-request startup latency without reusing JavaScript state, worker mode\nprewarms 50 one-shot workers by default; configure this with `--isolate-worker-pool-size`. See the\n[development-use `jco serve` benchmark](https://bytecodealliance.github.io/jco/performance/benchmarks/development-use-jco-serve.html)\npage for benchmark results and reproduction instructions.\n\n> [Wasmtime](https://github.com/bytecodealliance/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.\n\n### Componentize\n\n> **Note**: `jco componentize` is considered experimental, and breaking changes may be made without notice.\n\nTo componentize a JavaScript file run:\n\n```\njco componentize app.js --wit wit -n world-name -o component.wasm\n```\n\nBy default, [StarlingMonkey][sm] is the default componentization backend, but alternative backends can be\nselected with the `--backend` option, for example [QuickJS-NG][qjs-ng] via [`componentize-qjs`][cqjs]\n(i.e. `--backend quickjs` or `--backend qjs`):\n\n```\njco componentize app.js --wit wit -n world-name -o component.wasm --backend qjs\n```\n\nQuickJS uses an async-capable runtime by default, even for synchronous WIT worlds. For synchronous\ncomponents targeting hosts without async support, such as Node.js 22 when running Jco-generated\nJavaScript, add `--backend-qjs-disable-async` to select the non-async runtime.\n\nThe accepted backend names are `starlingmonkey`/`sm`, `quickjs`/`qjs`, and `perry`. The existing `--engine `\noption supplies a custom StarlingMonkey build and is valid only with the StarlingMonkey backend.\n\nWith StarlingMonkey and QuickJS, TypeScript entry modules are transformed and bundled automatically:\n\n```\njco componentize app.ts --wit wit -n world-name -o component.wasm\n```\n\nThe TypeScript transform erases types but does not perform semantic type checking. Run `tsc --noEmit`\nseparately when required.\n\n#### Experimental Perry backend\n\nPerry is selected independently of Jco. Use a WASI-enabled source-built CLI:\n\n```sh\njco componentize app.ts --backend perry --backend-perry-cli-path /path/to/perry -o component.wasm\njco transpile component.wasm --bindgen-enable-wasm-exnref -o transpiled\n```\n\nWithout a CLI path, Jco resolves `@perryts/perry` from the source project. Use\n`--backend-perry-package ` for an npm alias or a local package; the two\nselectors are mutually exclusive. Jco checks WASI support with an isolated\n`--target wasi --no-link` compile before compiling the application. Failed checks\nidentify the CLI and explain how to select a WASI-enabled build. Perry compiles\nthe original source and supported Node-style APIs to\nWASI P2; Jco's bundler and Node adapters are not enabled. Omit `--wit` and\n`--world-name`: custom WIT bindings are not supported upstream yet.\n\nPerry's published `0.5.1520` release does not include the WASI target. A compiler\nbuilt with `target-wasi`, its matching runtime and wasi-sdk are required. See the\n[Perry backend guide](https://bytecodealliance.github.io/jco/perry.html) for setup,\nguest declaration generation, a filesystem example on ordinary Node, limitations,\nand dependency-management tradeoffs.\n\n#### Experimental Node.js built-in compatibility\n\n> **Warning:** Node.js builtin compatibility in components is experimental. Its\n> APIs and generated component requirements may change incompatibly before the\n> feature is stabilized.\n\nBundled source can keep ordinary supported `node:` imports. See the Jco book's\n[Node.js built-in compatibility guide](https://bytecodealliance.github.io/jco/interop/nodejs-builtins.html)\nfor the current API inventory, implementation choices, WIT requirements, host\nadapter policy, limitations, and examples.\n\nSee [ComponentizeJS][cjs] and [componentize-qjs][cqjs] for backend-specific details.\n\n[sm]: https://github.com/bytecodealliance/StarlingMonkey\n[qjs-ng]: https://github.com/quickjs-ng/quickjs\n[cjs]: https://github.com/bytecodealliance/componentize-js\n[cqjs]: https://github.com/andreiltd/componentize-qjs\n\n## API\n\n#### `transpile(component: Uint8Array, opts?): Promise<{ files: Record }>`\n\nTranspile a Component to JS.\n\n#### `opt(component: Uint8Array, opts?): Promise<{ component: Uint8Array }>`\n\nOptimize a Component with the [Binaryen Wasm-opt](https://www.npmjs.com/package/binaryen) project.\n\n#### `componentWit(component: Uint8Array, document?: string): string`\n\nExtract the WIT world from a component binary.\n\n#### `print(component: Uint8Array): string`\n\nPrint the WAT for a Component binary.\n\n#### `metadataShow(wasm: Uint8Array): Metadata`\n\nExtract the producer toolchain metadata for a component and its nested modules.\n\n#### `parse(wat: string): Uint8Array`\n\nParse a compoment WAT to output a Component binary.\n\n#### `componentNew(coreWasm: Uint8Array | null, adapters?: [String, Uint8Array][]): Uint8Array`\n\n\"WIT Component\" Component creation tool, optionally providing a set of named adapter binaries.\n\n#### `componentEmbed(coreWasm: Uint8Array | null, wit: String, opts?: { stringEncoding?, dummy?, world?, metadata? }): Uint8Array`\n\n\"WIT Component\" Component embedding tool, for embedding component types into core binaries, as an advanced use case of component generation.\n\n#### `metadataAdd(wasm: Uint8Array, metadata): Uint8Array`\n\nAdd new producer metadata to a component or core Wasm binary.\n\n## Contributing\n\nSee the [Contributing](https://bytecodealliance.github.io/jco/contributing.html) chapter of the Jco book.\n\n# License\n\nThis project is licensed under the Apache 2.0 license with the LLVM exception.\nSee [LICENSE](LICENSE) for more details.\n\n### Contribution\n\nUnless you explicitly state otherwise, any contribution intentionally submitted\nfor inclusion in this project by you, as defined in the Apache-2.0 license,\nshall be licensed as above, without any additional terms or conditions.\n","readmeFilename":""}
![\"build](\"https://github.com/bytecodealliance/jco/workflows/CI/badge.svg\"){kind=icon}
\n