Setup

Danger

Version 0.0.6 is a complete rewrite to expand the support from Workers to Windows, and enhanced the experience of multiple protocols running on the same channel.

Workex is a solution to RPC in the JS world. You define interfaces in TypeScript, and Workex generates code so that calling a remote context uses the same interface you define.

Workex provides support for these bidirectional RPCs:

  • Between Window and Worker
  • Between 2 Windows, for both same- and cross-origin
    • For example, the main window and iframes, or popouts
  • WebSocket support might be added in the future

The library works as follows:

  • You define the messaging protocol as TypeScript interfaces
  • Run the workex CLI to generate code in your project
  • Use the generated code and the @pistonite/workex SDK library to have seamless RPC - Handshake, protocol agreement, error handling, same- and cross-origin… all handled internally

To get started, install the CLI tool with

cargo install --git https://github.com/Pistonite/workex

After installing, you can run workex --help to see the available options. See the tutorials for a full end-to-end walk-through of running some basic RPC stuff.

TypeScript SDK

The code generated by the workex CLI depends on the @pistonite/workex TypeScript SDK. You can install it with your favorite package manager. For example, for pnpm:

pnpm i @pistonite/workex

The tutorials shows basic examples for using the SDK. You can also refer to the SDK reference when needed.

Note that:

  • The SDK version and workex version should match exactly
  • The SDK is TypeScript-only, so a bundler is needed to consume it.