ToolJet Cloud v3 Migration Guide
ToolJet Cloud will be upgraded to v3 on November 11th, 2024. This update includes breaking changes that may affect your applications. Please review and update your applications before November 11th to ensure they continue working after the upgrade.
You must make these changes before November 11th to prevent disruption to your applications. The upgrade will happen automatically and cannot be postponed.
Dynamic Input Restrictions
You can no longer dynamically change references to component names.
Action Required
- Review your applications for any dynamic component name references and refactor as necessary
- Replace all dynamic component references with static references
- Test all component interactions after making these changes
Examples and Details
The following patterns are no longer supported:
-
Using variables to construct component names:
// This will no longer work
{{components[variables.componentNameVariable].value}} -
Dynamically referencing components:
// This is not supported
{{components['textinput' + components.tabs1.currentTab].value}} -
Dynamically accessing nested properties:
// This dynamic property access is not allowed
{{components.table1[components.textinput1.value]}}
Instead, use static references to components:
{{components.textinput1.value}}
{{components.table1.selectedRow}}
{{queries.query1.data}}
Component and Query Naming
This is only an issue during the upgrade process. Once your application is running on ToolJet v3, you can use identical names for components and queries without any problems.
Action Required
- Review your applications for any instances where queries and components share the same name
- Temporarily rename either the component or the query to ensure unique names
- Document all renamed components/queries for potential post-upgrade reversion
- Test affected components and queries after renaming
Details and Examples
When upgrading, if a component is referencing a query with the same name, the upgrade process may break that mapping. This occurs because ToolJet previously used a global ID-to-name map for both components and queries, which is now split in v3.
Example scenario: If a table component named userData
is referencing a query also named userData
, this reference may break during the upgrade process.
Property Panel Logic
Action Required
- Review all property panel variable checks
- Update any existing variable existence checks to use the new recommended format
- Remove any instances of unsupported logic patterns
- Test all components using variable checks after updates
New Variable Access Rules
There are changes to how you can access and check for the existence of variables in the property panel:
- For components, queries, and page variables, a minimum of two keys must be available after the
component/query/page
keyword - For variables, a minimum of one key should be present after the
variables
keyword
// Supported formats
components.textinput1.value
components?.textinput1?.value
components["textinput1"].value
queries.restapi1.data
page.variables.name
variables["name"]
variables.name
// No longer supported
{{'name' in variables}}
{{Object.keys(variables).includes('name')}}
{{variables.hasOwnProperty('name')}}
// Recommended approach for checking existence
{{variables['name'] ?? false}}
These changes may affect how your application interacts with variables and components. Be sure to test thoroughly after making these updates.
Multi-Page Component Names
Action Required
- Review multi-page applications for components with identical names
- Either rename components to ensure uniqueness across pages
- Or modify queries to use query parameters instead of direct references
- Document all component name changes
- Test affected pages and their interactions after making changes
Current Limitations and Details
When the same component name exists on multiple pages and is linked to queries, the query will only work correctly on the page where the component was originally associated with it.
Example scenario:
- You have
page1
andpage2
, each containing a component namedtextinput1
- You create a query in
page1
that is linked totextinput1
- The query will only function properly on
page1
- When you switch to
page2
, the query will not work as expected, even though there's a component with the same name
When building multi-page applications, it's recommended to use unique component names across all pages to avoid any potential issues with query bindings.
Future resolution: We will be adding functionality to enforce unique component names across all pages in upcoming releases.