From 7efad4201c1c4d68c64df88ebfdf7c989593c7cb Mon Sep 17 00:00:00 2001 From: Michel Weststrate Date: Tue, 4 Jan 2022 09:05:09 -0800 Subject: [PATCH] Document how to use Node.js api's Summary: * Documented `npx flipper-server` * Documented how to properly interact with the OS from Flipper plugins Reviewed By: antonk52 Differential Revision: D33361929 fbshipit-source-id: 3028de2bf77a9ee6d9e521c1a53cff2388c936ea --- README.md | 15 ++++++++------- docs/extending/desktop-plugin-structure.mdx | 9 +++++++++ docs/extending/flipper-plugin.mdx | 4 +++- docs/extending/node-apis.mdx | 18 ++++++++++++++++++ docs/getting-started/index.mdx | 1 + website/sidebars.js | 5 +++-- 6 files changed, 42 insertions(+), 10 deletions(-) create mode 100644 docs/extending/node-apis.mdx diff --git a/README.md b/README.md index 79f8425b0..9f96648d5 100644 --- a/README.md +++ b/README.md @@ -21,9 +21,6 @@ ## Table of Contents -- [Mobile development](#mobile-development) -- [Extending Flipper](#extending-flipper) -- [Contributing to Flipper](#contributing-to-flipper) - [In this repo](#in-this-repo) - [Getting started](#getting-started) - [Requirements](#requirements) @@ -31,11 +28,14 @@ - [Desktop](#desktop) - [Running from source](#running-from-source) - [Building standalone application](#building-standalone-application) -- [iOS SDK + Sample App](#ios-sdk--sample-app) -- [Android SDK + Sample app](#android-sdk--sample-app) + - [iOS SDK + Sample App](#ios-sdk--sample-app) + - [Android SDK + Sample app](#android-sdk--sample-app) + - [React Native SDK + Sample app](#react-native-sdk--sample-app) + - [JS SDK + Sample React app](#js-sdk--sample-react-app) + - [Troubleshooting](#troubleshooting) - [Documentation](#documentation) -- [Contributing](#contributing) -- [License](#license) + - [Contributing](#contributing) + - [License](#license) ## Mobile development @@ -80,6 +80,7 @@ This repository includes all parts of Flipper. This includes: Please refer to our [Getting Started guide](https://fbflipper.com/docs/getting-started/index) to set up Flipper. +Or, (still experimental) run `npx flipper-server` for a browser based version of Flipper. ## Requirements diff --git a/docs/extending/desktop-plugin-structure.mdx b/docs/extending/desktop-plugin-structure.mdx index a6c60527a..dc91d0751 100644 --- a/docs/extending/desktop-plugin-structure.mdx +++ b/docs/extending/desktop-plugin-structure.mdx @@ -270,6 +270,15 @@ If you need any dependencies in your plugin, you can install them using `yarn ad +
+ +Flipper plugins should be designed to work inside browsers as well, as Flipper isn't guaranteed to be always running on top of Electron. +For that reason it should be avoided to use Node.js APIs directly (e.g. modules like `fs`, `child_process`, `path`), +or packages that depend on those. +For alternative APIs, see [using Node.js APIs](./node-apis.mdx) in Flipper plugins. + +
+ ## Migration to new Plugin Specification Flipper plugins are defined according to the specification. As with any specification, it is evolving, so new versions of it can be released. Currently Flipper supports plugins defined using version 2 of specification which is described in this page. Previous version of specification is being deprecated, and we encourage all the plugins still using it to migrate. diff --git a/docs/extending/flipper-plugin.mdx b/docs/extending/flipper-plugin.mdx index 6aef69f8d..44cf72f4a 100644 --- a/docs/extending/flipper-plugin.mdx +++ b/docs/extending/flipper-plugin.mdx @@ -990,7 +990,9 @@ See `View > Flipper Style Guide` inside the Flipper application for more details A set of globally available utilities like opening links, interacting with the clipboard, etc. Example: `getFlipperLib().writeTextToClipboard("hello from Flipper"); -The full set of utilities can be found [here](https://github.com/facebook/flipper/blob/main/desktop/flipper-plugin/src/plugin/FlipperLib.tsx#L20) +The full set of utilities can be found [here](https://github.com/facebook/flipper/blob/main/desktop/flipper-plugin/src/plugin/FlipperLib.tsx#L94). + +Since Node.js system API's cannot be used directly by Flipper plugins (when running in a browser), the utilties exposed on `getFlipperLib().remoteServerContext` should be used instead, as detailed in [Using Node.js APIs](./node-apis.mdx). ### createTablePlugin diff --git a/docs/extending/node-apis.mdx b/docs/extending/node-apis.mdx new file mode 100644 index 000000000..7fba780ab --- /dev/null +++ b/docs/extending/node-apis.mdx @@ -0,0 +1,18 @@ +--- +id: node-apis +title: Using Node.js APIs +--- + +Flipper plugins should be designed to work inside browsers as well, as Flipper isn't guaranteed to be always running on top of Electron. +For that reason it should be avoided to use Node.js APIs directly (e.g. modules like `fs`, `child_process`, `path`), +or packages that depend on those. + +The most important Node APIs can be found by using `getFlipperLib()` (exposed by the `flipper-plugin` package). Please note that these APIs are all promisified. + +* `fs`: Use `getFlipperLib().remoteServerContext.fs` instead. +* `child_process`: Use `getFlipperLib().remoteServerContext.childProcess.exec`. Note that this API is intended for short lived processes only. +* `path`: Use `import {path} from 'flipper-plugin'` instead. +* `os`: Use `getFlipperLib().environmentInfo.os` instead. + * For system specific directories like home, desktop, etc, use `getFlipperLib().paths.homePath` and alike. + +In the future, these APIs might be subject to further security / permission restrictions to sandbox plugins better. diff --git a/docs/getting-started/index.mdx b/docs/getting-started/index.mdx index d5e81433c..26ac9a5a4 100644 --- a/docs/getting-started/index.mdx +++ b/docs/getting-started/index.mdx @@ -26,6 +26,7 @@ To work properly with mobile apps, Flipper requires a working installation of th If you are hacking a JS app, you should be good to go without any extra dependencies installed. +[Experimental] Alternatively, it is possible to run a browser based version of Flipper directly from NPM by using `npx flipper-server`. diff --git a/website/sidebars.js b/website/sidebars.js index 4fd155668..fcd80aa49 100644 --- a/website/sidebars.js +++ b/website/sidebars.js @@ -54,7 +54,7 @@ module.exports = { 'getting-started/react-native-ios', ], }, - 'getting-started/javascript' + 'getting-started/javascript', ], }, ...fbInternalOnly(['getting-started/fb/connecting-to-flipper']), @@ -109,11 +109,12 @@ module.exports = { 'extending/flipper-plugin', 'extending/styling-components', 'extending/deeplinks', + 'extending/node-apis', ...fbInternalOnly([ { 'QPL linting': ['fb/building-a-linter', 'fb/active-linters'], }, - ]), + ]), ], 'Client plugin APIs': [ 'extending/create-plugin',