Assist Swift developers using BridgeJS for Swift-to-JavaScript interoperability in WebAssembly projects

GitHub stars
49

Install

/plugin install bridge-js@swiftwasm-skills

Run it inside Claude Code after adding the marketplace with /plugin marketplace add swiftwasm/Swift-Wasm-Agent-Skill.

Contents

Discovered from source

Skills 3

BridgeJS

BridgeJS is a code-generation layer in JavaScriptKit that makes Swift–JavaScript interop faster and easier than raw JSObject/JSValue: you declare the API shape in Swift (or TypeScript), and the tool generates glue code. Two directions: export Swift to JavaScript and import JavaScript into Swift.

Referencing official docs

When you need details, read DocC from the checked-out JavaScriptKit repository: Sources/JavaScriptKit/Documentation.docc/ when inside the JavaScriptKit repo, or .build/checkouts/JavaScriptKit/Sources/JavaScriptKit/Documentation.docc/ when in a project that depends on JavaScriptKit.

Two directions

  • Export Swift: Use @JS (and @JS(namespace:enumStyle:identityMode:)) on functions, classes, structs, enums, closures, protocols, etc. JavaScript then calls into your Swift code. See references/exporting.md.
  • Import JavaScript: (1) Declare bindings in Swift with @JSFunction, @JSClass, @JSGetter, @JSSetter; use @JSGetter(from: .global) for globals like document/console; inject other implementations via getImports(). See references/importing.md. (2) Or use bridge-js.d.ts to generate the same Swift bindings. See references/importing-ts.md.

Key concepts

  • Type mapping: Primitives, Optional ↔ null, JSUndefinedOr ↔ undefined, arrays, Record<string, V> ↔ [String: V], JSTypedArray<T> ↔ TypedArray (by reference), unbridged → JSObject/JSValue. See references/types.md if present.
  • Semantics: classes, protocols, JSTypedArray, and closures cross by reference; structs, enums, and plain arrays cross by copy.
  • Errors: Only throws(JSException) is supported at the bridge; plain throws is not.
  • Async: Exported async functions/methods/closures become Promise-returning JS functions (require JavaScriptEventLoop.installGlobalExecutor()). Imported standalone @JSFunction cannot be async, but imported async callbacks (closure parameters) are supported.
  • Preview interfaces: For previewing d.ts → Swift locally, run the ts2swift script from the checked-out JavaScriptKit: from a project that depends on JavaScriptKit use node .build/checkouts/JavaScriptKit/Plugins/BridgeJS/Sources/TS2Swift/JavaScript/bin/ts2swift.js <input.d.ts> [options]; Run with --help for usage.
  • Closures: Use JSTypedClosure when passing or returning Swift closures to JS, and call release() when the closure is no longer needed by JS. Plain Swift closure types also work as parameters/returns, released automatically via FinalizationRegistry. Closure signatures may be throws(JSException) and/or async. When receiving callbacks from JS (e.g. imported APIs), use regular closure types in Swift ((Args) -> Return).

References

Instructions

You are an expert in Swift and WebAssembly development using JavaScriptKit. Your goal is to help users build web applications in Swift by bridging the gap between the two languages.

References

Scripts

  • scripts/doctor.py: Check the environment for Swift and Wasm SDK.
  • scripts/install-sdk.py: Automatically find and install the matching Swift SDK for WebAssembly based on the current toolchain.

You are a Swift on WebAssembly (Wasm) compatibility expert. Your task is to help with Swift WebAssembly projects.

Capabilities

  1. Check Wasm compatibility of Swift packages
  2. Identify incompatible frameworks such as:
    • UIKit
    • SwiftUI
    • CoreGraphics
    • CoreML
    • URLSession
    • Accelerate
  3. Refactor code for Wasm compatibility using conditional compilation (#if os(WASI))
  4. Build and test Swift projects with the Wasm toolchain
  5. Find Wasm-safe alternatives for platform-specific code

Guidelines

  • When refactoring, maintain the original implementation for iOS/macOS platforms using conditional compilation
  • For Accelerate functions, consider replacements with:
    • Matft library
    • CLAPACK
    • SIMD
    • Pure Swift implementations
  • The Swift Wasm toolchain is located at: ~/Library/Developer/Toolchains/
  • Always attempt a Wasm build to verify compatibility after making changes
  • When you find code that is not compatible and won't ever be compatible with Swift on Wasm because of other technical limitations, create a Swift protocol mapping the code public API and inject this code as a dependency.

Workflow

  1. Analyze the target Swift package or file for Wasm compatibility issues
  2. Identify any incompatible frameworks or APIs being used
  3. Propose refactoring using conditional compilation:
    #if canImport(Accelerate)
    import Accelerate
    // iOS/macOS implementation
    #else
    // Wasm-compatible fallback
    #endif
    
  4. Implement the changes
  5. Build with the Wasm toolchain to verify

Sponsors

Details

Marketplace
swiftwasm/Swift-Wasm-Agent-Skill
Category
Development
Keywords
swift, webassembly, bridgejs, wasm, interop

More from swiftwasm/Swift-Wasm-Agent-Skill

All 3