raw
current commit
261029.1 · docs: fix typos in documentation
<(git log)

Contributing to the Codebase

Development is based on a standard NodeJS workflow, with pnpm as the package manager, i.e.:

pnpm install
pnpm run build
pnpm run test

Prerequisites

Required prerequisites for building jco include:

Rust Toolchain

The latest Rust stable toolchain can be installed using rustup.

Specifically:

rustup toolchain install stable
rustup target add wasm32-wasi

In case you do not have rustup installed on your system, please follow the installation instructions on the official Rust website based on your operating system

Project Structure

jco is effectively a monorepo consisting of the following projects:

Files that should be checked in

The repository is for project related code only – avoid checking in files related to specific platforms or IDEs. One off configuration and/or secrets should of course not be checked in either.

If there is information/configuration that is important for users or developers to see, include them in documentation and/or examples with appropriate context/explanation.

Building

To build jco, run:

pnpm install
pnpm run build

Testing

There are three test suites in jco:

warning

!WARNING Generally, when running jco tests, you will want to build the project first during a test run, to ensure the latest version of Rust code (i.e. js-component-bindgen is in use):

cd packages/jco
pnpm run build
pnpm run test api.js

The command above runs a single test file – the name of the file is relative to packages/jco/test.

Browser test setup

Install Chrome and select the installed executable before running browser tests:

export PUPPETEER_EXECUTABLE_PATH="$(node scripts/install-puppeteer.mjs)"

The installer downloads the current stable Chrome release by default. Set PUPPETEER_VERSION to an exact Chrome for Testing version to pin the installation. The script prints the executable path to stdout and diagnostics to stderr. GitHub Actions jobs automatically receive PUPPETEER_EXECUTABLE_PATH through GITHUB_ENV, so tests use the installed version even when Puppeteer expects a different revision. This also applies when the browser is already cached.

Testing Rust-side bindgen changes

When working on the Rust bindgen crate (crates/js-component-bindgen), you generally must build jco-transpile to see changes appear in Jco, along with configuring Jco to use the workspace’s version of jco-transpile rather than a released one:

In packages/jco/package.json:

-    "jco-transpile": "X.X.X",
+    "jco-transpile": "workspace:*",

After this has been set, you might run a commands like the following from packages/jco:

pnpm --filter '@bytecodealliance/jco-transpile' build
pnpm run test future-lifts.js

Ensure to reset the jco-transpile dependency to a published version once you’ve finished testing locally

Running specific tests

JS tests are powered by vitest, and a specific test suite can be run by passing the filename to pnpm run test:

cd packages/jco
pnpm run test runtime.js

For example, to run multiple tests in a given folder:

cd packages/jco
pnpm run test test/p3/*.js

Commits

Jco and related subprojects use Conventional Commits. Using Conventional Commits helps the project maintain consistency in commit messages, and powers release automation.

CI enforces that commits are structured in a conventional commit style (see commitlint.config.mjsgithub. Special care must also be taken to ensure PR titles are formatted in a way that matches conventional commits as well, when performing squash merges.

The following types are valid:

The following project scopes are valid:

For changes made to projects in the repository to be included in releases, the appropriate project scope must be applied.

Since changes that should be made to the repo may not always have a project-specific scope, the following scopes can be used as well:

Here are a few example commit messages:

chore(jco): update componentize-js dependency to X.X.X

feat(ci): add commitlint to actions workflows