Nx Forge

Appearance

Executors ​

Documents the executors provided by the Nx Forge plugin.

Append --help or -h for any of the plugin executors to explore all available options.

Forge ​

shell
nx forge <nx-forge-app-name> <forge-cli-options>

Runs any Forge CLI command in the <nx-forge-app-name> output directory. Refer to the Forge CLI reference documentation for a list of all available commands.

INFO

Where a custom executor is provided by Nx Forge, prefer using the custom executor over calling the Forge CLI directly.

Properties

  • outputPath required
    • The output path of the Forge app files.
    • Type: string

Nx Forge-provided executors ensure that the Nx project configuration is updated where necessary when the Forge command has run. For example, registering a Forge app using nx forge <nx-forge-app-name> register will invoke the Forge CLI directly and only update the Forge app ID in the manifest file in the output directory. The next time you run nx build <nx-forge-app-name> the manifest file in the output path will be overwritten. The correct way to do this is to run nx register <nx-forge-app-name>, which will update the app ID of the manifest.yml within the <nx-forge-app-name> project root.

Build Deprecated ​

shell
nx build <nx-forge-app-name>

Builds the Forge app project named <nx-forge-app-name> to the directory specified in the outputPath property. If the Forge app project has dependent resource projects (Custom UI), this will build dependent projects first before building the Forge app itself.

WARNING

The build executor is deprecated in favor of a native Nx build (webpack or esbuild) in combination with the package executor. Refer to the migration guide for more information.

Properties

  • outputPath required
    • Output path of the generated files.
    • Type: string
  • customUIPath
    • Custom UI output path relative to the outputPath.
    • Type: string
  • resourceOutputPathMap
    • Map of resource project names to their respective output path (relative to the workspace root).
    • Type: object
    • Default: {}
  • watch
    • Enable re-building when files change.
    • Type: boolean
    • Default: false
  • sourceMap
    • Output sourcemaps. Use 'hidden' for use with error reporting tools without generating sourcemap comment.
  • webpackConfig
  • uiKit2Packaging Experimental
    • Enables UI Kit 2 compatible packaging.
    • Type: boolean
    • Default: false

Package ​

shell
nx package <nx-forge-app-name>

Packages the Forge app project named <nx-forge-app-name> into a deployable artifact accepted by the Forge platform. Expects the build output from <nx-forge-app-name> app to be available in the outputPath directory.

INFO

The package executor is intended to be used with a standard Nx build executor, for example, Webpack or esbuild. Refer to the migration guide for more information.

Properties

  • outputPath required
    • Output path of the generated files.
    • Type: string
  • resourcePath
    • Path where resource files such as Custom UI output is placed relative to the outputPath.
    • Type: string
  • resourceOutputPathMap
    • Map of resource project names to their respective output path (relative to the workspace root).
    • Type: object
    • Default: {}
  • tsConfig
    • The path for the TypeScript configuration file, relative to the current project.
    • Type: string
    • Default: "tsconfig.app.json"
  • uiKit2Packaging Experimental
    • Enables UI Kit 2 compatible packaging.
    • Type: boolean
    • Default: false

This executor will copy the output of dependent resource project builds to the resourcePath directory. To do this, the executor tries to infer the output path of dependent resources (Custom UI, UI Kit 2) from the dependent project's build target configuration as follows:

  1. if a mapping is defined using resourceOutputPathMap use the mapping
  2. else if the build target definition has options.outputPath define use that
  3. else use the build target's outputs definition, if there is only one entry

In cases where the output path cannot be inferred or is inferred incorrectly, the output path should be defined explicitly using the resourceOutputPathMap option.

Deploy ​

shell
nx deploy <nx-forge-app-name>

Deploys the Forge app project named <nx-forge-app-name> to the Forge platform.

Mirrors the deploy command of the Forge CLI.

Properties

  • outputPath required
    • The output path of the Forge app files.
    • Type: string
  • environment
    • Environment to deploy to.
    • Type: string
    • Default: "development"
  • verify
    • Run pre-deployment checks.
    • Type: boolean
    • Default: true
  • interactive
    • Run deployment with or without input prompts.
    • Type: boolean
    • Default: true
  • verbose
    • Run deployment in verbose mode.
    • Type: boolean
    • Default: false
  • manifestTransform
    • A JSONata expression that transforms the manifest.yml content before the deployment.
    • Type: string

For details on how to use the manifestTransform parameter, refer to the guide on transforming the manifest.

Register ​

shell
nx register <nx-forge-app-name>

Registers the Forge app project named <nx-forge-app-name> with the Forge platform. This command will automatically update the manifest file in the <nx-forge-app-name> project with the generated app id.

Mirrors the register command of the Forge CLI.

Properties

  • outputPath required
    • The output path of the Forge app files.
    • Type: string
  • appName required
    • Name of the app on the Forge platform. The app name can include dashes, spaces, and underscores. Defaults to the project name
    • Type: string
  • verbose
    • Run registration in verbose mode.
    • Type: boolean
    • Default: false

Install ​

shell
nx install <nx-forge-app-name>

Installs the Forge app project named <nx-forge-app-name> for the given site and product. The CLI will prompt for site, product if they are not provided as parameters.

Mirrors the install command of the Forge CLI.

Properties

  • outputPath required
    • The output path of the Forge app files.
    • Type: string
  • site required
    • Atlassian site URL (example.atlassian.net)
    • Type: string
  • product required
    • Atlassian product: jira, confluence, compass, bitbucket
    • Type: string
    • The value is restricted to the following:
      1. "jira"
      2. "confluence"
      3. "compass"
      4. "bitbucket"
  • environment
    • Environment to install to.
    • Type: string
    • Default: "development"
  • upgrade
    • Upgrade an existing installation.
    • Type: boolean
    • Default: false
  • confirmScopes
    • Skip confirmation of scopes for the app before installing or upgrading the app.
    • Type: boolean
    • Default: false
  • interactive
    • Run installation with or without input prompts.
    • Type: boolean
    • Default: true
  • verbose
    • Run installation in verbose mode.
    • Type: boolean
    • Default: false

Tunnel Experimental ​

shell
nx serve <nx-forge-app-name>

Starts the serve target for all Custom UI projects defined in the manifest.yml of the Forge app project named <nx-forge-app-name> on their specified tunnel port. After that, starts a build process in watch mode for the Forge app itself, before ultimately, starting the nx-forge tunnel process for the Forge app.

Mirrors the tunnel command of the Forge CLI.

Properties

  • outputPath required
    • The output path of the Forge app files.
    • Type: string
  • debug
    • Run Forge tunnel in debug mode.
    • Type: boolean
    • Default: false
  • verbose
    • Run Forge tunnel in verbose mode.
    • Type: boolean
    • Default: false

Released under the MIT License.

Copyright © 2024-present ToolsPlus