Skip to main content

Execute JavaScript with the Code block

Learn how to use JavaScript code in a workflow.

JavaScript is the primary method for manipulating and transforming data in Retool. Use Code blocks to write custom JavaScript code that can transform data and perform complex logic. You can also use popular JavaScript libraries to further extend the functionality of workflows.

Add a JavaScript Code block​

To use JavaScript in a workflow, add a Code block to the canvas and select JavaScript.

Write and execute JavaScript code​

You can build complex logic or manipulate data using JavaScript methods like map(). For example, you could transform an array of customer records using map():

Map
const data = query1.data;

return data.map((customer) => ({
  fullName: customer.name,
  emailAddress: customer.email,
}));

In general, Retool recommends you visually construct conditional statements with Branch blocks or filter query results using Filter blocks.

JavaScript Code blocks can also call functions—reusable blocks that operate outside the workflow control flow. Functions allow your workflow to perform actions only when required and can receive parameters to use.

Use JavaScript libraries​

Retool includes support for a selection of popular JavaScript libraries which you can use in a workflow. You can browse and add libraries, configure their imports, and use them in your workflow.

Built-in libraries​

To use a built-in JavaScript library:

  1. Open the Libraries tab click +.
  2. Search for the library you want to include and then toggle the checkbox to make it available.

You can browse through all the built-in JavaScript libraries below. Some libraries are only available on self-hosted deployments.

Demo

Add custom libraries​

Retool uses NsJail to sandbox the creation of execution environments for custom libraries. NsJail requires privileged container access.

Privileged mode is not supported by ECS/Fargate deployments. To make use of custom libraries, you must either:

  • Migrate to an ECS/EC2 deployment or another supported deployment framework.
  • Host the code-executor service in a separate "jailed" cluster that can run containers in privileged mode on ECS/EC2 or another supported deployment framework. You then configure the CODE_EXECUTOR_INGRESS_DOMAIN environment variable to communicate with the code-executor service over http or https.

Both Cloud and self-hosted organizations can import public packages from npm. Self-hosted organizations can also import private packages from npm.

Use libraries in a workflow​

You can reference libraries using JavaScript Code blocks or as inline JavaScript in other blocks using {{ }}. You can also use require() to include libraries directly within JavaScript Code blocks.

For example, you could use marked to convert Markdown into HTML. This can be useful to generate reports and send them as HTML-formatted rich emails.

return marked.parse(query1.data.message);

Add a public npm package​

As with typical Node.js development, you provide a set of libraries to use in a package.json file. Retool makes this file available through the Workflow editor. To populate it, navigate to the Libraries tab, click +, then select Modify package.json.

package.json
{
    "dependencies": { 
        "lodash": "4.17.21", 
        "numbro": "2.1.0", 
        "papaparse": "5.3.2", 
        "moment-timezone": "0.5.23",
        "uuid": "3.4.0"
    }
}

Add a private npm registry​

Private npm registries are only supported for organizations using self-hosted Retool on versions 3.36+. You must also configure the code-executor service in order to use private npm registries.

Configuring a private npm registry requires setting some environment variables in the code executor service: NPM_REGISTRIES and NPM_REGISTRY_AUTH_LINES.

NPM_REGISTRIES is a comma-separated list of domains, and each entry uses either the @scope:url or url format.

# Support both npm and internal registries based on scope

NPM_REGISTRIES=@mycompany:https://npm.mycompany.com,@supplierco:https://npm.supplierco.com

# Only use internal registry

NPM_REGISTRIES=https://npm.mycompany.com

NPM_REGISTRY_AUTH_LINES is a comma-separated list of lines to append to a .npmrc file. This file is used to authenticate into the configured npm registries and is only required if your npm registry requires authentication. See the npm documentation for details on the format.

# Authentication for the Github Package repository

NPM_REGISTRY_AUTH_LINES=//npm.pkg.github.com/:_authToken=<GITHUBTOKEN>

Once the code executor is configured, you can install packages through the Modify package.json option in the Workflows editor.

package.json
{
    "dependencies": { 
        "@mycompany/internal-library": "1.0.0", 
    }
}

Configure block settings​

You can configure the following settings for Code blocks.

Timeout after (ms)

The duration to wait before the block times out. Default is 10000.

Retry count

The maximum number of attempts to retry the query if an error is returned.

Interval

The minimum length of time to wait between query retries. This is useful if a query is triggering a rate limit.

Exponential

Whether to increase the interval between retries, also known as exponential backoff. This is useful for handling rate limits.

Finally

Whether to stop the workflow and return an error if the block fails, or continue to allow an error handler to run.

Coefficient

When exponential backoff is enabled, the constant factor by which the time delay between retry attempts increases after each failure.

Max interval

When exponential backoff is enabled, the maximum time to delay between retries.