swiftwasm/bridge-js

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:)) 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], unbridged → JSObject/JSValue. See references/types.md if present.
• Errors: Only throws(JSException) is supported at the bridge; plain throws is not.
• 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: Do not use plain Swift closure types for bridging Swift closures to JavaScript. Use JSTypedClosure when passing or returning Swift closures to JS, and call release() when the closure is no longer needed by JS. When receiving callbacks from JS (e.g. imported APIs), use regular closure types in Swift ((Args) -> Return).

References

• Project setup and config
• Exporting Swift to JS
• Importing JS into Swift (macros)
• Generating from TypeScript
• Supported types (optional)
• Testing
• Limitations