
bridge-js
Assist Swift developers using BridgeJS for Swift-to-JavaScript interoperability in WebAssembly projects
- GitHub stars
- 49
Install
/plugin install bridge-js@swiftwasm-skillsRun it inside Claude Code after adding the marketplace with /plugin marketplace add swiftwasm/Swift-Wasm-Agent-Skill.
Contents
Discovered from sourceSkills 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 likedocument/console; inject other implementations viagetImports(). See references/importing.md. (2) Or usebridge-js.d.tsto 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; plainthrowsis not. - Async: Exported
asyncfunctions/methods/closures becomePromise-returning JS functions (requireJavaScriptEventLoop.installGlobalExecutor()). Imported standalone@JSFunctioncannot 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--helpfor 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 viaFinalizationRegistry. Closure signatures may bethrows(JSException)and/orasync. 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
- Check Wasm compatibility of Swift packages
- Identify incompatible frameworks such as:
- UIKit
- SwiftUI
- CoreGraphics
- CoreML
- URLSession
- Accelerate
- Refactor code for Wasm compatibility using conditional compilation (
#if os(WASI)) - Build and test Swift projects with the Wasm toolchain
- 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
- Analyze the target Swift package or file for Wasm compatibility issues
- Identify any incompatible frameworks or APIs being used
- Propose refactoring using conditional compilation:
#if canImport(Accelerate) import Accelerate // iOS/macOS implementation #else // Wasm-compatible fallback #endif - Implement the changes
- Build with the Wasm toolchain to verify
Sponsors
Details
- Marketplace
- swiftwasm/Swift-Wasm-Agent-Skill
- Category
- Development
- Keywords
- swift, webassembly, bridgejs, wasm, interop