Swiftpack.co - Package - swiftwasm/JavaScriptKit

Swiftpack.co is a collection of thousands of indexed Swift packages. Search packages.

swiftwasm/JavaScriptKit

Swift framework to interact with JavaScript through WebAssembly.

JavaScriptKit

Run unit tests

Swift framework to interact with JavaScript through WebAssembly.

Getting started

This JavaScript code

const alert = window.alert;
const document = window.document;

const divElement = document.createElement("div");
divElement.innerText = "Hello, world";
const body = document.body;
body.appendChild(divElement);

const pet = {
  age: 3,
  owner: {
    name: "Mike",
  },
};

alert("JavaScript is running on browser!");

Can be written in Swift using JavaScriptKit

import JavaScriptKit

let document = JSObject.global.document

var divElement = document.createElement("div")
divElement.innerText = "Hello, world"
_ = document.body.appendChild(divElement)

struct Owner: Codable {
  let name: String
}

struct Pet: Codable {
  let age: Int
  let owner: Owner
}

let jsPet = JSObject.global.pet
let swiftPet: Pet = try JSValueDecoder().decode(from: jsPet)

JSObject.global.alert!("Swift is running in the browser!")

Usage in a browser application

The easiest way to get started with JavaScriptKit in your browser app is with the carton bundler.

As a part of these steps you'll install carton via Homebrew on macOS (you can also use the ghcr.io/swiftwasm/carton Docker image if you prefer to run the build steps on Linux). Assuming you already have Homebrew installed, you can create a new app that uses JavaScriptKit by following these steps:

  1. Install carton:
brew install swiftwasm/tap/carton

If you had carton installed before this, make sure you have version 0.6.1 or greater:

carton --version
  1. Create a directory for your project and make it current:
mkdir SwiftWasmApp && cd SwiftWasmApp
  1. Initialize the project from a template with carton:
carton init --template basic
  1. Build the project and start the development server, carton dev can be kept running during development:
carton dev
  1. Open http://127.0.0.1:8080/ in your browser and a developer console within it. You'll see Hello, world! output in the console. You can edit the app source code in your favorite editor and save it, carton will immediately rebuild the app and reload all browser tabs that have the app open.

You can also build your project with webpack.js and a manually installed SwiftWasm toolchain. Please see the following sections and the Example directory for more information in this more advanced use case.

Manual toolchain installation

This library only supports swiftwasm/swift toolchain distribution. The toolchain can be installed via swiftenv, in the same way as the official Swift nightly toolchain.

You have to install the toolchain manually when working on the source code of JavaScriptKit itself, especially if you change anything in the JavaScript runtime parts. This is because the runtime parts are embedded in carton and currently can't be replaced dynamically with the JavaScript code you've updated locally.

Just pass a toolchain archive URL for the latest SwiftWasm 5.3 snapshot appropriate for your platform:

$ swiftenv install https://github.com/swiftwasm/swift/releases/download/swift-wasm-5.3.0-RELEASE/swift-wasm-5.3.0-RELEASE-macos_x86_64.pkg

You can also use the install-toolchain.sh helper script that uses a hardcoded toolchain snapshot:

$ ./scripts/install-toolchain.sh
$ swift --version
Swift version 5.3 (swiftlang-5.3.0)
Target: x86_64-apple-darwin19.6.0

Github

link
Stars: 335
Last commit: 4 days ago

Related Packages

Releases

0.10.0 - 2021-01-21T17:19:04

This release contains multiple breaking changes in preparation for enabling async/await, when this feature is available in a stable SwiftWasm release. Namely:

  • JSClosure.init(_ body: @escaping ([JSValue]) -> ()) overload is deprecated to simplify type checking. Its presence requires explicit type signatures at the place of use. It will be removed in a future version of JavaScriptKit.
  • JSClosure is no longer a subclass of JSFunction. These classes are not related enough to keep them in the same class hierarchy. As a result, you can no longer call JSClosure objects directly from Swift. Call wrapped closures directly instead.
  • Introduced JSOneshotClosure for closures that are going to be called only once. You don't need to manage references to these closures manually, as opposed to JSClosure. However, they can only be called a single time from the JS side. Subsequent invocation attempts will raise a fatal error on the Swift side.
  • Removed generic parameters on JSPromise, now both success and failure values are always assumed to be of JSValue type. This also significantly simplifies type checking and allows callers to fully control type casting if needed.

Closed issues:

  • DOMKit? (#21)

Merged pull requests: