Update tutorial to reflect changes in plugin packaging format

Summary: Tutorial updated to reflect changes in plugin packaging format

Reviewed By: passy

Differential Revision: D21161268

fbshipit-source-id: b7c6d272be8dd56b76a0af87acdc347df4216f6c

desktop/plugins/seamammals/package.json

@@ -1,13 +1,28 @@
 {
-  "name": "sea-mammals",
+  "name": "flipper-plugin-sea-mammals",
-  "version": "1.0.0",
+  "id": "sea-mammals",
-  "main": "index.tsx",
+  "private": true,
+  "specVersion": 2,
+  "version": "2.0.0",
+  "main": "dist/bundle.js",
+  "flipperBundlerEntry": "src/index.tsx",
   "license": "MIT",
-  "keywords": ["flipper-plugin"],
+  "keywords": [
+    "flipper-plugin"
+  ],
   "icon": "apps",
   "title": "Sea Mammals",
   "category": "Example Plugin",
   "bugs": {
     "email": "realpassy@fb.com"
+  },
+  "scripts": {
+    "prepack": "flipper-pkg bundle"
+  },
+  "dependencies": {
+    "flipper": "0.39.0"
+  },
+  "devDependencies": {
+    "flipper-pkg": "0.39.0"
   }
 }

desktop/scripts/workspaces.ts

@@ -27,6 +27,10 @@ export interface Workspaces {
   packages: Package[];
 }
 
+function isPlugin(dir: string) {
+  return dir.startsWith(pluginsDir);
+}
+
 export async function getWorkspaces(): Promise<Workspaces> {
   const rootPackageJson = await fs.readJson(path.join(rootDir, 'package.json'));
   const packageGlobs = rootPackageJson.workspaces.packages as string[];
@@ -37,9 +41,7 @@ export async function getWorkspaces(): Promise<Workspaces> {
           glob(path.join(rootDir, pattern, '')),
         )),
       ),
-      async (dir) =>
+      async (dir) => await fs.pathExists(path.join(dir, 'package.json')),
-        !dir.startsWith(pluginsDir) &&
-        (await fs.pathExists(path.join(dir, 'package.json'))),
     ),
     async (dir) => {
       const json = await fs.readJson(path.join(dir, 'package.json'));
@@ -95,11 +97,13 @@ async function bumpWorkspaceVersions(
 ): Promise<string> {
   newVersion = newVersion || (rootPackage.json.version as string);
   const allPackages = [rootPackage, ...packages];
-  const localPackageNames = packages.map(({json}) => json.name as string);
+  const localPackageNames = packages
+    .filter((pkg) => !isPlugin(pkg.dir))
+    .map(({json}) => json.name as string);
   for (const pkg of allPackages) {
-    const json = pkg.json;
+    const {dir, json} = pkg;
     let changed = false;
-    if (json.version !== newVersion) {
+    if (json.version !== newVersion && !isPlugin(dir)) {
       json.version = newVersion;
       changed = true;
     }

docs/tutorial/js-publishing.md

@@ -11,21 +11,31 @@ two rules:
 - The package name should to start with "flipper-plugin-". This makes
   it easier to see what the purpose of the package is.
 - The package must include the keyword "flipper-plugin".
+- Source code of the plugin must be bundled by "flipper-pkg" tool.
 
 A valid example `package.json` could look like this:
 
 ```json
 {
-  "name": "flipper-plugin-example",
+  "name": "flipper-plugin-sea-mammals",
-  "version": "1.0.0",
+  "id": "sea-mammals",
-  "description": "An example for a Flipper plugin",
+  "specVersion": 2,
-  "main": "index.tsx",
+  "version": "2.0.0",
+  "main": "dist/bundle.js",
+  "flipperBundlerEntry": "src/index.tsx",
   "license": "MIT",
   "keywords": ["flipper-plugin"],
-  "title": "Example Plugin",
   "icon": "apps",
-  "bugs": {
+  "title": "Sea Mammals",
-    "url": "https://github.com/facebook/flipper/issues/"
+  "category": "Example Plugin",
+  "scripts": {
+    "prepack": "flipper-pkg bundle"
+  },
+  "dependencies": {
+    "flipper": "latest"
+  },
+  "devDependencies": {
+    "flipper-pkg": "latest"
   }
 }
 ```

docs/tutorial/js-setup.md

@@ -5,7 +5,8 @@ sidebar_label: Building a Desktop Plugin
 ---
 
 Now that we have the native side covered, let's display the data we're sending
-on the desktop side.
+on the desktop side. You can check out the full workflow of building Flipper desktop
+plugins here: https://fbflipper.com/docs/extending/js-setup.html.
 
 ![Custom cards UI for our sea mammals plugin](assets/js-custom.png)
 
@@ -40,22 +41,36 @@ $ cd sea-mammals
 $ yarn init
 ```
 
-When choosing the package name, remember to use the name we have specified on the native side as ID.
+Open the `package.json` and edit it. There are a few important things:
-In our case, that is "sea-mammals". Once done, open the `package.json`. In addition to the name,
+1) "name" must start with "flipper-plugin-"
-you can also specify a title to show in the Flipper sidebar and an icon to display here. For instance:
+2) "keywords" must contain "flipper-plugin"
+3) "id" must be the same as used on native side, e.g. returned by getId() method in Android plugin. In our case that is "sea-mammals".
+4) "specVersion" must contain the version of the specification according to which the plugin is defined.  Currently, Flipper supports plugins defined by the specification version 2, while version 1 is being deprecated.
+5) "title" and "icon" are optional fields specifying the plugin item appearance in the Flipper sidebar.
+
+For instance:
 
 ```json
 {
-  "name": "sea-mammals",
+  "name": "flipper-plugin-sea-mammals",
-  "version": "1.0.0",
+  "id": "sea-mammals",
-  "main": "index.tsx",
+  "specVersion": 2,
+  "version": "2.0.0",
+  "main": "dist/bundle.js",
+  "flipperBundlerEntry": "src/index.tsx",
   "license": "MIT",
   "keywords": ["flipper-plugin"],
   "icon": "apps",
   "title": "Sea Mammals",
   "category": "Example Plugin",
+  "scripts": {
+    "prepack": "flipper-pkg bundle"
+  },
   "dependencies": {
     "flipper": "latest"
+  },
+  "devDependencies": {
+    "flipper-pkg": "latest"
   }
 }
 ```