docs: update docs

update getting started guide; add migration docs for inferred targets and package executor; add plugin concept docs

docs/.vitepress/config.mts

@@ -23,7 +23,7 @@ export default defineConfig({
       {text: 'Home', link: '/'},
       {text: 'Guides', link: '/guides/getting-started', activeMatch: '/guides/'},
       {text: 'Reference', link: '/reference/generators', activeMatch: '/reference/'},
-      {text: 'Concepts', link: '/concepts/motivation', activeMatch: '/concepts/'},
+      {text: 'Concepts', link: '/concepts/plugin-concepts', activeMatch: '/concepts/'},
       {text: 'Discussions', link: '/~https://github.com/toolsplus/nx-forge/discussions'},
       {text: 'Releases', link: '/~https://github.com/toolsplus/nx-forge/releases'},
       {text: 'Contributing', link: '/~https://github.com/toolsplus/nx-forge/blob/main/CONTRIBUTING.md'}
@@ -51,6 +51,8 @@ export default defineConfig({
             text: 'Maintenance',
             items: [
               {text: 'Migrating to a newer plugin version', link: 'migrating-plugin-version'},
+              {text: 'Migrating to the package executor', link: 'migrating-to-package-executor'},
+              {text: 'Migrating to inferred tasks', link: 'migrating-to-inferred-tasks'},
             ]
           },
           {
@@ -80,6 +82,7 @@ export default defineConfig({
           {
             text: 'Concepts',
             items: [
+              {text: 'Plugin concepts', link: 'plugin-concepts'},
               {text: 'Motivation', link: 'motivation'},
               {text: 'Workspace layout', link: 'workspace-layout'},
               {text: 'Project graph', link: 'project-graph'}

docs/concepts/plugin-concepts.md

@@ -0,0 +1,26 @@
+# Plugin concepts
+
+This page summarizes the main Nx Forge plugin concepts and ideas.
+
+## Building Forge apps
+
+When using [the app generator](../guides/generating-a-forge-app.md) to scaffold a Forge app, you will get a Nx project with a build target and a collection of inferred targets provided by the Nx Forge plugin.
+
+The most important thing to know is that to deploy a Forge app, you need to run the following executors to get an artifact that can be deployed to the Forge platform:
+
+::: tip Executors to get a deployable Forge app artifact
+
+build -> package
+
+:::
+
+The `build` target is meant to compile and bundle the app's Typescript code. This can be done by any standard Nx plugin that supports bundling node applications, for example `@nx/webpack` or `@nx/esbuild`. The main Forge requirement is that the output is produced into a `src` directory (a Forge CLI quirk, probably because the CLI itself wants to support Typescript compilation and bundle the code).
+
+The `package` target is provided by Nx Forge and completes the output generated by the `build` target to an artifact that can be deployed to the Forge platform. This includes, copying the manifest.yml file to the output, copying the outputs of dependent resource project (Custom UI or UI Kit) to the Forge app, as well as generating a package.json file that includes all the Forge app dependencies.
+
+Once, the `build` and `package` stages have run, the Forge app can be deployed. Because it is so common to run these tasks in sequence, it is worth [defining target defaults for them](../guides/getting-started.md#configuring-target-defaults). Nx caches builds, so there is hardly any overhead to always running when calling the `deploy` target.
+
+## Plugin targets
+
+The Nx Forge plugin provides [a set of executors](../reference/executors.md) that assist with developing, building and deploying Forge apps in a Nx workspace. The plugin provides specific [`register`](../reference/executors.md#register) or [`deploy`](../reference/executors.md#deploy) executors which should be used over the Forge CLI command. They facilitate the integration with the Nx workspace and provide additional features.
+In cases where the plugin does not provide specific executors, it is recommended to use the [`forge`](../reference/executors.md#forge) executor to invoke the Forge CLI. This will ensure that the command runs from the app's output directory in the Nx workspace.

docs/guides/generating-a-forge-app.md

@@ -17,10 +17,12 @@ nx g @toolsplus/nx-forge:app <nx-forge-app-name>
 
 Refer to [the generator reference documentation](../reference/generators#application) for details on the available generator options.
 
-When the generator completes, you have a blank Forge app project. In most cases, you would want to run the [Forge register command](../reference/executors#register) immediately after that:
+When the generator completes, you have a blank Forge app project. To register the new app with the Forge platform, run the following [build](../reference/executors#build), [package](../reference/executors#package), and [register](../reference/executors#register) commands in this order:
 
 ```shell
+nx build <nx-forge-app-name>
+nx package <nx-forge-app-name>
 nx register <nx-forge-app-name> --appName="My Forge App"
 ```
 
-This command will register the newly created app with the Forge platform and update the `app.id` in the manifest file to the value returned from the registration.
+The register command updates the `app.id` in the manifest file to the value returned from the registration.

docs/guides/getting-started.md

@@ -20,17 +20,29 @@ You will be asked if you would like to use Nx Cloud and/or remote caching. Eithe
 
 ## Setting up
 
+:::info
+
+The following steps assume that nx is installed globally. If you have not, you can do so by running `npm install -g nx`.
+
+:::
+
+### Installing Nx Console
+
+Nx Console is the Nx IDE plugin for VSCode and JetBrains IDEs. This step is optional, however, if you are new to Nx or generally prefer a user interface over a terminal, we highly recommend installing Nx Console: https://nx.dev/getting-started/editor-setup
+
+With Nx Console, you can run generator and executor commands from your IDE user interface instead of using the terminal. It also helps with task discovery, since [plugin targets are inferred](https://nx.dev/concepts/inferred-tasks) from configuration instead of explicitly defined (where possible).
+
 ### Installing the plugin
 
 Add the plugin to your Nx workspace using
 
 ```shell
-npm install --save-dev @toolsplus/nx-forge@latest
+nx add @toolsplus/nx-forge
 ```
 
 :::tip NOTE
 
-Ensure that Nx peer dependency version listed in the nx-forge package matches the Nx major version of your workspace. If you are starting new, most of the time `latest` should be fine. If you use an older Nx version, please install the nx-forge plugin version accordingly. 
+The plugin is compatible with Nx version {{nxVersion}}. If you use an older Nx version, we recommend upgrading to avoid compatibility issues. 
 
 :::
 
@@ -39,7 +51,7 @@ Ensure that Nx peer dependency version listed in the nx-forge package matches th
 Once installed, run the Forge app generator to generate a Forge app. Replace `<nx-forge-app-name>` with the name of the app you want to create. You can add the `--dry-run` flag to preview what will be generated.
 
 ```shell
-npx nx g @toolsplus/nx-forge:app <nx-forge-app-name> --directory apps/<nx-forge-app-name> --projectNameAndRootFormat as-provided
+nx g @toolsplus/nx-forge:app <nx-forge-app-name> --directory apps/<nx-forge-app-name> --projectNameAndRootFormat as-provided
 ```
 
 :::info
@@ -50,10 +62,16 @@ Starting with Nx 20 the flag `--projectNameAndRootFormat as-provided` will becom
 
 ### Adding 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 installed `@nx/react` in your workspace, call `npm add -D @nx/react@{{nxVersion}}`. This plugin allows us to generate a React application for our Custom UI. Replace `<custom-ui-app-name>` with the name of the Custom UI project you want to create. You can add the `--dry-run` flag to preview what will be generated.
+Forge apps require at least one module before they can be deployed. Let's start with a simple Custom UI module to get started. Run the following command from the workspace root to add Nx React support:
+
+```shell-vue
+nx add @nx/react@{{nxVersion}}
+```
+
+This plugin allows us to generate a React application for our Custom UI. Replace `<custom-ui-app-name>` with the name of the Custom UI project you want to create. You can add the `--dry-run` flag to preview what will be generated.
 
 ```shell
-npx nx g @nx/react:app <custom-ui-app-name>
+nx g @nx/react:app <custom-ui-app-name>
 ```
 
 
@@ -117,83 +135,60 @@ app:
 
 The most significant bit to note here is that the `path` property of the `project-page` resource must reference the Custom UI project name from the previous step. This declaration tells the Nx Forge plugin which Nx app project corresponds to the `project-page` resource. The plugin will replace this path with the path to the actual Custom UI build artifact during the Forge app build. Refer to [the project graph concept documentation](../concepts/project-graph) for further details.
 
-### Configuring targets dependencies
+### Configuring target defaults
 
-Configure `build` target dependencies to ensure Nx builds the Custom UI project before the Forge app. Open the `nx.json` file in your workspace root and update the `targetDefault as follows:
+Technically, we already have everything in place to build, package, and deploy our Forge app. However, to make our lives even easier, it is helpful to configure a few target defaults. Open the `nx.json` file in your workspace root and update or add the `targetDefaults` as follows:
 
 ::: code-group
 ```json{4-8}[nx.json]:line-numbers
 {
   ...
   "targetDefaults": {
-    "build": {
-      "cache": true,
-      "dependsOn": ["^build"],
-      "inputs": ["production", "^production"]
-    },
-    ...
-  },
-  ...
-}
-```
-:::
-
-This setting tells Nx that when we call the `build` target on a project, it should first run the `build` target on all dependent projects ([`^build`](https://nx.dev/reference/project-configuration#dependson)). This works because Nx knows about project dependencies.
-
-Feel free to customize and play around with these settings to tune them to your liking. For example, another helpful setting could be to run the `build` target before the [`package` target](../reference/executors.md#package) runs:
-
-::: code-group
-```json{9-15}[nx.json]:line-numbers
-{
-  ...
-  "targetDefaults": {
-    "build": {
-      "cache": true,
-      "dependsOn": ["^build"],
-      "inputs": ["production", "^production"]
+    "deploy": {
+      "dependsOn": ["package"],
     },
     "package": {
       "dependsOn": ["build"],
-      "executor": "@toolsplus/nx-forge:package",
-      "options": {
-        "outputPath": "dist/{projectRoot}"
-      }
-    }
+    },
     ...
   },
   ...
 }
 ```
 :::
 
+These settings tell Nx that when we call the `deploy` target on a project, it should first run the `package` target. Additionally, we make the `package` target dependent on the `build` target. With these ([target dependencies](https://nx.dev/reference/project-configuration#dependson)) in place, we can call `nx deploy <nx-forge-app-name>`, and Nx will ensure that the app is first built, then packaged and finally deployed.
+
+Feel free to customize and play around with these settings to tune them to your liking.
+
 ### Initial build, registration, deployment, and installation
 
-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
+Before you can deploy the Forge app it needs to be registered with the Forge platform. To do this, initially build and package the Forge app (assuming you have configured the target dependencies above):
 
 ```shell
-npx nx build <nx-forge-app-name>
+nx package <nx-forge-app-name>
 ```
 
 Once that's finished, run
 
 ```shell
-npx nx register <nx-forge-app-name>
+nx register <nx-forge-app-name>
 ```
 
 This command will use `<nx-forge-app-name>` by default as the app name on the Forge platform. If you would like to use a different name, add the app name flag as follows: `--appName="My Forge App"`.
 
 Then run
 
 ```shell
-npx nx deploy <nx-forge-app-name>
+nx deploy <nx-forge-app-name>
 ```
 
 to deploy the Forge app to the default development environment.
 
 Finally, install the app on any of your sites with the following command
 
 ```shell
-npx nx install <nx-forge-app-name> --site <my-atlassian-site.atlassian.net> --product jira --no-interactive
+nx install <nx-forge-app-name> --site <my-atlassian-site.atlassian.net> --product jira --no-interactive
 ```
 
 :tada: The Forge app is now registered, deployed, and installed with the Forge platform.

docs/guides/migrating-to-inferred-tasks.md

@@ -0,0 +1,15 @@
+# Migrating to inferred tasks
+
+Since Nx version 18, Nx plugins can automatically infer tasks for your projects based on the configuration of different tools. Refer to the [Nx docs on inferred tasks (Project Crystal)](https://nx.dev/concepts/inferred-tasks) for more details.
+
+::: tip Nx Console
+
+If you are not using Nx Console yet, we [highly recommend installing it](./getting-started.md#installing-nx-console) when moving to inferred tasks as it helps you discover tasks and run them from your IDE's user interface.
+
+:::
+
+Staring with Nx Forge plugin version 4.0.0, the plugin could infer targets for Forge app projects and since plugin version 5.1.0, the plugin generates Forge apps with inferred targets. This means, if you generate a new Forge app, you will not see any target definitions in the app's `project.json` file if they can be inferred.
+
+As of plugin version 5.1.0, all [executor targets provided by the plugin](../reference/executors.md) can be inferred (except for the deprecated `build` executor). This means, to migrate to inferred tasks, you can simply remove those from your app's `project.json` files.
+
+From our experience, transitioning the configuration to inferred tasks can be tricky. If you run into issues, it often helps to [generate a clean Nx test workspace](./getting-started.md#prerequisites), run the app generators you are interested in and compare the generated configuration in `project.json` files and the `nx.json` with your existing workspace.

docs/guides/migrating-to-package-executor.md

@@ -0,0 +1,20 @@
+# Migrating to the package executor
+
+Since plugin version 5.1.0, the existing `build` executor has been deprecated in favor of a Nx native build in combination with the `package` executor.
+
+For all the details and motivation of this change refer to [the discussion on GitHub](/~https://github.com/toolsplus/nx-forge/discussions/86).
+
+## Migration steps
+
+1. Ensure you are on the latest plugin version by running:
+
+   `nx add @toolsplus/nx-forge@latest`.
+2. [Generate a new Forge app](./generating-a-forge-app.md) with the updated app generator. Make sure to set the `bundler` option to [choose if the `build` task should be run by Webpack or esbuild](../reference/generators.md#application). You do not need to run the `build`, `package`, or `register` tasks. Generating this Forge app will ensure you have the correct dependencies installed and your workspace is configured to work with Webpack or esbuild.
+3. a) If you chose the Webpack bundler option (default): 
+
+   Copy the `webpack.config.js` to your app's project directory and update the `output.path` to match your project layout. Delete the existing `build` target configuration.
+
+   b) If you chose the esbuild bundler option:
+
+   Copy the `build` target configuration from the generated app's `project.json` and replace the existing `build` target configuration in your app's `project.json`. Adjust the path configurations in the `build` target to match your project layout.
+4. Run `nx g @nx/workspace:remove --projectName=<genrated-forge-app>` to remove the app generated in step 2.