6258169afe
Summary:
Adding this to another place that people seem to overlook.
This diff has been automatically generated by the inpage editor.
If you want to update this diff, go through the preview link that would be attached to the test plan.
Please ensure you are editing the same page that was used to create this diff.
Reviewed By: antonk52
Differential Revision: D33528019
fbshipit-source-id: ce6bf60b42161fc409277fb8c62ff38fd91b05cf
174 lines
7.2 KiB
Plaintext
174 lines
7.2 KiB
Plaintext
---
|
||
id: dev-setup
|
||
title: Development Setup
|
||
---
|
||
|
||
## IDE
|
||
|
||
<OssOnly>
|
||
|
||
When developing Flipper plugins we recommend the following IDEs:
|
||
|
||
1. TypeScript (for Flipper Desktop (plugins)): Visual Studio Code
|
||
1. Install the "ESLint" (dbaeumer.vscode-eslint) extension from marketplace to enable linting
|
||
1. Install the "Prettier" (esbenp.prettier-vscode) extension to enable automatic code-formatting
|
||
1. 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.
|
||
|
||
1. Android Studio (for Android plugins)
|
||
1. XCode (for iOS plugins)
|
||
|
||
</OssOnly>
|
||
|
||
<FbInternalOnly>
|
||
|
||
### TypeScript
|
||
|
||
Flipper Desktop is written in TypeScript.
|
||
Using our internal "VSCode @ FB" as IDE is strongly recommended (`code-fb`).
|
||
|
||
Make sure to install and enable extensions `[FB-Internal] ESLint Diagnostics` and `[FB-Internal] Prettier`.
|
||
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 (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 (e.g. 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.
|
||
|
||
</FbInternalOnly>
|
||
|
||
|
||
## Running Flipper from source (recommended)
|
||
|
||
When developing Flipper plugins we strongly recommend to run from Flipper itself from source as well, as this yields several benefits:
|
||
|
||
|
||
- Automatic transpilation and bundling of loaded plugins: ES6, TypeScript, JSX.
|
||
- Automatic refresh after code changes.
|
||
- React and Redux Dev Tools.
|
||
- [Debugging](debugging.mdx) using Chrome Dev Tools or Visual Studio Code.
|
||
- Additional debug information like React warnings and performance metrics.
|
||
|
||
Prerequisites for Flipper development build:
|
||
- node ≥ 14
|
||
- yarn ≥ 1.5
|
||
- git
|
||
- watchman
|
||
|
||
To run Flipper Desktop from source:
|
||
|
||
<OssOnly>
|
||
|
||
```
|
||
git clone https://github.com/facebook/flipper.git
|
||
cd flipper/desktop
|
||
yarn
|
||
yarn start
|
||
```
|
||
|
||
Tip: start with `yarn start --fast-refresh` for experimental fast refresh.
|
||
|
||
</OssOnly>
|
||
|
||
<FbInternalOnly>
|
||
|
||
Note: All these steps must be run on a local machine (e.g. laptop) and development cannot be done on a Dev Server or OnDemand as Flipper is a desktop application.
|
||
|
||
```bash
|
||
fbclone fbsource --sparse tools/scm/sparse/xplat/flipper-js
|
||
cd ~/fbsource/xplat/sonar/desktop
|
||
yarn
|
||
yarn start
|
||
```
|
||
|
||
A note on sparse profiles: We have 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
|
||
|
||
```bash
|
||
hg sparse enable tools/scm/sparse/xplat/flipper-js
|
||
```
|
||
|
||
Tip: start with `yarn start --fast-refresh` for experimental fast refresh.
|
||
|
||
Tip: start wih `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`.
|
||
|
||
</FbInternalOnly>
|
||
|
||
### 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 file `.env` in `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, e.g.:
|
||
|
||
```
|
||
FLIPPER_FAST_REFRESH=true
|
||
FLIPPER_OPEN_DEV_TOOLS=true
|
||
FLIPPER_ENABLED_PLUGINS=flipper-messages,network,inspector
|
||
```
|
||
|
||
<FbInternalOnly>
|
||
|
||
To start Flipper against a specific OnDemand instance, set FB_ONDEMAND flag, e.g: `FB_ONDEMAND=34435.od yarn start`
|
||
|
||
</FbInternalOnly>
|
||
|
||
## Guidelines for writing TypeScript
|
||
* **Important:** Use `.tsx` file extension for all TypeScript files (instead of `.ts`)
|
||
* Prefer `type` for React props and state over interfaces
|
||
* Don’t prefix interfaces with `I`
|
||
* Enums, Types and Interfaces use PascalCase (uppercase first letter)
|
||
* Install 3rd party type definitions as dev dependency (e.g. `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](testing.mdx) page for more details on writing and running test.
|
||
|
||
To make sure 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`
|