Skip to main content

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.

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

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

Custom JavaScript functions use the window prefix.

Using preloaded code in a JavaScript query.

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 custom components.

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

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.