Preloaded JavaScript

Retool supports preloading custom JavaScript code. You can add custom JavaScript code at both the application and organization level.

App-level vs. Organization-level JavaScript

We recommend using application-level JavaScript over organization-level JavaScript where possible. Organization-level JavaScript will be loaded when you open any application in your organization. This can affect performance, especially if you are loading complex JavaScript functions that aren't being used in every app.

Application-specific JavaScript gets loaded only in the application in which it is defined and it's easier to write, edit, and reuse within an application. When in doubt, we suggest using app-specific JavaScript!

Application-specific Preloaded JavaScript

To add preloaded JavaScript at the application level, click on the More Settings menu (three dots) next to the Share button in the editor navigation bar, then press on Scripts and styles. Once the modal comes up, press on the JavaScript tab.

You can now define the functions you want by assigning them to the window scope:

Organization-specific 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 the Organization Settings page and navigate to the Advanced tab. Only admin users can add preloaded JavaScript at the organization level.

Using Preloaded JavaScript in Apps

Once you define your preloaded JavaScript you'll be able to use your custom helpers inside {{ }} snippets, in Transformers and JavaScript. Here's some quick examples!

🚧

For security reasons, all JavaScript runs in a sandbox.

If JavaScript ran directly on your page, other people in your org could XSS you. To prevent that, we execute all JavaScript in a separate iframe, on a different domain.

That means that inside of your preloaded JavaScript, you won't be able to use jQuery, or other hosted libraries to create your own components, listen to events on the Retool page, etc.

Custom JavaScript Libraries + NPM modules

📘

Application-specific vs. organization-specific libraries

Like with preloaded JavaScript, we recommend using application-specific libraries to reduce the potential impact of loading unnecessary libraries on your application's performance.

You can also pull in libraries from external URLs. For example, you could add papaparse by adding the URL https://cdnjs.cloudflare.com/ajax/libs/PapaParse/4.6.0/papaparse.min.js to the Libraries section. Then, you'll have papaparse available inside all your JavaScript queries, {{ }}, etc.

Many libraries can be loaded this way. A list can be found at CDNJS.

🚧

You want to make sure you are loading the minified, UMD build from CDN instead of index.js file, because that file can often include imports and requires calls that require preprocessing before being made usable in the browser.

For builds that will properly load the library in the browser inside window, they are usually named umd/<library>.min.js or browser/<library>.min.js , or lives inside the root folder as <library>.min.js.

An example of this is React:

❌ You don't want to use this file, as it contains require calls:
https://www.unpkg.com/browse/[email protected]/index.js

✅ You do want to use this file
https://www.unpkg.com/browse/[email protected]/umd/react.production.min.js

An example for a library that won't work in the browser due to not having a browser build:

https://unpkg.com/browse/[email protected]/

A sign of linking the wrong file is if you get require is not a function or module is undefined in the console when you start up your application.

Application-specific Libraries

To add libraries at the application level, click on the ••• menu in the top right and select Scripts and styles.

On the Libraries tab, click Add new to enter a link to the library and add it.

Organization-specific Libraries

You 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 the Organization Settings page and navigate to the Advanced tab. Only admin users can add preloaded libraries at the organization level.

🚧

Libraries also run in a sandbox

Like all other JavaScript inside of Retool, any library functions are run inside of a separate iframe. This means that if your library is dependent on external services or requests it will likely not work for those functions. Any communication that needs to happen through the sandbox must be routed through an official integration like a REST API.