9b16d0c29a
Summary: Document Flipper integration with JavaScript clients. Reviewed By: passy Differential Revision: D31827187 fbshipit-source-id: c40d8820241c0f85bd2366a0c087d4270d316c71
84 lines
3.1 KiB
Plaintext
84 lines
3.1 KiB
Plaintext
---
|
|
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 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 <Link to={useBaseUrl("/docs/extending/create-plugin")}>write your own</Link>!
|
|
|
|
## Dependencies
|
|
|
|
Flipper JavaScript SDK is distiributed via NPM. To add it to your app run:
|
|
|
|
```sh
|
|
npm install js-flipper
|
|
```
|
|
|
|
or
|
|
|
|
```sh
|
|
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](https://developer.mozilla.org/en-US/docs/Web/API/WebSocket). For node.js, it requires a compatible WebSocket implementation (e.g. [ws](https://github.com/websockets/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:
|
|
|
|
```ts
|
|
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:
|
|
|
|
```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:'}) });
|
|
```
|
|
|
|
As you can see, `flipperClient` accepts an options object as a second parameter to its `start` method. Here is what you can pass there:
|
|
|
|
```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:
|
|
|
|
```ts
|
|
flipperClient.addPlugin(/* your plugin */)
|
|
```
|
|
|
|
Chekc out <Link to={useBaseUrl("/docs/extending/create-plugin")}>documentation on creating plugins</Link> to write your own!
|