Skip to main content

Preload custom JavaScript in apps

Learn how to preload custom JavaScript and libraries in apps.

Application-level vs. organization-level JavaScript​

Retool recommends using application-wide JavaScript instead of organization-wide JavaScript where possible. Organization-wide JavaScript loads when you open any application in your organization. This can affect performance, especially if you load complex JavaScript functions that aren't used in every app.

Application-wide JavaScript loads only in the application in which it is defined. Though you can call global JavaScript functions from anywhere in your app, local storage is the recommended way to store global variables in Retool.

caution

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. This means that inside your preloaded JavaScript, you can't use jQuery or other hosted libraries.

Application-wide preloaded JavaScript​

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

Organization-wide preloaded JavaScript​

You can also add custom preloaded JavaScript to all applications in an organization. To do so, click on your profile picture dropdown in the upper right, then go to Settings and navigate to the Advanced tab. Only admin users can add preloaded JavaScript at the organization level.

Use preloaded JavaScript in apps​

After you define your preloaded JavaScript, you can use your methods wherever you write JavaScript: inside curly braces {{ window.myCustomHelper() }}, JavaScript transformers, and JavaScript queries. You call functions in your apps using the window prefix.

Using preloaded code in a JavaScript query.

Custom JavaScript libraries​

Similar to preloaded JavaScript, Retool recommends you use application-specific libraries to reduce the potential performance impact of loading unnecessary libraries. Retool automatically imports some libraries.

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.

CDNJS lists libraries you can load. Retool recommends you load the minified, UMD build, usually named with the format <library>.min.js. 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.

Application-wide libraries​

To add libraries at the application level, open the App settings in the left panel, then select Libraries.

Organization-wide libraries​

Admin users can also add custom preloaded JavaScript libraries to all applications in an organization. To do so, click on your profile picture dropdown in the upper right, then go to Settings and navigate to the Advanced tab.