Rate this page:
The Forge app runtime includes a set of APIs that provide additional functionality to the Forge platform. You can use these APIs to interact with REST endpoints and to store data.
We are developing a new native Node.js runtime to replace Forge's current runtime environment. This new runtime introduces several changes to the way security and egress controls work. Sandboxing and snapshots (including any 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 native Node.js runtime is available now as part of Forge's Early Access Program (EAP). For information about testing this new runtime, see Native Node.js runtime (EAP).
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.
To access Forge APIs from your app, first install the latest API package by running:
1 2npm install @forge/api
This package will enable the use of the following APIs:
When a Forge app is invoked, the JavaScript code is executed within the app sandbox. This environment differs from a traditional Node.js environment you might already be familiar with. Learn more about the app sandbox.
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
which 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.
The invocation context is a function that gets called on invocation time. Each module receives different request parameters based on the module type.
The invocation context has a maximum timeout of 25 seconds. Your function will be stopped and will result in an error if processing exceeds the time limit. Learn more about platform limits
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.
The snapshots
flag is available under the runtime object with a default value of true
.
1 2app: runtime: snapshots: true # Boolean
Environment variables are not available in the snapshot context.
1 2const 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.
1 2const 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.
1 2const snapshotContextBuffer = new Buffer(); // May result in unpredictable behavior export const run = () => { // ... };
The global process object is a partial implementation of the Node JS process.
1 2process
Key | Value |
---|---|
platform | forge |
env | See Environments. |
version | The underlying Node JS version. Example: process.version // 12.14.1
|
versions | Versions of runtime dependencies. Example: {
forge: 'forge:47',
node: '12.14.1'
}
|
nextTick | A polyfill of Node JS nextTick. |
Rate this page: