Async events API
Fetch API
Storage API

Rate this page:

We are currently developing a new native Node.js runtime that will eventually replace Forge's current runtime environment. This native Node.js runtime is available now as part of Forge's Early Access Program (EAP). We encourage you to test your existing apps on this new runtime for compatibility and performance.

Forge’s EAP offers experimental features to selected users for testing and feedback purposes. These features are not supported or recommended for use in production environments. They are also subject to change without notice.

For more information, see Forge EAP, Preview, and GA.

New native Node.js runtime (EAP)

You can now test the new native Node.js runtime that enables Forge functions within a standard Node.js environment. This will allow you to import any built-in, local, or third-party Node modules into your app.

Our long-term aim is to make this new runtime the default for Forge. Participating in this EAP will help you prepare and test your app for compatibility and performance.

We are releasing this new Node.js runtime under EAP to help identify bugs, compatibility problems, and unanticipated breaking changes. You can also take this opportunity to test functions blocked by the current runtime’s limited JavaScript support.

For now, apps using the new native Node.js runtime can only be deployed on staging and development environments.

Runtime changes

Forge’s current runtime uses a custom JavaScript environment to control data egress and enforce tenant isolation. The new Node.js runtime performs both security functions through an outbound proxy instead. This architectural change introduces several changes that may affect your apps:

Atlassian product APIs that redirect to external domains

App requests to Atlassian product APIs that return HTTP redirects to external domains (for example, api.media.atlassian.com for downloading Confluence attachments) will now be considered egress. As such, those domains must be declared in the application manifest. This will require users to re-consent to using the app.

HTTPS only

All external connections must be done through HTTPS; plain HTTP or TCP connections are not allowed. In addition, these connections will be implemented over a custom proxy which will only allow the following https.request options (or equivalents from third-party packages):

  • auth
  • headers
  • host
  • method
  • port
    • Only 80, 8080, 443, 8443, 8444, 7990, 8090, 8085 and 8060.
  • path

No more snapshots

Snapshots will no longer be relevant in the new Node.js runtime. If your app uses the snapshots flag in your manifest.yml file, you'll need to remove it.

Expanded responsibilities

The new native Node.js runtime’s architecture requires different methods for tenant isolation and security. This will result in some changes to your responsibilities as laid out in our Shared responsibility model. Some of these changes involve ensuring that your app:

  • Doesn't persist state between subsequent invocations
  • Doesn't copy data from one tenant to another

We will provide more details on these changes in future updates.

Benefits

The architecture of the new native Node.js runtime offers several major improvements over the current runtime. Below are two of the most important ones affecting app developers:

Full Node.js compatibility

Currently, Forge’s custom JavaScript environment only supports a subset of Node’s built-in modules. The new native Node.js runtime, on the other hand, will fully support all Node modules. This provides compatibility with all Node libraries and NPM packages, enabling you to leverage the entire JavaScript developer ecosystem.

Improved performance

The current Forge runtime sandboxes your app to control its execution. This helps secure the Forge platform, but results in a performance overhead that scales with an app’s function size.

The new native Node.js runtime’s security architecture, however, allows your app to run directly on the AWS Lambda runtime. This bypasses the Forge runtime sandbox’s performance overhead, resulting in moderate performance gains.

EAP limitations

As it is with all Forge EAP features, the Node.js runtime is still under active development. As such, we cannot guarantee its safe use outside of testing. In addition, the this release of the Node.js runtime also has the following limitations:

App logs are now visible on forge logs and the developer console. However, the reliability of these logs are subject to the following limitations:

  • Some log statements may be displayed out of order.
  • Some log messages may not be displayed if your function finishes executing before all log statements have been ingested.
  • If your function fails because it exceeds the 25-second runtime timeout, the log messages from that invocation will not be displayed.

We are actively working on addressing these limitations throughout this EAP. We will publish any related updates through the Forge changelog.

Before you begin

To participate in this EAP, your app must use the latest version of all Forge packages (for example, @forge/cli, @forge/ui, and @forge/api). Install updates for the packages your app uses, from the command line:

  • npm install -g @forge/cli@latest
  • npm install @forge/ui@latest
  • npm install @forge/api@latest

Repeat the npm install command for any other Forge packages your app uses.

During testing, we encourage you to focus on testing your current app’s code on the new runtime. This will help us identify compatibility issues with real-world apps.

In addition, you’ll also need a site on which to test the app. We recommend that you use an existing test site that already has data. During this EAP, we’ll only enable the app for your development and staging environments.

Step 1: Send us your app ID and site URL

Before you can use the new native Node.js runtime, our team needs to enable the runtime on your app and site. To do that, we’ll need your app ID and site URL.

Submit those details through the early access registration form.

Step 2: Configure your manifest file

The runtime section of the manifest.yml now features a new name property that lets you specify what runtime to use. To specify the new native Node.js runtime, set name to nodejs18.x:

1
2
app:
  runtime:
    name: nodejs18.x
  id: "ari:cloud:ecosystem::app/406d303d-0393-4ec4-ad7c-1435be94583a"

Snapshots

Snapshots no longer work in the new native Node.js runtime. If your app uses the snapshots option, remove it from the manifest.

Redirects to external domains

All requests to Atlassian product APIs that return redirects to external domains are now considered egress. If your app uses such redirects, you’ll need to add permissions for those domains in the application manifest:

1
2
permissions:
  external:
    fetch:
      backend:
        - 'https://www.example.com'

See Runtime egress permissions for detailed instructions.

Since this change involves a permission change in the manifest, users will need to re-consent to using the app.

Step 3: Deploy and install the app

The next time you deploy your app, it will be under the new native Node.js runtime. To do this:

  1. Navigate to the app's top-level directory and deploy your app by running:

    1
    2
    forge deploy
    
  2. Install your app by running:

    1
    2
    forge install
    
  3. Select your Atlassian product using the arrow keys and press the enter key.

  4. Enter the URL for your development site. For example, example.atlassian.net. View a list of your active sites at Atlassian administration.

Once the successful installation message appears, your app is installed and ready to use on the specified site. You can always delete your app from the site by running the forge uninstall command.

Running the forge install command only installs your app onto the selected product. To install onto multiple products, repeat these steps again, selecting another product each time. Note that the Atlassian Marketplace does not support cross-product apps yet.

You must run forge deploy before running forge install in any of the Forge environments.

If you wish to opt out of this EAP, revert the manifest.yml changes you made in Step 2: Configure your manifest file. The next time you re-deploy your app, it will be with the current Forge runtime environment.

Step 4: Report any bugs and send us feedback

For this EAP, we are interested in feedback relating to changes in your app’s performance under the new runtime. We expect moderate improvements for all apps; we would appreciate any benchmark data you can provide. We are particularly interested in learning which app functions are affected the most.

Please share your feedback in the private EAP discussion group on the Atlassian Community site or the EAP slack channel shared during the sign-up process.

We are also committed to resolving any compatibility problems you may have with the new native Node.js runtime. Please report them (along with any bugs) through Developer and Marketplace Support.

Rate this page: