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.

Preloaded libraries

Retool automatically imports the following utility libraries for use across Retool. These libraries are available for use in JavaScript queries and within {{ + + }} embedded expressions.

Name	Alias	Description
Lodash	_	A modern JavaScript utility library delivering modularity, performance & extras.
Moment.js	moment	Parse, validate, manipulate, and display dates and times.
UUID	uuid	Generate and validate RFC-compliant UUIDs.
Numbro	numbro	Convert, format, and manipulate numbers.
PapaParse	Papa	Parse CSV data, and convert between CSV and JSON.
i18next 1	i18n	Manage the translation of a web application.

Footnotes

1. Available in web apps only. Not available in workflows or mobile. ↩

Built-in libraries

Retool also provides a series of built-in libraries, which are third-party libraries that you can import.

To use a built-in JavaScript library:

1. Open the Libraries tab.
2. Click +, and click Add JavaScript Library.
3. The pop-up window shows the most commonly used libraries, or you can search for the library that you want to include.
4. Toggle the checkbox to make it available, and click Add selected libraries when you are done.

Add custom libraries

If the library that you want to use is not available as a preloaded or built-in library, you can import packages from npm.

Retool automatically tries to use NsJail to sandbox the creation of execution environments for custom libraries. NsJail requires privileged container access. While NsJail is not required to use custom libraries, it is strongly recommended.

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

Refer to the Code block reference for information about the block's settings.