---
id: javascript
title: Set up your JavaScript App
sidebar_label: JavaScript (browser / Node.js)
---
import useBaseUrl from '@docusaurus/useBaseUrl';
import Link from '@docusaurus/Link';

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 <Link to={useBaseUrl("/docs/extending/create-plugin")}>create your own</Link>.

## Dependencies

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

```sh
npm install js-flipper
```

or

```sh
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](https://developer.mozilla.org/en-US/docs/Web/API/WebSocket).
* **node.js** - requires a compatible WebSocket implementation (such as [ws](https://github.com/websockets/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:

```ts
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:

```ts
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:

```ts
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:

```ts
flipperClient.addPlugin(/* your plugin */)
```

Refer to the documentation on <Link to={useBaseUrl("/docs/extending/create-plugin")}>creating plugins</Link> to write your own!