JavaScriptKit Documentation

When you run swift package --swift-sdk $SWIFT_SDK_ID js, the PackageToJS plugin generates a JavaScript package in .build/plugins/PackageToJS/outputs/Package/. This package contains the compiled WebAssembly module, entry points for different environments, and TypeScript definitions.

Package Structure

.build/plugins/PackageToJS/outputs/Package/
├── ProductName.wasm          # Compiled WebAssembly module
├── index.js                  # Main entry point for browser environments
├── index.d.ts                # TypeScript type definitions for index.js
├── instantiate.js            # Low-level instantiation API
├── instantiate.d.ts          # TypeScript type definitions for instantiate.js
├── package.json              # npm package metadata
└── platforms/
    ├── browser.js            # Browser-specific platform setup
    ├── browser.d.ts          # TypeScript definitions for browser.js
    ├── node.js               # Node.js-specific platform setup
    └── node.d.ts             # TypeScript definitions for node.js

BridgeJS allows you to export Swift enums containing static functions. When you do this, BridgeJS uses a Values/Tag/Object pattern to ensure you can access both the enum constants and the static methods through a single interface in JavaScript.

The Pattern Breakdown:

• Values: A constant object containing the enum cases (e.g., CalculatorValues).
• Tag: A TypeScript type alias representing the enum values (e.g., CalculatorTag).
• Object: An intersection type that combines the Values and the static methods (e.g., CalculatorObject).
• Exports: The final exported object uses the Object type, allowing unified access.

This pattern enables you to call exports.EnumName.CaseName for constants and exports.EnumName.methodName() for functions.

@JS enum Calculator {
    case scientific
    case basic

    @JS static func square(value: Int) -> Int {
        return value * value
    }

    @JS static func cube(value: Int) -> Int {
        return value * value * value
    }
}

The BridgeJS plugin maps TypeScript declarations to Swift using specific macros.

Functions

Exported functions become top-level Swift functions annotated with @JSFunction and throws(JSException).

Global Getters

Module-level declare const or top-level readonly bindings become Swift global properties annotated with @JSGetter.

Classes

Classes become Swift structs annotated with @JSClass:

• Constructor: Becomes init(...) with @JSFunction.
• Properties: Readonly properties use @JSGetter. Read-writable properties use @JSGetter and @JSSetter (as set<Name>(_:)).
• Methods: Become @JSFunction.
• Static Methods: Become static func on the struct.

Interfaces

Interfaces become Swift structs annotated with @JSClass. They do not have constructors; instances are typically obtained via other function calls returning that interface type. Properties and methods are bridged using @JSGetter, @JSSetter, and @JSFunction.

Type Aliases

• Primitive aliases (e.g., type UserId = string): Inlined as the underlying Swift type (e.g., String).
• Object-shaped aliases (e.g., type User = { id: string }): Emitted as a named Swift struct with @JSClass.

String Enums

TypeScript string enums become Swift enums with String raw values, conforming to necessary BridgeJS protocols.

// TypeScript (bridge-js.d.ts)
export class Greeter {
    readonly id: number;
    message: string;
    constructor(id: string, name: string);
    greet(): string;
    static createDefault(greetingId: number, locale: string): string;
}

// Generated Swift
@JSClass struct Greeter {
    @JSGetter var id: Double
    @JSGetter var message: String
    @JSSetter func setMessage(_ newValue: String) throws(JSException)
    @JSFunction init(id: String, name: String) throws(JSException)
    @JSFunction func greet() throws(JSException) -> String
    @JSFunction static func createDefault(_ greetingId: Double, _ locale: String) throws(JSException) -> String
}

By default, every time a Swift object crosses the boundary, a new JavaScript wrapper is created. This means identity checks (===) will fail even if the underlying Swift object is the same.

To ensure that the same Swift object always returns the same JavaScript wrapper, you can enable Identity Mode.

Options for enabling Identity Mode

1. Per-class (Recommended): Use the @JS attribute on the class definition. This has zero overhead for classes that do not use it.

   @JS(identityMode: true)
   class Model { ... }

2. Global Configuration: Enable it for all classes in a target via bridge-js.config.json:

   { "identityMode": "pointer" }

Tradeoffs

• Pros: Improves performance for workloads where the same objects are passed back and forth frequently.
• Cons: Adds overhead for workloads that create many short-lived objects due to the internal cache (Map, WeakRef, FinalizationRegistry) used to maintain identity.

@JS(identityMode: true)
class Model {
    @JS var name: String
    @JS init(name: String) { self.name = name }
}

Use JSTypedClosure to pass or return Swift closures to JavaScript via BridgeJS with compile-time type safety. Unlike the untyped JSClosure, JSTypedClosure requires a concrete signature (e.g., (Int) -> Int).

Use cases:

• Passing a Swift closure as an argument to a JavaScript API (e.g., a callback).
• Returning a Swift closure from a Swift function exported via JS(namespace:enumStyle:) so JavaScript can invoke it later.

Important: You must manually manage the lifetime of a JSTypedClosure by calling release() when it is no longer needed by JavaScript. Failure to do so can lead to memory leaks, and calling it too early will cause JavaScript to throw an exception when attempting to invoke the function.

import JavaScriptKit

// Example: Passing a typed closure to a JS function
@JSFunction static func applyTransform(_ value: Int, _ transform: JSTypedClosure<(Int) -> Int>) throws(JSException) -> Int

let double = JSTypedClosure<(Int) -> Int> { $0 * 2 }
defer { double.release() }
let result = try applyTransform(10, double) // 20