The new native Node.js runtime is now in preview, and will eventually replace Forge’s current runtime environment. We strongly encourage you to test your apps on this new runtime for compatibility and performance.

This new runtime introduces several changes to the way security and egress controls work. Sandboxing and snapshots (including related settings and restrictions) are no longer relevant in the new runtime as well. These changes may result in additional developer responsibilities to help uphold Forge's security.

This section describes a Forge preview feature. Preview features are deemed stable; however, they remain under active development and may be subject to shorter deprecation windows. Preview features are suitable for early adopters in production environments.

We release preview features so partners and developers can study, test, and integrate them prior to General Availability (GA). For more information, see Forge release phases: EAP, Preview, and GA.

New native Node.js runtime (Preview)

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

This new runtime environment is now fully supported. This means that apps using this runtime environment can now be deployed on production environments.

We strongly recommend that you test your app in this environment for compatibility and performance. Eventually, the new native Node.js runtime will become the default for Forge.

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

Forge’s current runtime is a custom JavaScript environment that 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. Sandboxing in this way comes with a performance penalty, where your app slows down as your bundle size grows larger.

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

In addition, the new native Node.js runtime has 512MB or memory available per invocation. This is 4x of what the current runtime provides.

New AppContext API

The new AppContext API is only available for the new native Node.js runtime, see AppContext API for more details.

Breaking 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 (among others) introduces several updates that may require code changes to your apps.

APIs that redirect to external domains

App requests to Atlassian product APIs that return HTTP redirects to external domains 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.

We are currently assessing which domains should be exempt from this egress declaration. For example, api.media.atlassian.com will likely be exempted in the future, as it is an Atlassian-owned domain (and as such, should not require disclosure to customers if the app communicates with it).

Node.js LTS version

The current runtime runs on an environment that mimics Node.js 14. The new native Node.js runtime uses Node.js 18, and we intend to support newer versions as they become LTS. If your app is affected by any breaking changes between both versions, you’ll need to address these.

New invocation semantics

The current runtime uses a v8 JavaScript isolate sandbox. This sandbox is bootstrapped for every invocation, providing a clean context for each invocation of your app.

The new native Node.js runtime handles isolation (and, by extension, security) at the VM layer, making the sandbox unnecessary. As such, we removed this sandbox; this, incidentally, moderately improves Forge’s invocation performance.

Expanded developer responsibilities

The removal of the v8 JavaScript isolate sandbox no longer guarantees that local state in your Forge functions is cleared for each invocation. As such, the new native Node.js runtime introduces new responsibilities for you as a developer to ensure that customer data does not persist across app invocations. These responsibilities are laid out in our shared responsibility model.

To comply with these new developer responsibilities, review your app code to ensure that:

  • Your app must not persist customer data or sensitive content in global state, in memory or on disk, between subsequent invocations.
  • Your app must not copy customer data or sensitive content from one installation to another, unless it has been explicitly permitted by the customer.

Snapshot removal

The snapshotting feature is no longer supported in the new native Node.js runtime, as it is no longer required. This feature was enabled by default in the current runtime. If your app uses the snapshots flag in your manifest.yml file, you'll need to remove it.

When snapshotting is enabled, the current runtime invokes any globally-scoped JavaScript code at deployment time rather than invocation time.

With the new native Node.js runtime, your app may be re-initialised if it wasn’t used for a long time, or if it needs to execute multiple times simultaneously. If your app requires globally-scoped code to be executed exactly once per deployment, this change in invocation semantics may require changes to your app.

Delayed code execution

The new native Node.js runtime might keep executing the code after the function returns. For example:

1
2
resolver.define("example", () => {
  setTimeout(() => {
    fetch("...");
  }, 5000);
});

On the current runtime, the setTimeout function will execute, but not the fetch call. On the new native Node.js runtime, timers and other asynchronous code may continue executing even after the Forge function returns a response.

If you previously used the setTimeout function to set a condition for dealing with Forge function timeouts, you may need to re-assess this approach.

Default Content-Type header no longer set

Outbound HTTP requests previously assumed a Content-type: application/json if a content type was not specified. This default is no longer applied to requests to external domains using the fetch function or other HTTP clients.

For the GA release of the native Node.js runtime, this default will be applied when making API calls using requestJira, requestConfluence and requestBitbucket in order to improve backwards compatibility.

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

Sending a request with a body still works, as long as you specify the correct Content-Type: header (for example, Content-Type: application/json for a JSON body).

Custom https and console implementations

While the new runtime uses full Node.js environment, some https and console methods are replaced with custom implementations that ensure external connections and logs connect to the Forge platform.

Environmental changes

The new native Node.js runtime also introduces several changes to the way developers interact with Forge. The following changes may require changes to your development processes, but not your app.

No Docker when tunnelling

The new native Node.js runtime no longer requires a local Docker image for invoking your Forge functions locally. This simplifies the local toolchain for setting up the tunnel, and will improve the performance of your tunnel.

However, this new implementation makes it possible for functions to succeed in your local environment but fail when deployed to Forge. This may be caused by variations in your local environment. To prevent this, ensure the following:

  1. Your local environment uses the same version of Node.js used by deployed Forge apps (currently Node.js 18.x).
  2. Your local Node.js environment does not include any additional dependencies or libraries that are not provided out-of-the-box by Node.js or bundled directly by your app.

We are evaluating support for an optional Docker image for tunnelling, based on level of feedback and interest from Forge app developers.

No more tunnel debugging

The forge tunnel command no longer supports attaching an interactive debugger to your locally running Forge function. As such, the --debug option of forge tunnel is no longer supported.

We are evaluating re-introducing support for debuggers in the future, based on level of feedback and interest from Forge app developers.

IP address range changes for outgoing connections

Outgoing connections for Forge apps currently originate from a VPC configured in the Atlassian cloud environment where the Forge functions are executed. For apps deployed on the Native Node.js runtime, outgoing connections will originate from Atlassian’s cloud infrastructure (specifically, the IP addresses listed here).

This could be a breaking change for customers who use IP allowlisting to permit Forge apps to communicate with their Atlassian products or other SaaS or on-premises software.

We strongly recommend that you communicate directly with your customers if they will be impacted by this change.

Known limitations

The new native Node.js runtime is fully supported and deemed safe for production use. However, we are still working on resolving some existing limitations before GA:

Before you begin

The new native Node.js runtime requires 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.

Step 1: Configure your manifest file

The runtime section of the manifest.yml file 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"

Adding the name property to the manifest file will not trigger a major upgrade. As such, deploying this change alone to production will automatically install it on all sites.

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 your manifest file:

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 2: Deploy and install the app for testing

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

  1. Navigate to the app's top-level directory and deploy your app to the development environment by running:
    1
    2
    forge deploy --environment development
    
  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, you can start testing your app. 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.

To opt out of the new native Node.js runtime, revert the manifest.yml changes you made in Step 1. The next time you re-deploy your app, it will be with the current Forge runtime environment.

Step 3: Report any bugs

We worked hard to ensure backwards compatibility with the existing Forge runtime in order to minimise the effort of adopting the new native Node.js runtime. We are also committed to resolving any compatibility or performance problems you have; please report them (along with any bugs) through Developer and Marketplace Support.

Step 4: Deploy your app to production

If you’re satisfied with your app’s performance and functionality with the new native Node.js runtime, deploy it to your customers. Navigate to the app's top-level directory and deploy your app to production environment by running:

1
2
forge deploy --environment production

Rate this page: