Preloaded JavaScript and Libraries
Learn how to preload custom JavaScript and libraries in apps.
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 ofindex.js
file, because that file can often includeimports
andrequires
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
orbrowser/<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.jsAn 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
ormodule 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.
Updated 18 days ago