Skip to main content

Set up your JavaScript App

To set up Flipper in your JavaScript app, you need to add the neccessary dependencies to your app, initialize the Flipper client and enable the plugins you want to use.

Currently, we do not ship any plugins for JavaScript environments you can use right away, but we encourage you to write your own!


Flipper JavaScript SDK is distiributed via NPM. To add it to your app run:

npm install js-flipper


yarn add js-flipper

Application Setup

Flipper SDK works in browser and Node.js environments. For browsers, it works out-of-the-box as long as your browser supports WebSockets. For node.js, it requires a compatible WebSocket implementation (e.g. ws).

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.

Here is how you setup Flipper in your browser:

import flipperClient from 'js-flipper';

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

Here 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
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:'}) });

As you can see, flipperClient accepts an options object as a second parameter to its start method. Here is what you can pass there:

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:

flipperClient.addPlugin(/* your plugin */)

Chekc out documentation on creating plugins to write your own!