Motivation

Currently, importing JavaScript APIs from the global scope requires users to write TypeScript declaration files and import APIs through the standard BridgeJS workflow. For simple use cases where users only need to access a few well-known global APIs like console.log() or document.getElementById(), this approach can feel heavyweight and requires additional setup steps.

Proposed Solution

Allow users to declare global scope imports directly in Swift using @JS var declarations with protocol interfaces, eliminating the need for separate .d.ts files for simple global API access.

High-level API

@JS protocol JSConsole {
    func log(_ message: String) throws(JSException)
    func error(_ message: String) throws(JSException)
}

@JSGetter(from: .global) var console: JSConsole

@JS class JSElement {
    var innerHTML: String { get set }
    func addEventListener(_ event: String, _ handler: @escaping () -> Void) throws(JSException)
}

@JS protocol JSDocument {
    func getElementById(_ id: String) throws(JSException) -> JSElement?
}

@JS(from: .global, jsName: "document") var jsDocument: JSDocument

@JSImport(from: .module("uuid"), jsName: "v4")
func uuidv4() throws(JSException) -> String

@JSImport(from: .module("./custom-component.js"), jsName: "defineCustomComponents")
func jsDefineCustomComponents() throws(JSException)

@JS func run() {
    print(uuidv4())
    jsDefineCustomComponents()
}

Implementation

This feature would require adding a macro plugin to support @JS var [name]: [Type] declarations that generates getter/setter accessors interacting with the code generated by @JS protocol

If it works well, we might be able to make ImportTS just to generate @JS annotated Swift code and centralize ABI-facing code in ExportSwift