Toolscript introduction

Learn how Retool uses Toolscript to serialize apps.

Available on:
• Enterprise plan

Toolscript is a JSX-style markup language built to serialize Retool apps protected using Source Control. Unlike its YAML predecessor, Toolscript is designed to be human reviewable.

Retool recommends you not modify Toolscript files directly and only make changes when resolving merge conflicts.

Toolscript is available on Retool Cloud and self-hosted Retool versions 3.6.0 and later. Organizations already using Source Control can migrate YAML files to Toolscript.

Syntax

Toolscript uses XML-like syntax to convey positioning and hierarchical information at-a-glance. It uses the rsx (Retool Scripting XML) file extension, or "Toolscript" for short.

Toolscript uses nesting to represent parent-child relationships. For example:

• Containers have nested Header, Footer, Body and View elements. Child components are nested inside these elements.
• Many components, including Select dropdowns and Button groups, have nested Options.
• Tables have nested Columns.

The ordering of components is based on their position on the canvas: top to bottom, then left to right. When component positions change—for example, a button is moved above another button—their order in the Toolscript file also changes.

File structure

Toolscript code is split into multiple files for easier comprehension:

• Large groups of components are split into their own files.
• Code blocks are split into own files (e.g., *.sql, *.js).
• Minor position and size changes are separated from more substantial logical changes.

Toolscript files

The apps directory contains the serialized app contents, split into the following files and directories. Some files and directories, such as lib, src, and functions.rsx, are not always present, depending on the app's structure.

app-name
└── .defaults.json
└── .positions.json
└── .mobilePositions.json
└── lib
  └── sqlQueryName.sql
  └── jsQueryName.js
└── src
  └── container1.rsx
└── functions.rsx
└── main.rsx
└── metadata.json

JSON dotfiles

Toolscript makes use of JSON dotfiles.

• .defaults.json contains default component values at time of serialization.
• .positions.json contains positioning information for components in the desktop layout.
• .mobilePositions.json contains positioning information for components in the mobile layout, if enabled.

Toolscript dotfiles are autogenerated and not designed to be human-readable.

Core files

• main.rsx is the main entry point to the app.
• functions.rsx stores functions and queries.
• metadata.json contains information about the app version and flags.

The lib/ directory

Files in lib are extracted from functions and queries. These files contain the contents of the query. The query component has an attribute of the format query={include("./lib/query1.sql", "string")}.

The src/ directory

Files in src are extracted from certain components. They are named after the ID of the extracted component, e.g., container1.rsx.

Edit Toolscript

Review these best practices before you directly edit Toolscript files.

Toolscript is a major improvement in readability from YAML, but it is not yet optimized for writing. While manually editing RSX files outside of Retool is possible, it is not currently recommended due to the lack of standard developer tooling, including linting, type-checking, and testing. However, editing library files locally in your IDE and committing the result to your Source Control repository can be a useful way to develop longer scripts and queries.

To provide feedback on your specific use cases for editing Toolscript, contact support.

Toolscript elements

The following are recommendations for how to edit specific Toolscript elements.

Plugin names

// "hello1" is a plugin name
<Text id="hello1" value="Hi there!" />

Plugin names can be safely edited. However, all references must be renamed as well. This includes the relevant entry in the .positions.json file, as well as any other plugins that reference the plugin to be renamed with a Retool expression (e.g., {{ hello1.value }} ).

Plugin content

// "Hi there!" is plugin content
<Text id="hello1" value="Hi there!" />

Plugin content is safe to edit, provided the attribute does not begin with an underscore. Edited content must be the same type as the original type, and it must be well formed. Only simple scalar expressions are allowed (e.g., {"hi" + "world"} is not supported).

Import statements

<Import src="./src/container1.rsx" />

Although it is safe to do so, import statements should not be manually edited because they are currently automatically generated by Retool. As such, any manual changes to imports will be lost the next time the app is exported or updated through Source Control.

Importing files from outside of the app root (e.g., ../other-directory/file) is not supported.

Library files

-- lib/query1.sql --
SELECT * from table;

You can change the content of library files arbitrarily. If you rename a library file, you must change all import references to it in RSX files as well.

Note that Retool expressions (e.g., {{ query1.value }}) are likely not parsed as valid code in library files. Retool expressions prevent the code from being directly executed outside of Retool as well.

File names

In general, file names correspond to the name of the root plugin or query contained in that file. To rename files, you should rename the corresponding element in the Retool UI to ensure that all dependencies are also renamed.

The name of the main.rsx, functions.rsx, and JSON metadata files are fixed and cannot be modified.

IDE settings

If you open Toolscript files in an IDE, you can change the language settings for RSX files to React or JSX to enable basic syntax highlighting and auto-formatting.

For example, in VS Code, to change the language setting for RSX, open any RSX file and select JavaScript (JSX) on the bottom toolbar.

Select language mode for JSX