Skip to main content

Toolscript

Learn how Retool uses Toolscript to serialize apps.

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. Support for YAML will be removed in the Q2 2025 stable release of Self-hosted Retool. Organizations still using YAML serialization of these elements in Source Control must migrate to Toolscript prior to upgrading.

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.

// "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 }} ).

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