From 49be7fd35f0191320d1c0259a813979ea03e98af Mon Sep 17 00:00:00 2001 From: John Knox Date: Fri, 3 May 2019 04:25:22 -0700 Subject: [PATCH] Redefine Js-Setup as JS Plugin Definition Summary: The purpose of this page wasn't that clear to me, though the content is pretty focused. I've changed it from JS setup to JS Plugin Definition, and reworded it a bit. I think it makes sense if this specifies everything to do with plugins on the file system, and the next page talks about what you do in javascript. Reviewed By: passy Differential Revision: D15184829 fbshipit-source-id: 6335ebc8d4297ffcbf1ab9860b4f055fe5bbcf87 --- docs/extending/jssetup.md | 38 ++++++++++++++++++++++++++++++++------ website/i18n/en.json | 2 +- 2 files changed, 33 insertions(+), 7 deletions(-) diff --git a/docs/extending/jssetup.md b/docs/extending/jssetup.md index ebab8f751..d72956918 100644 --- a/docs/extending/jssetup.md +++ b/docs/extending/jssetup.md @@ -1,12 +1,15 @@ --- id: js-setup -title: JavaScript Setup +title: JavaScript Plugin Definition --- -## Creating the plugin UI +All JavaScript Flipper plugins consist of a directory. This directory must contain the following two files: +* package.json +* index.js -To create the desktop part of your plugin, initiate a new JavaScript project using `yarn init` and make sure your package name is the plugin's ID you are using in the native implementation. Create a file called `index.js`, which is the entry point to your plugin. A sample `package.json`-file could look like this: +To create the desktop part of your plugin, initiate a new JavaScript project using `yarn init` and make sure your package name is the same as the identifier of the client plugin. Create a file called `index.js`, which is the entry point to your plugin. An example `package.json` file could look like this: +Example `package.json`: ``` { "name": "myplugin", @@ -22,13 +25,36 @@ To create the desktop part of your plugin, initiate a new JavaScript project usi } ``` -Flipper uses some fields from the `package.json` in the plugin. The `name` is used as, the ID to identify the mobile counterpart. A `title` can be set, that is shown in Flipper's sidebar, same is true for the `icon`. We also strongly encourage to set a `bugs` field specifying an email and/or url, where bugs for the plugin can be reported. +Important attributes of `package.json`: -In `index.js` you can now create your plugin. Take a look at [Writing a plugin](writing-a-plugin.md) to learn how a plugin can look like. Also, make sure to check out [Flipper's UI components](ui-components.md) when building your plugin. +`name` Used as the plugin identifier and **must match the mobile plugin Identifier**. + +`title` Shown in the main sidebar as the human readable name of the plugin. + +`icon` Determines the plugin icon which is displayed in the main sidebar. + +`bugs` Specify an email and/or url, where plugin bugs should be reported. + +In `index.js` you can now create your plugin. Take a look at [Writing a plugin](writing-a-plugin.md) to see what this code looks like. Also, make sure to check out the [Flipper UI Component Library](ui-components.md) for lots of pre-made components. ### Dynamically loading plugins -Once a plugin is created, Flipper can load it from its folder. The path from where the plugins are loaded is specified in `~/.flipper/config.json`. The paths specified in `pluginPaths` need to point to a folder containing a subfolder for every plugin. For example you can create a directory `~/flipper-plugins` and set `pluginPaths` in Flipper's config to `["~/flipper-plugins"]`. This directory needs to contain a sub-directory for every plugin you create. In this example there would be a directory `~/flipper-plugins/myplugin` that contains your plugin's `package.json` and all code of your plugin. +Flipper will load and run plugins it finds in a configurable location. The paths searched are specified in `~/.flipper/config.json`. These paths, `pluginPaths`, should contain one folder for each of the plugins it stores. An example config setting and plugin file structure is shown below: + +`~/.flipper/config.json`: +``` +{ + ..., + "pluginPaths": ["~/flipper-plugins"] +} +``` +Plugin File Structure: +``` +~ flipper-plugins/ + my-plugin/ + package.json + index.js +``` ### npm dependencies diff --git a/website/i18n/en.json b/website/i18n/en.json index 5702ce380..2e9b5cb53 100644 --- a/website/i18n/en.json +++ b/website/i18n/en.json @@ -32,7 +32,7 @@ "title": "Clients and Plugins" }, "extending/js-setup": { - "title": "JavaScript Setup" + "title": "JavaScript Plugin Definition" }, "extending/layout-inspector": { "title": "Extending the Layout Inspector"