Development Setup

IDE

When developing Flipper plugins, the following IDEs are recommended:

• TypeScript (for Flipper Desktop (plugins)): Visual Studio Code
  • Install the "ESLint" (dbaeumer.vscode-eslint) extension from marketplace to enable linting.
  • Install the "Prettier" (esbenp.prettier-vscode) extension to enable automatic code-formatting.
  • If for some reason it is not working, the builtin TypeScript extension might be disabled. To enable it, to go to extensions, search for “@builtin typescript” and enable it.
• Android Studio (for Android plugins).
• XCode (for iOS plugins).

TypeScript

Flipper Desktop is written in TypeScript. Use of the internal 'VSCode @ FB' as your 'go to' IDE is strongly recommended (code-fb).

Make sure to install and enable extensions [FB-Internal] ESLint Diagnostics and [FB-Internal] Prettier. If it's not working, the builtin TypeScript extension might be disabled. To enable it, go to extensions, search for “@builtin typescript”, and enable it.

Android (Java)

IntelliJ is the recommended platform. Focussing on a flipper-enabled app should include the flipper modules as expected.

If you don't have an fbsource checkout (such as Whatsapp Team), you can open Android Studio and import project: fbsource/xplat/sonar

If you're having gradle (or other) problems, make sure you're on the latest Android Studio version.

Running Flipper from source (recommended)

When developing Flipper plugins, it's strongly recommended to run from Flipper itself from source as well, as this yields the following benefits:

• Automatic transpilation and bundling of loaded plugins: ES6, TypeScript, JSX.
• Automatic refresh after code changes.
• React and Redux Dev Tools.
• Debugging using Chrome Dev Tools or Visual Studio Code.
• Additional debug information like React warnings and performance metrics.

Prerequisites for a Flipper development build:

• node ≥ 14
• yarn ≥ 1.5
• git
• watchman

To run Flipper Desktop from source:

git clone https://github.com/facebook/flipper.git
cd flipper/desktop
yarn
yarn start

:::note Tip Start with yarn start --fast-refresh for experimental fast refreash. :::

:::note All these steps must be run on a local machine (such as a laptop) and development cannot be done on a Dev Server or OnDemand as Flipper is a desktop application. :::

fbclone fbsource --sparse tools/scm/sparse/xplat/flipper-js
cd ~/fbsource/xplat/sonar/desktop
yarn
yarn start

A note on sparse profiles

There is a minimal profile for working with the Flipper JavaScript files in fbsource for plugin Developers. This will drastically reduce the size of your checkout, but won't include the files necessary to, for instance, build and work on mobile apps.

If you have an existing sparse checkout, you can add the Flipper profile with the following:

hg sparse enable tools/scm/sparse/xplat/flipper-js

:::note Tips

• Start with yarn start --fast-refresh for an experimental fast refresh.
• Start with yarn start --public-build to preview changes for public builds. :::

Use VSCode to hack on Flipper.

To make sure ESLint and Prettier are applied correctly, make sure to open either sonar or sonar/desktop as workspace folder in VSCode: code-fb ~/fbsource/xplat/sonar.

Startup options

You can use several options to customise development build instance. They can be provided as command-line args or environment variables.

You can check all of them by executing yarn start --help:

yarn start [args]

Options:
  --embedded-plugins    Enables embedding of plugins into Flipper bundle. If it
                        disabled then only installed plugins are loaded. The
                        flag is enabled by default. Env var
                        FLIPPER_NO_EMBEDDED_PLUGINS is equivalent to the
                        command-line option "--no-embedded-plugins".   [Boolean]
  --fast-refresh        Enable Fast Refresh - quick reload of UI component
                        changes without restarting Flipper. The flag is disabled
                        by default. Env var FLIPPER_FAST_REFRESH is equivalent
                        to the command-line option "--fast-refresh".   [Boolean]
  --plugin-auto-update  [FB-internal only] Enable plugin auto-updates. The flag
                        is disabled by default in dev mode. Env var
                        FLIPPER_NO_PLUGIN_AUTO_UPDATE is equivalent to the
                        command-line option "--no-plugin-auto-update"  [Boolean]
  --enabled-plugins     Load only specified plugins and skip loading rest. This
                        is useful when you are developing only one or few
                        plugins. Plugins to load can be specified as a
                        comma-separated list with either plugin id or name used
                        as identifier, e.g. "--enabled-plugins
                        network,inspector". The flag is not provided by default
                        which means that all plugins loaded.             [array]
  --open-dev-tools      Open Dev Tools window on startup. The flag is disabled
                        by default. Env var FLIPPER_OPEN_DEV_TOOLS is equivalent
                        to the command-line option "--open-dev-tools". If
                        "FLIPPER_UPDATE_DEV_TOOLS=true" is set additionally,
                        Flipper will try to update the dev tools from the play
                        store.                                         [Boolean]
  --dev-server-port     Dev server port. 3000 by default. Env var "PORT=3001" is
                        equivalent to the command-line option "--dev-server-port
                        3001".                          [number] [default: 3000]
  --version             Show version number                            [Boolean]
  --help                Show help                                      [Boolean]

You can also create an .env file in the desktop subfolder and specify any environment variables to load them automatically on yarn start so you don't need to pass command-line args every time:

FLIPPER_FAST_REFRESH=true
FLIPPER_OPEN_DEV_TOOLS=true
FLIPPER_ENABLED_PLUGINS=flipper-messages,network,inspector

To start Flipper against a specific OnDemand instance, set FB_ONDEMAND flag. for example, FB_ONDEMAND=34435.od yarn start

Guidelines for writing TypeScript

• Install 3rd party type definitions as dev dependency (for example, yarn add @types/lodash --dev)

Submitting a diff / PR

Make sure your new functionality is covered with tests and run yarn test or yarn test --watch in the desktop/ directory to verify that they pass.

See the testing page for more details on writing and running tests.

To ensure you don't get any lint/formatting errors, run yarn lint before submitting your diff. Some errors (especially formatting errors) can be auto-fixed by running yarn fix