Preload custom JavaScript for apps

Learn how to preload custom JavaScript and libraries in apps.

Retool enables you to make use of custom JavaScript and libraries in apps. You can configure this on a per-app basis or for all apps in your organization.

In general, Retool recommends you configure custom JavaScript and libraries only in apps in which it is required.

Custom JavaScript is sandboxed

For security reasons, all JavaScript runs in a sandbox. Retool executes all JavaScript in a separate <iframe> on a different domain to prevent cross-site scripting (XSS) attacks. You cannot use jQuery or similar libraries directly in apps.

Configure custom JavaScript

You can preload custom JavaScript to extend app functionality with custom logic. Once configured within an app, custom JavaScript is available only within that app. If you configure custom JavaScript across your organization, it is preloaded and available across all apps.

While you can call global JavaScript functions from anywhere in your app, local storage is the recommended way to store global variables in Retool.

Per-app

To add preloaded JavaScript to an app, open the App settings in the left panel, then select Preloaded JS.

Organization

All apps load custom JavaScript for the organization

Add custom JavaScript for the organization only if it is needed in most apps. Custom JavaScript can affect performance, especially if you load complex JavaScript functions that aren't used in every app.

Retool admins can configure custom JavaScript that loads in all apps within the organization. This is useful if there is custom JavaScript or libraries that must be available in all apps. Navigate to your organization's Settings at /settings and select the Advanced tab.

After you define your preloaded JavaScript, you can use your methods wherever you write JavaScript, such as:

• Within {{ }} embedded expressions, such as {{ window.myCustomHelper() }}.
• In JavaScript transformers and JavaScript queries.

Custom JavaScript functions use the window prefix.

Configure custom libraries

Preloaded libraries

Retool automatically imports some libraries, such as moment().

Retool supports the use of externally-hosted JavaScript libraries that function without any external dependencies. Retool recommends using libraries that follow UMD.

In addition, Retool recommends using:

• The minified version of a library. Minified versions are optimized to load quicker and generally end with .min.js.
• Only the libraries that you require. Every library you add to an app is loaded. The more libraries you include, the more it can impact performance.

CDNJS lists libraries you can load. Non-minified builds usually require @require or import statements. Some libraries are not compatible with Retool and you may need to use these in legacy custom components.

Per-app

To add libraries to an app, open the App settings in the left panel, then select Libraries.

Organization

To import external libraries, add URLs to Settings > Advanced > Libraries in your organization's settings, or the Libraries section of an app's settings. This allows you to access the library wherever you write JavaScript.

Custom libraries extend app functionality further with additional features and logic. For instance, you can use the blueimp-md5 library to generate an MD5 hash of an email address to retrieve a profile image from Gravatar.