DOCSEARCHbyAlgolia
Submit Docs

Nx Forge

website·Indexed 29 days ago

https://toolsplus.github.io/nx-forge/

A plugin for Nx that provides a structured way to build, manage, and deploy Atlassian Forge applications. It includes generators for creating Forge apps, UI Kit and Custom UI modules, and executors for managing the Forge lifecycle, including manifest transformations and project graph extensions.

Tokens
6.4K
Snippets
41
Records
54
Agent score
75%

What's inside Nx Forge

  1. Understand the purpose of Nx Forge for Atlassian app development

    Atlassian Forge requires applications to be fully self-contained at deployment, meaning all static artifacts (Custom UI or UI Kit) must reside within the Forge app root directory. This creates challenges for developers regarding code sharing between frontend and backend, managing TypeScript compilation/Babel transpilation, and scaling projects with multiple Custom UI resources.

    Nx Forge is an Nx plugin that solves these issues by treating Forge app resources (like Custom UI modules) as independent projects within an Nx workspace. This allows developers to manage, build, and test resources independently while providing a single command to build the entire Forge app and its dependencies into a deployable format.

  2. Structure a Forge workspace using Nx

    When using the Nx Forge plugin, the workspace is organized into apps and libs to ensure a modular architecture and separation of concerns. This structure allows developers to maintain multiple Forge applications or Custom UI projects in a single workspace while sharing logic via libraries.
    my-nx-workspace/
├── apps
│   ├── my-forge-app-1
│   │   |── src
│   │   |── manifest.yml
│   │   |── package.json
│   │   |── project.json
│   ├── my-forge-app-2
│   │   |── src
│   │   |── manifest.yml
│   │   |── package.json
│   │   |── project.json
│   ├── custom-ui-a
│   ├── ui-kit-ui-b
├── libs
|   ├── shared-api-code
|   ├── shared-ui-code
├── dist
├── nx.json
└── package.json

  3. Understand how Nx Forge extends the Nx project graph

    Nx Forge extends the standard Nx project graph to integrate Forge applications and their dependencies. It automatically identifies Forge application projects by detecting a manifest.yml file in the project root. This allows Nx to manage task dependencies (like builds) and ensures that dependent projects are processed before the Forge application itself.

  4. Update @toolsplus/nx-forge to the latest version

    Starting with plugin version 2.2.0, @toolsplus/nx-forge includes migration scripts. To update the workspace to the latest version of the plugin, use the nx migrate command. After running the command, follow the instructions provided in the terminal output to complete the migration process.
    nx migrate @toolsplus/nx-forge@latest

  5. Add a Custom UI module to a Forge app

    Forge apps require at least one module for deployment. To add a React-based Custom UI module:

    1. Add React support to the workspace.
    2. Generate a React application.
    3. Configure the bundler (Webpack or Vite) to use relative paths for assets to ensure compatibility with Forge.
    # 1. Add React support
nx add @nx/react@23

# 2. Generate the React app
nx g @nx/react:app apps/<custom-ui-app-name>

  6. Build and package a Forge app for deployment

    To create a deployable artifact for the Forge platform, a Forge app must undergo a two-step process: build followed by package.

    1. build: Compiles and bundles TypeScript code. This can be handled by any standard Nx bundling plugin (e.g., @nx/webpack or @nx/esbuild). The output must be produced into a src directory to satisfy Forge CLI requirements.
    2. package: Provided by the Nx Forge plugin. This target completes the artifact by copying the manifest.yml file, including outputs from dependent resource projects (like Custom UI or UI Kits), and generating a package.json containing all Forge app dependencies.
    # Conceptual sequence to get a deployable artifact
nx build <project-name>
nx package <project-name>

  7. Register, deploy, and install a Forge app

    Follow these steps to move a Forge app from local development to an Atlassian site:

    1. Package: Build and package the app.
    2. Register: Register the app with the Forge platform. Use --appName to specify a custom name.
    3. Deploy: Deploy to the default development environment.
    4. Install: Install the app on a specific site using the nx forge executor.
    # 1. Package
nx run <nx-forge-app-name>:package

# 2. Register
nx run <nx-forge-app-name>:register --appName="My Forge App"

# 3. Deploy
nx run <nx-forge-app-name>:deploy

# 4. Install
nx forge <nx-forge-app-name> install --site <my-atlassian-site.atlassian.net> --product jira --non-interactive

  9. Test and develop manifest transforms

    To test JSONata expressions before applying them to the manifest, convert your manifest.yml content to JSON and use the JSONata Exerciser. To emulate the $env function during testing, use a lookup object as shown in the example.
    (
    $env := $lookup({
        'CONNECT_APP_KEY': 'io.toolsplus.hello',
        'CONNECT_REMOTE_BASE_URL': 'https://connect-base-url.com'
    }, ?);
    
    $ ~> |app.connect|{'key': $env('CONNECT_APP_KEY')}| 
      ~> |remotes[key='connect']|{'baseUrl': $env('CONNECT_REMOTE_BASE_URL')}|
)

  10. Migrate Nx Forge projects to inferred tasks

    Since Nx version 18 and Nx Forge plugin version 5.1.0, all targets provided by the plugin can be automatically inferred based on tool configuration. To migrate existing projects to inferred tasks, remove the plugin-provided target definitions from the app's project.json files. New Forge apps generated with plugin version 5.1.0+ use inferred targets by default and will not have these definitions in project.json.

  12. Access Nx Forge best practice examples

    For implementation patterns and current best practices when using Nx Forge, refer to the official Nx Forge Examples repository. This repository is maintained to provide up-to-date examples of how to structure and configure Nx Forge projects.
    # Clone the Nx Forge examples repository
git clone https://github.com/toolsplus/nx-forge-examples