https://github.com/coder/wxnm
A library for providing TypeScript typed communication between your web extension and your native Node application using Native Messaging
https://github.com/coder/wxnm
Last synced: 2 months ago
JSON representation
A library for providing TypeScript typed communication between your web extension and your native Node application using Native Messaging
- Host: GitHub
- URL: https://github.com/coder/wxnm
- Owner: coder
- License: mit
- Created: 2020-01-22T19:23:06.000Z (over 5 years ago)
- Default Branch: master
- Last Pushed: 2021-08-23T19:47:49.000Z (over 3 years ago)
- Last Synced: 2025-02-06T12:11:48.866Z (3 months ago)
- Language: TypeScript
- Size: 191 KB
- Stars: 2
- Watchers: 8
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# (W)eb E(x)tension (N)ative (M)essenger
`wxnm` is a TypeScript library for providing typed communication between your web extension and your native Node application using [Native Messaging](https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/Native_messaging). It also provides some utilities for installing your native application's app manifest.
`wxnm` is meant for long-running applications and uses the [`runtime.connectNative`](https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/API/runtime/connectNative) API under the hood. If your use case only requires infrequent, one-off messages to be sent, it's recommended you use [`runtime.sendNativeMessage`](https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/API/runtime/sendNativeMessage) directly.
## Compatibility
| Browser | Windows | Linux | Mac |
| :------------ | :-----: | :---: | :-: |
| Firefox | ✕ | ✓ | ✓ |
| Waterfox | ✕ | ✓ | ✓ |
| Chrome | ✕ | ✓ | ✓ |
| Chrome Canary | ✕ | | ✓ |
| Chrome Beta | ✕ | ✓ | |
| Chromium | | ✓ | ✓ |
| Brave | ✕ | ✓ | ✓ |
| Opera | ✕ | ✕ | ✓ |
| Vivaldi | ✕ | ✓ | ✓ |
✓ - supported
✕ - not supported
blank - OS does not support this browser
Windows support is a WIP
## Installation
```bash
npm install @coder/wxnm
# or #
yarn add @coder/wxnm
```
## Example
See the [`example` directory](/example) for a full implementation of an extension that talks to a native application to get its process ID.
## Installing your Native Messaging App
Before your extension and your native app can communicate, the app will need to register an application manifest on the user's machine, and the extension will need to declare the `nativeMessaging` permission in its manifest. This library provides an `installManifest` utility to install a manifest for all of the user's currently installed browsers, which you can put somewhere in your app as either its own executable, or run via a flag on your main executable. For instance:
```ts
// If passed --install, install the manifest
const argv = yargs.argv
if (argv.install) {
installManifest({
name: "com.coder.wxnm_example",
description: "Example of the wxnm library",
path: path.resolve("./node/dist/wxnm-node-example"),
chromeExtensionIds: [process.env.CHROME_EXTENSION_ID],
webExtensionIds: ["[email protected]"],
})
process.exit(0)
}
```
See the example for more info.
## Usage
### Types
To get the full effectiveness of `wxnm`, you'll want to create some types that will be shared between your browser extension and your node application. They should look something like this:
```ts
import { NativeMessage } from "@coder/wxnm"
/**
* Messages the extension will send, native app will recieve
*/
interface PingMessage extends NativeMessage {
type: "PING"
message: string
}
export type ExtensionMessages = PingMessage
/**
* Messages the native app will send, extension will receive
*/
interface PongMessage extends NativeMessage {
type: "PONG"
message: string
}
interface ErrorMessage extends NativeMessage {
type: "ERROR"
error: string
}
export type NativeMessages = PongMessage | ErrorMessage
```
### Web Extension
In your web extension, you'll call `createExtensionMessenger` which will allow you to send messages, listen for messages, and listen for disconnects:
```ts
import { createExtensionMessenger } from "@coder/wxnm/extension"
import { ExtensionMessages, NativeMessages } from "../shared/types"
/**
* Create an instance of ExtensionNativeMessenger
*/
const msger = createExtensionMessenger("com.company.name_of_app")
/**
* Handle each message type as it comes in from the app
*/
msger.onMessage((msg: NativeMessages) => {
switch (msg.type) {
case "PONG":
console.log("Got PONG back!", msg.message)
case "ERROR":
console.error("Uh oh!", msg.error)
}
})
/**
* Alert to an error if we unexpectedly disconnect
*/
msger.onDisconnect((err?: Error) => {
if (err) {
console.error("Error with disconnect!", err)
}
})
/**
* Send a ping message to the native app
*/
msger.sendMessage({
type: "PING",
message: "Hello",
})
```
### Native Node Application
The node side looks very similar, with the generics flipped for `createNodeMessenger`:
```ts
import { createNodeMessenger } from "@coder/wxnm/node"
import { ExtensionMessages, NativeMessages } from "../shared/types"
/**
* Create an instance of NodeNativeMessenger
*/
const msger = createNodeMessenger()
/**
* Handle ping messages and respond with a pong message
*/
msger.onMessage((msg: ExtensionMessages) => {
switch (msg.type) {
case "PING":
msger.sendMessage({
type: "PONG",
data: { message: `You said: ${msg.data.message}` },
})
}
})
/**
* Alert to an error if we unexpectedly disconnect
*/
msger.onDisconnect((err?: Error) => {
if (err) {
console.error("Error with disconnect!", err)
}
// Maybe run some cleanup code if you need to as well
})
```
## API
The `wxnm` API is **_not isomorphic_**, so you'll have two import paths depending on which environment you're in.
### @coder/wxnm/extension`
```ts
export class ExtensionNativeMessenger {
/**
* Disconnect from the native app. This will kill the native app process and
* trigger all onDisconnect listeners on both sides.
*/
disconnect(): void
/**
* Add a listener for when you disconnect. Calls to `disconnect` will trigger
* this without an error. Returns an unlistener function.
*/
onDisconnect(listener: (err?: Error) => void): () => void
/**
* Add a listener for when you receive messages from the native app. Returns
* an unlistener function.
*/
onMessage(listener: (msg: NodeMessage) => void): () => void
/**
* Send a message to the native app. Must be JSON serializable.
*/
sendMessage(msg: ExtensionMessage): void
}
/**
* Creates an instance of ExtensionNativeMessenger
*/
export function createExtensionMessenger()
```
### @coder/wxnm/extension
```ts
export class NodeNativeMessenger {
/**
* Add a listener for when the extension disconnects. The app will terminate
* after this runs. Returns an unlistener function.
*/
onDisconnect(listener: (err?: Error) => void): () => void
/**
* Add a listener for when you receive messages from the extension. Returns
* an unlistener function.
*/
onMessage(listener: (msg: NodeMessage) => void): () => void
/**
* Send a message to the extension. Must be JSON serializable.
*/
sendMessage(msg: ExtensionMessage): void
}
/**
* Creates an instance of ExtensionNativeMessenger
*/
export function createExtensionMessenger()
```
## Publishing
Because using this package relies on you importing submodules, you must run `npm publish` from within the `dist/` directory to avoid imports having to add `/dist/` to their paths. If you attempt to publish from the top level, the `prepublishOnly` script will fail.