Node.js Engine

JavaScript code in a bot can run in one of two execution modes. Select the mode in the bot’s NodeJS Engine settings. The Use extended NodeJS engine toggle switches between the simple and extended modes.

Simple mode

The simple mode is the lightweight default. JavaScript functions are executed synchronously in the embedded JavaScript runtime.

Define regular functions and return their result directly:

function collectData(params) {
    return { name: params.name };
}

Do not use async, await, or asynchronous APIs that return Promises in this mode. The function is invoked synchronously, so a Promise is not awaited.

Extended Node.js mode

To enable the extended mode, turn on Use extended NodeJS engine. The package.json dependencies editor then appears, where you can declare the npm packages the bot needs:

{
    "dependencies": {
        "node-fetch": "^3.3.2"
    }
}

Dependencies are installed for the bot and the code runs in the sandboxed Node.js engine. This mode supports Node.js module loading (require and imports) and asynchronous operations such as network requests.

Functions executed by the extended engine must be Promise-compatible. Declare them as async when they await asynchronous work:

async function collectData(params) {
    const response = await fetch("https://example.com/customer/" + params.id);
    const customer = await response.json();
    return { name: customer.name };
}

This applies to prompt/pre-processing functions, tools, and tool handlers executed by the Node.js engine. A synchronous return value in extended mode causes execution to fail because the engine requires a Promise.

Resource limits

The Node.js engine can use up to 250 MB of memory and run for up to 10 seconds per execution. These limits can be adjusted within the allowed range in the NodeJS Engine settings.

Use simple mode for self-contained, synchronous transformations. Use extended mode when the bot needs npm dependencies, imports, or asynchronous code.