Files

Andrey Goncharov 9a47f41056 Implement JS flipper client

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

2021-10-21 04:28:21 -07:00

2.8 KiB

Raw Blame History

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. 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.
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.

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.

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.

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. It is currently WIP (do not confuse with RIP!).

2.8 KiB Raw Blame History