9a47f41056
Summary: Standardize WS implementation for JS environments. Why do we need a separate server implementation for browsers? Browser targets cannot authenticate via the default certificate exchange flow. We need a dedicated client for them that works over an insecure channel (without the cert exchange). Major changes: 1. Renamed `flipper-js-client-sdk` to `js-flipper` for consistency with `react-native-flipper` 2. Updated `js-flipper` implementation to match our other existing clients Documentation will be updated in a separate subsequent PR. https://fb.quip.com/2mboA0xbgoxl Reviewed By: mweststrate Differential Revision: D31688105 fbshipit-source-id: 418aa80e0fd86361c089cf54b0d44a8b4f748efa
69 lines
2.8 KiB
Markdown
69 lines
2.8 KiB
Markdown
# flipper-sdk-api
|
|
|
|
This package exposes JavaScript bindings to talk from web / Node.js directly to
|
|
flipper.
|
|
|
|
## Installation
|
|
|
|
`yarn add js-flipper`
|
|
|
|
## Usage
|
|
|
|
How to build Flipper plugins is explained in the flipper documentation:
|
|
[Creating a Flipper plugin](https://fbflipper.com/docs/extending/index).
|
|
Building a Flipper plugin involves building a plugin for the Desktop app, and a
|
|
plugin that runs on a Device (web or Node.js). This package is only needed for
|
|
the plugin that runs on the device (web / Node.js), and wants to use the
|
|
WebSocket connection to communicate to Flipper.
|
|
|
|
This package exposes a `flipperClient`. It has:
|
|
|
|
- `addPlugin` method. It accepts a `plugin`
|
|
parameter, that registers a client plugin and will fire the relevant callbacks
|
|
if the corresponding desktop plugin is selected in the Flipper Desktop. The full
|
|
plugin API is documented
|
|
[here](https://fbflipper.com/docs/extending/create-plugin).
|
|
- `start` method. It starts the client.
|
|
- `appName` setter to set the app name displayed in Flipper
|
|
- `onError` setter to override how errors are handled (it is simple `console.error` by default)
|
|
- `websocketFactory` setter to override WebSocket implementation (Node.js folks, it is for you!)
|
|
- `urlBase` setter to make the client connect to a different URL
|
|
|
|
## Example (web)
|
|
|
|
An example plugin can be found in
|
|
[FlipperTicTacToe.js](https://github.com/facebook/flipper/blob/main/js/react-flipper-example/src/FlipperTicTacToe.tsx).
|
|
|
|
The corresponding Desktop plugin ships by default in Flipper, so importing the
|
|
above file and dropping the `<FlipperTicTacToe />` component somewhere in your
|
|
application should work out of the box.
|
|
|
|
The sources of the corresponding Desktop plugin can be found
|
|
[here](https://github.com/facebook/flipper/tree/main/desktop/plugins/rn-tic-tac-toe).
|
|
|
|
## Node.js
|
|
|
|
Node.js does not have a built-in WebSocket implementation. You need to install
|
|
any implmentation of WebSockets for Node.js that is compatible with the
|
|
interface of the
|
|
[web version](https://developer.mozilla.org/en-US/docs/Web/API/WebSocket).
|
|
|
|
```ts
|
|
import {setWebSocketImplementation, start} from 'js-flipper';
|
|
// Say, you decided to go with 'ws'
|
|
// https://github.com/websockets/ws
|
|
import WebSocket from 'ws';
|
|
|
|
// You need to let the flipper client know about it.
|
|
setWebSocketImplementation(url => new WebSocket(url, {origin: 'localhost:'}));
|
|
// You might ask yourself why there is the second argument `{ origin: 'localhost:' }`
|
|
// Flipper Desktop verifies the `Origin` header for every WS connection. You need to set it to one of the whitelisted values (see `VALID_WEB_SOCKET_REQUEST_ORIGIN_PREFIXES`).
|
|
|
|
// Now, the last bit. You need to start the client.
|
|
start();
|
|
```
|
|
|
|
An example plugin should be somewhat similar to
|
|
[what we have for React](https://github.com/facebook/flipper/blob/main/js/react-flipper-example/src/FlipperTicTacToe.tsx).
|
|
It is currently WIP (do not confuse with RIP!).
|