Skip to main content

Set up your JavaScript App

To set up Flipper in your JavaScript app, you need to add the necessary dependencies, initialize the Flipper client and enable the plugins you want to use. Currently, plugins are not available for JavaScript environments, but you can create your own.

Dependencies​

Flipper JavaScript SDK is distributed via NPM. To add it to your app, use either the following:

npm install js-flipper

or

yarn add js-flipper

Application Setup​

Flipper SDK works in browser and Node.js environments:

  • browsers - works out-of-the-box if your browser supports WebSockets.
  • node.js - requires a compatible WebSocket implementation (such as ws).
caution

You MUST NOT start Flipper client in production. In browser environments, you should think about not including it in the final production build at all.

To setup Flipper in your browser, use the following:

import flipperClient from 'js-flipper';

// Start the client and pass your app name
flipperClient.start('My cool browser app');

Following is how you can do it in your Node.js app:

import flipperClient from 'js-flipper';
// Say, you decided to go with 'ws' as your WebSocket implementation
// https://github.com/websockets/ws
import WebSocket from 'ws';

// Start the client and pass your app name
// 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`).
flipperClient.start('My cool nodejs app', { websocketFactory: url => new WebSocket(url, {origin: 'localhost:'}) });

flipperClient accepts an options object as a second parameter to its start method. The following code shows what you can pass to it:

interface FlipperClientOptions {
    // Make the client connect to a different URL
    urlBase?: string;
    // Override WebSocket implementation (Node.js folks, it is for you!)
    websocketFactory?: (url: string) => FlipperWebSocket;
    // Override how errors are handled (it is simple `console.error` by default)
    onError?: (e: unknown) => void;
    // Timeout after which client tries to reconnect to Flipper
    reconnectTimeout?: number;
}

Enabling plugins​

Flipper is just a communication channel between the desktop app and your application; its true power comes from its plugins.

All plugins must be added to the client. Client communicates the list of available plugins to the desktop upon connection.

You can add a plugin by calling the following:

flipperClient.addPlugin(/* your plugin */)

Refer to the documentation on creating plugins to write your own!