Add documentation

Summary: Document Flipper integration with JavaScript clients.

Reviewed By: passy

Differential Revision: D31827187

fbshipit-source-id: c40d8820241c0f85bd2366a0c087d4270d316c71

docs/getting-started/index.mdx

@@ -6,12 +6,13 @@ import useBaseUrl from '@docusaurus/useBaseUrl';
 
 import FbInstallation from './fb/installation.mdx';
 
-Flipper helps you debug Android and iOS apps running in an emulator/simulator or connected physical development devices. Flipper consists of two parts:
+Flipper helps you debug Android, iOS, and even web apps running in an emulator/simulator, connected physical development devices, or in your browser. Flipper consists of two parts:
 
 - The desktop app
-- The native mobile SDKs for Android and iOS
+- The native mobile SDKs for Android and iOS, the client for JavaScript, or even a third-party client you could implement yourself or find on the web
 
 Once you start Flipper and launch an emulator/simulator or connect a device, you'll start to see the device logs (and any other device-level plugins that work with your device).
+For web apps, we do not ship any built in plugins yet.
 
 To see app specific data, you need to integrate the Flipper SDK into your app. See the relevant section in the sidebar for how to do that.
 
@@ -21,9 +22,10 @@ To see app specific data, you need to integrate the Flipper SDK into your app. S
 
 The desktop part of Flipper doesn't need any particular setup. Simply download the latest build for [Mac](https://www.facebook.com/fbflipper/public/mac), [Linux](https://www.facebook.com/fbflipper/public/linux) or [Windows](https://www.facebook.com/fbflipper/public/windows) and launch it. If you're on macOS, you can run `brew install --cask flipper` to let `homebrew` manage installation and upgrades (simply run `brew upgrade` to upgrade when a new version is released, although it might take a few hours up to a day for the package to be upgraded on `homebrew`). 
 
-In order to work properly, Flipper requires a working installation of the Android and (if where applicable) iOS development tools on your system, as well as the [OpenSSL](https://www.openssl.org) binary on your `$PATH`.
+To work properly with mobile apps, Flipper requires a working installation of the Android and (if where applicable) iOS development tools on your system, as well as the [OpenSSL](https://www.openssl.org) binary on your `$PATH`. A compatible OpenSSL for Windows can be downloaded [here](https://slproweb.com/products/Win32OpenSSL.html) or from Chocolatey with `choco install openssl`.
+
+If you are hacking a JS app, you should be good to go without any extra dependencies installed.
 
-A compatible OpenSSL for Windows can be downloaded [here](https://slproweb.com/products/Win32OpenSSL.html) or from Chocolatey with `choco install openssl`.
 
 </OssOnly>
 <FbInternalOnly>

docs/getting-started/javascript.mdx

@@ -0,0 +1,83 @@
+---
+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!