@toolsplus/nx-forge 1.0.0 → 1.1.1

package/README.md

@@ -1,11 +1,164 @@
-# forge
+#  Nx Forge
 
-This library was generated with [Nx](https://nx.dev).
+[Nx plugin](https://nx.dev) for [Atlassian Forge](https://developer.atlassian.com/platform/forge/) that aims to assist in efficient, scalable app development and remove the mental overhead of how to set up a Forge project.
+Building on top of Nx means shared code can easily be extracted into libraries, and [Custom UI](https://developer.atlassian.com/platform/forge/custom-ui/) can be integrated into the app and dev workflow without having to break with the monorepo structure that Nx provides.
 
-## Building
+## Prerequisites
 
-Run `nx build forge` to build the library.
+The following setup procedure assumes you already have a Nx workspace. If you do not, make sure to create one using
 
-## Running unit tests
+```shell
+npx create-nx-workspace <workspace-name> --preset=apps
+```
 
-Run `nx test forge` to execute the unit tests via [Jest](https://jestjs.io).
+You will be asked if you would like to use Nx Cloud or not (either option is fine). Once, the workspace has been created run `cd <workspace-name>`.
+
+Finally, make sure your workspace has the following package installed
+
+```shell
+npm install --save-dev @nrwl/js
+```
+
+
+## Setting up
+
+### Install the plugin
+
+Add the plugin to your Nx workspace using
+
+```shell
+npm install --save-dev @toolsplus/nx-forge
+```
+
+or
+
+```shell
+yarn add --dev @toolsplus/nx-forge
+```
+
+### Generate a Forge app
+
+Once installed, run the Forge app generator to generate a Forge app.
+
+```shell
+nx g @toolsplus/nx-forge:app <forge-app-name>
+```
+
+> Hint: You can use the `--dry-run` flag to see what will be generated.
+
+Replacing `<forge-app-name>` with the name of the app you're wanting to create.
+
+### Add a Custom UI module
+
+Forge apps require at least one module before they can be deployed. Let's start with a simple Custom UI module to get started. If you have not yet installed `@nrwl/react` in your workspace call `npm i -D @nrwl/react`. This allows us to generate a React application for our Custom UI:
+
+    nx g @nrwl/react:app <custom-ui-app-name>
+
+> Hint: You can use the `--dry-run` flag to see what will be generated.
+
+Replacing `<custom-ui-app-name>` with the name of the Custom UI project you're wanting to create.
+
+To get this React app working as a Forge Custom UI update the `apps/<custom-ui-app-name>/project.json` file by replacing the `baseHref` value in the build options with `.` instead of `/` ([refer to the Forge docs for additional details](https://developer.atlassian.com/platform/forge/custom-ui/#accessing-static-assets)):
+
+```
+{
+  "root": "apps/<custom-ui-app-name>",
+  "sourceRoot": "apps/<custom-ui-app-name>/src",
+  "projectType": "application",
+  "targets": {
+    "build": {
+      "executor": "@nrwl/web:webpack",
+      "outputs": ["{options.outputPath}"],
+      "defaultConfiguration": "production",
+      "options": {
+        "compiler": "babel",
+        "outputPath": "dist/apps/<custom-ui-app-name>",
+        "index": "apps/<custom-ui-app-name>/src/index.html",
+----->  "baseHref": ".",
+        ...
+      }
+    },
+    ...
+  }
+}
+```
+
+### Wire the Custom UI project with the Forge app project
+
+Back in the Forge app project, open the generated `manifest.yml` file and add a Custom UI module and the corresponding resource entry:
+
+```yaml
+modules:
+  jira:projectPage:
+    - key: project-page
+      title: Project page Custom UI
+      layout: basic
+      resource: project-page
+      resolver:
+        function: resolver
+  function:
+    - key: resolver
+      handler: index.handler
+resources:
+  - key: project-page
+    path: <custom-ui-app-name>
+    tunnel:
+      port: 4200
+permissions:
+  content:
+    styles:
+      - 'unsafe-inline'
+app:
+  id: ari:cloud:ecosystem::app/to-be-generated
+```
+
+The most important bit to note here is that the `path` property of the `project-page` resource should refer to the Custom UI project name from the previous step. This tells the Nx Forge plugin which Nx app project corresponds to `project-page` resource. The plugin will replace this path with the actual Custom UI build artifact during the Forge app build.
+
+Finally, update the `apps/<forge-app-name>/project.json` file in the generated Forge app project to define an implicit dependency to the Custom UI project.
+
+```json
+{
+  "root": "apps/<forge-app-name>",
+  "sourceRoot": "apps/<forge-app-name>/src",
+  "projectType": "application",
+  "targets": {
+    
+  },
+  "implicitDependencies": ["<custom-ui-app-name>"]
+}
+```
+
+This tells Nx that each time we build our Forge app, it needs to build the Custom UI project first.
+
+### Initial build and registration
+
+Before you can deploy the Forge app it needs to be registered with the Forge platform. To do this, initially build the Forge app using
+
+    nx build <forge-app-name>
+
+Once that's finished, go to `dist/apps/<forge-app-name>` and run the following three commands
+
+```shell
+forge register
+forge deploy
+forge install
+```
+
+The Forge app is now registered, deployed and installed with the Forge platform. As a final last step, open the `dist/apps/<forge-app-name>/manifest.yml` and copy-paste the app id that was generated during app registration into the Forge app project under `apps/<forge-app-name>/manifest.yml`:
+
+```yaml
+app:
+  id: ari:cloud:ecosystem::app/f2fc9c8f-5947-7da7-32ab-6367647e4b1a
+```
+
+That's it for the setup steps. You can now generate additional Custom UI resources, generate shared Nx libraries to keep shared app logic and depend on it in one or more Forge apps.
+
+## Using the Nx Forge plugin
+
+### Build
+
+Run `nx build <forge-app-name>` to build the project. The build artifacts will be stored in the `dist/` directory.
+
+## Further help on how to develop with Nx
+
+Visit the [Nx Documentation](https://nx.dev) to learn more.

package/package.json

@@ -1,13 +1,13 @@
 {
   "name": "@toolsplus/nx-forge",
-  "version": "1.0.0",
+  "version": "1.1.1",
   "description": "Atlassian Forge plugin for Nx",
   "main": "src/index.js",
   "generators": "./generators.json",
   "executors": "./executors.json",
   "peerDependencies": {
-    "@nrwl/js": "^13.9.4",
-    "@nrwl/workspace": "^13.9.4"
+    "@nrwl/js": "^14.0.0",
+    "@nrwl/workspace": "^14.0.0"
   },
   "typings": "./src/index.d.ts",
   "dependencies": {

package/src/generators/application/files/tsconfig.app.json

@@ -9,7 +9,6 @@
     "esModuleInterop": true,
     "lib": ["dom", "es2017"],
     "types": ["node"],
-    "baseUrl": "./",
     "jsx": "react",
     "jsxFactory": "ForgeUI.createElement"
   },

package/src/generators/application/lib/get-build-config.d.ts

@@ -1,3 +1,3 @@
-import { ProjectConfiguration, TargetConfiguration } from 'nx/src/shared/workspace';
 import { NormalizedOptions } from '../schema';
+import { ProjectConfiguration, TargetConfiguration } from '@nrwl/devkit';
 export declare function getBuildConfig(project: ProjectConfiguration, options: NormalizedOptions): TargetConfiguration;

package/src/generators/application/lib/get-build-config.js.map

@@ -1 +1 @@
-{"version":3,"file":"get-build-config.js","sourceRoot":"","sources":["../../../../../../../packages/forge/src/generators/application/lib/get-build-config.ts"],"names":[],"mappings":";;;AAKA,yCAAiD;AAEjD,SAAgB,cAAc,CAC5B,OAA6B,EAC7B,OAA0B;IAE1B,OAAO;QACL,QAAQ,EAAE,2BAA2B;QACrC,OAAO,EAAE,CAAC,sBAAsB,CAAC;QACjC,OAAO,EAAE;YACP,UAAU,EAAE,IAAA,0BAAiB,EAAC,MAAM,EAAE,OAAO,CAAC,cAAc,CAAC;SAC9D;KACF,CAAC;AACJ,CAAC;AAXD,wCAWC"}
+{"version":3,"file":"get-build-config.js","sourceRoot":"","sources":["../../../../../../../packages/forge/src/generators/application/lib/get-build-config.ts"],"names":[],"mappings":";;;AACA,yCAIsB;AAEtB,SAAgB,cAAc,CAC5B,OAA6B,EAC7B,OAA0B;IAE1B,OAAO;QACL,QAAQ,EAAE,2BAA2B;QACrC,OAAO,EAAE,CAAC,sBAAsB,CAAC;QACjC,OAAO,EAAE;YACP,UAAU,EAAE,IAAA,0BAAiB,EAAC,MAAM,EAAE,OAAO,CAAC,cAAc,CAAC;SAC9D;KACF,CAAC;AACJ,CAAC;AAXD,wCAWC"}

package/src/generators/application/lib/get-deploy-config.d.ts

@@ -1,3 +1,3 @@
-import { ProjectConfiguration, TargetConfiguration } from 'nx/src/shared/workspace';
 import { NormalizedOptions } from '../schema';
+import { ProjectConfiguration, TargetConfiguration } from '@nrwl/devkit';
 export declare function getDeployConfig(project: ProjectConfiguration, options: NormalizedOptions): TargetConfiguration;

package/src/generators/application/lib/get-deploy-config.js.map

@@ -1 +1 @@
-{"version":3,"file":"get-deploy-config.js","sourceRoot":"","sources":["../../../../../../../packages/forge/src/generators/application/lib/get-deploy-config.ts"],"names":[],"mappings":";;;AAKA,yCAAiD;AAEjD,SAAgB,eAAe,CAC7B,OAA6B,EAC7B,OAA0B;IAE1B,OAAO;QACL,QAAQ,EAAE,4BAA4B;QACtC,OAAO,EAAE;YACP,UAAU,EAAE,IAAA,0BAAiB,EAAC,MAAM,EAAE,OAAO,CAAC,cAAc,CAAC;SAC9D;KACF,CAAC;AACJ,CAAC;AAVD,0CAUC"}
+{"version":3,"file":"get-deploy-config.js","sourceRoot":"","sources":["../../../../../../../packages/forge/src/generators/application/lib/get-deploy-config.ts"],"names":[],"mappings":";;;AACA,yCAIsB;AAEtB,SAAgB,eAAe,CAC7B,OAA6B,EAC7B,OAA0B;IAE1B,OAAO;QACL,QAAQ,EAAE,4BAA4B;QACtC,OAAO,EAAE;YACP,UAAU,EAAE,IAAA,0BAAiB,EAAC,MAAM,EAAE,OAAO,CAAC,cAAc,CAAC;SAC9D;KACF,CAAC;AACJ,CAAC;AAVD,0CAUC"}

package/src/generators/application/lib/get-serve-config.d.ts

@@ -1,3 +1,3 @@
-import { ProjectConfiguration, TargetConfiguration } from 'nx/src/shared/workspace';
 import { NormalizedOptions } from '../schema';
+import { ProjectConfiguration, TargetConfiguration } from '@nrwl/devkit';
 export declare function getServeConfig(project: ProjectConfiguration, options: NormalizedOptions): TargetConfiguration;

package/src/generators/application/lib/get-serve-config.js.map

@@ -1 +1 @@
-{"version":3,"file":"get-serve-config.js","sourceRoot":"","sources":["../../../../../../../packages/forge/src/generators/application/lib/get-serve-config.ts"],"names":[],"mappings":";;;AAKA,yCAAiD;AAEjD,SAAgB,cAAc,CAC5B,OAA6B,EAC7B,OAA0B;IAE1B,OAAO;QACL,QAAQ,EAAE,8BAA8B;QACxC,OAAO,EAAE;YACP,QAAQ,EAAE;gBACR;oBACE,OAAO,EAAE,UAAU,OAAO,CAAC,IAAI,gBAAgB;iBAChD;gBACD;oBACE,OAAO,EAAE,cAAc;iBACxB;aACF;YACD,GAAG,EAAE,IAAA,0BAAiB,EAAC,MAAM,EAAE,OAAO,CAAC,cAAc,CAAC;YACtD,QAAQ,EAAE,IAAI;SACf;KACF,CAAC;AACJ,CAAC;AAnBD,wCAmBC"}
+{"version":3,"file":"get-serve-config.js","sourceRoot":"","sources":["../../../../../../../packages/forge/src/generators/application/lib/get-serve-config.ts"],"names":[],"mappings":";;;AACA,yCAIsB;AAEtB,SAAgB,cAAc,CAC5B,OAA6B,EAC7B,OAA0B;IAE1B,OAAO;QACL,QAAQ,EAAE,8BAA8B;QACxC,OAAO,EAAE;YACP,QAAQ,EAAE;gBACR;oBACE,OAAO,EAAE,UAAU,OAAO,CAAC,IAAI,gBAAgB;iBAChD;gBACD;oBACE,OAAO,EAAE,cAAc;iBACxB;aACF;YACD,GAAG,EAAE,IAAA,0BAAiB,EAAC,MAAM,EAAE,OAAO,CAAC,cAAc,CAAC;YACtD,QAAQ,EAAE,IAAI;SACf;KACF,CAAC;AACJ,CAAC;AAnBD,wCAmBC"}