Contributing to JavaScriptKit

Thank you for considering contributing to JavaScriptKit! We welcome contributions of all kinds and value your time and effort.

Getting Started

Reporting Issues

• If you find a bug, have a feature request, or need help, please open an issue.
• Provide as much detail as possible:
  • Steps to reproduce the issue
  • Expected vs. actual behavior
  • Relevant error messages or logs

Setting Up the Development Environment

Clone the repository:

git clone https://github.com/swiftwasm/JavaScriptKit.git
cd JavaScriptKit

Quick start (recommended)

If you already have an OSS Swift toolchain installed via swiftly, run:

./Utilities/setup-dev.sh

The script verifies prerequisites, installs a matching Wasm Swift SDK from swift-sdk-index, runs make bootstrap, and prints the SWIFT_SDK_ID to use with make unittest. Re-running it is idempotent.

If a .swift-version file is present in the repo root, the script will install that toolchain via swiftly automatically. Create one to pin your local dev toolchain to an indexed release (e.g. echo 6.3.0 > .swift-version). The repo does not track .swift-version; if you'd like git to ignore it locally, add it to .git/info/exclude.

Manual setup

1. Install an OSS Swift toolchain via swiftly.
2. Install the Swift SDK for Wasm corresponding to the Swift version:

   (
     set -eo pipefail; \
     V="$(swiftc --version | head -n1)"; \
     TAG="$(curl -sL "https://raw.githubusercontent.com/swiftwasm/swift-sdk-index/refs/heads/main/v1/tag-by-version.json" | jq -e -r --arg v "$V" '.[$v] | .[-1]')"; \
     curl -sL "https://raw.githubusercontent.com/swiftwasm/swift-sdk-index/refs/heads/main/v1/builds/$TAG.json" | \
     jq -r '.["swift-sdks"]["wasm32-unknown-wasip1"] | "swift sdk install \"\(.url)\" --checksum \"\(.checksum)\""' | sh -x
   );
   export SWIFT_SDK_ID=$(
     V="$(swiftc --version | head -n1)"; \
     TAG="$(curl -sL "https://raw.githubusercontent.com/swiftwasm/swift-sdk-index/refs/heads/main/v1/tag-by-version.json" | jq -e -r --arg v "$V" '.[$v] | .[-1]')"; \
     curl -sL "https://raw.githubusercontent.com/swiftwasm/swift-sdk-index/refs/heads/main/v1/builds/$TAG.json" | \
     jq -r '.["swift-sdks"]["wasm32-unknown-wasip1"]["id"]'
   )
   

3. Install dependencies:

   make bootstrap
   

Running Tests

Unit tests running on WebAssembly:

make unittest

Tests for PackageToJS plugin:

swift test --package-path ./Plugins/PackageToJS

Tests for BridgeJS plugin:

swift test --package-path ./Plugins/BridgeJS

This runs both the TS2Swift Vitest suite (TypeScript .d.ts -> Swift macro output) and the Swift codegen/link tests. For fast iteration on the ts2swift tool only, run Vitest directly:

cd Plugins/BridgeJS/Sources/TS2Swift/JavaScript && npm test

To update snapshot test files when expected output changes:

UPDATE_SNAPSHOTS=1 swift test --package-path ./Plugins/BridgeJS

Editing ./Runtime directory

The ./Runtime directory contains the JavaScript runtime that interacts with the JavaScript environment and Swift code. The runtime is written in TypeScript and is checked into the repository as compiled JavaScript files. To make changes to the runtime, you need to edit the TypeScript files and regenerate the JavaScript files by running:

make regenerate_swiftpm_resources

Working with BridgeJS

BridgeJS is a Swift Package Manager plugin that automatically generates Swift bindings from TypeScript definitions. This repository contains pre-generated files created by BridgeJS in AoT (Ahead of Time) mode that are checked into version control.

To update these pre-generated files, use the utility script:

./Utilities/bridge-js-generate.sh

This script runs the BridgeJS plugin in AoT mode (swift package bridge-js) on several SwiftPM packages in this repository.

Run this script when you've made changes to:

• TypeScript definitions
• BridgeJS configuration
• BridgeJS code generator itself

These changes require updating the pre-generated Swift bindings committed to the repository.

Adding new BridgeJS intrinsics:

If you add new @_extern(wasm, module: "bjs") functions to BridgeJSIntrinsics.swift, also add corresponding stub entries to Plugins/PackageToJS/Templates/instantiate.js in the importObject["bjs"] object. This allows packages without BridgeJS-generated code to instantiate successfully.

Support

If you have any questions or need assistance, feel free to reach out via GitHub Issues or Discord.