Legacy runtime reference

As of Forge CLI version 9.0.0, all new Forge apps are deployed by default on the latest Forge runtime. This runtime provides several security and performance enhancements, along with greater compatibility with the Node.js ecosystem. We strongly advise developers to run all Forge apps on the latest runtime version.

This page describes the environment, features, and security of the legacy runtime version. This information is provided as a reference for developers who may still need it while upgrading to the latest runtime version.


The legacy runtime was designed to sandbox apps to control app execution. There are two main parts to this: user interface security and the app runtime.

App runtime

The legacy runtime sandboxes the apps from the environment in which they execute. By running apps in isolated environments, the platform limits what apps can do. For example:

  • Apps cannot accidentally leak customer data across sites.
  • Apps cannot interfere with or modify other running apps.

To understand how this works in detail, see the diagram and notes on the Forge app sandbox below:

Diagram of Forge app sandbox

Javascript environment

When a Forge app is invoked, the legacy runtime executes the code within the app sandbox. This environment differs from a traditional Node.js environment.

You'll need to write your functions in a subset of Node.js. Some globals are not exposed, for example:

  • process (except for process.env)
  • queueMicrotask

This means that some NPM packages that depend on these may not function correctly. The following Node.js built-in modules are not supported:

  • async_hooks
  • child_process
  • cluster
  • constants
  • dgram
  • dns
  • domain
  • http2
  • module
  • net
  • perf_hooks
  • readline
  • repl
  • sys
  • tls
  • trace_events
  • tty
  • v8
  • vm
  • worker_threads

Snapshots and snapshot context

Snapshot is the mechanism of evaluating your function's global scope at each deployment of the app, rather than at every invocation. Forge apps use snapshots by default, as this improves the response time for your app. You can disable snapshots, but this means your app needs to be fully evaluated on each invocation. For this reason, you should consider leaving snapshots enabled.

The following image highlights a sample snapshot context. Note that the invocation method is not run at this point in time.

A code editor showing the constants declared in the snapshot context

The snapshots flag is available under the runtime object with a default value of true.

    snapshots: true # Boolean


Environment variables

Environment variables are not available in the snapshot context.


const myVariable = process.env.MY_VARIABLE;

export const run = () => {
  console.log(myVariable) // Value is undefined


Random values created at snapshot time are not random on each function invocation.


const snapshotContextRandom = Math.random();

export const run = () => {
  console.log(snapshotContextRandom); // Same value per invocation


We discourage using Buffers in the snapshot context. Warnings will be presented at deploy time if this is detected.

const snapshotContextBuffer = new Buffer(); // May result in unpredictable behavior

export const run = () => {
  // ...

Standard globals


The global process object is a partial implementation of the Node JS process.

Object signature



Rate this page: