Skip to main content

Build Locally

A React Builder application can be developed on a local computer, in a code editor or with a coding agent. This guide sets up a local copy of the application's React project. Each local save is then shown on the canvas in ToolJet.

The Open locally view in the Code panel, with buttons to open the app in VS Code, Cursor or Windsurf and the terminal steps below them

How It Works​

Only the application's code is copied to the local computer. Queries, datasources, permissions and environments remain in ToolJet.

1
Clone
The ToolJet CLI copies the app's React project into a folder and links it to the app.
2
Edit
When a file is saved in the editor, the CLI rebuilds the application and the canvas in ToolJet shows the result.
3
Publish
One command checks the code, builds it and saves the draft as a version.

Prerequisites​

  • Node.js 18 or later, with npm.
  • Edit access to the app in ToolJet.
  • Permission to create personal access tokens in the workspace. The CLI signs in with one.

Set Up​

The editor shows the commands with the instance's address and the app's ID filled in.

  1. Open the app in the editor and click Code in the header.
  2. In the Code panel, click Open locally.
  3. Expand Use the terminal instead, then copy each command and run it in a terminal.

With the ToolJet extension installed in the editor, Open in VS Code, Open in Cursor or Open in Windsurf clones the app, signs in and starts the live preview.

At sign-in, the CLI prints a code and opens the Sign in the ToolJet CLI page in the browser. Type the code, click Continue, then click Approve. The CLI finishes signing in by itself.

The Sign in the ToolJet CLI page asking to approve the ToolJet CLI for the Northwind Logistics workspace, with Approve and Cancel

Go back to the app in the ToolJet editor: the canvas now shows the build from the local computer. Leave tooljet app dev running, and it rebuilds on every save in frontend/src. If a save has TypeScript errors, nothing is uploaded and the canvas keeps the last good build.

Common Commands​

Run these in the project folder.

Command
When to Run It
tooljet app devDuring development. It rebuilds on every save and shows the app live in the editor.
tooljet app pullAfter a query changes in ToolJet. It rewrites the typed hooks in frontend/src/tooljet.gen.ts.
tooljet app checkBefore publishing. It fails when the code names a query, screen or link the app doesn't have, and runs the security scan.
tooljet app publishWhen the work is ready. It saves the draft as a version, the same as clicking Save version in the editor.

Queries are created and edited in ToolJet's query editor, not in code. publish doesn't release the version: releases are made in ToolJet. See Versions and History.

Install packages with tooljet app install, not npm install: it never runs a package's install scripts. Every flag is in the CLI reference.

Build With a Coding Agent​

A coding agent can edit the application in the same project folder. First give it ToolJet's rules for React Builder apps:

tooljet skill install

The command writes one instruction file per agent, and each agent reads its own file without any setup.

Agent
File It Reads
Claude CodeCLAUDE.md
Codex and WindsurfAGENTS.md
Cursor.cursor/rules/tooljet.mdc

Start the agent in the project folder, then describe the change, for example:

Add a Carriers screen that lists the rows from the listCarriers query,
sorted by on-time rate. Link it from the sidebar.

The instructions tell the agent to read data only through ToolJet queries, to build with tooljet app dev --once, and to finish with tooljet app check passing. Keep tooljet app dev running while the agent works, and its changes show on the canvas as it saves them.

The agent writes the screens. To let it also create tables and queries in the app, connect it to the ToolJet MCP server: the A coding agent tab in Open locally lists the setup commands.

Syncing Changes​

Teammates and ToolJet AI can change the app during local development. For an app created in ToolJet, each local build also saves the code to the app's draft, so the Code panel and the AI work on the latest local code. For the other cases, see Who Sees Local Saves.

While it runs, tooljet app dev also checks ToolJet for newer code every few seconds:

  • If no local files changed since the last sync, it pulls the newer code and rebuilds.
  • If there are local changes, it keeps them and stops uploading until the newer code is pulled in.
tooljet app source-pull

source-pull refuses to overwrite locally changed files, and lists them. To take ToolJet's code anyway, add --force: the CLI keeps a copy of the changed files in .tooljet/before-pull/.

Other Sign-In Methods, Git Branches and Common Problems

Other Ways to Sign In​

The CLI can also sign in with a pasted personal access token through tooljet login, stay signed in to several instances at once, or sign in from CI without a browser. See Sign In in the CLI reference.

Git Branches​

If the workspace uses GitSync, ToolJet commits the app's code to a code/ folder inside the app's folder in the repository. Open that folder and run tooljet app dev there.

The Git branch of the folder decides which draft is used. After git checkout feature-x, tooljet app dev works on the feature-x branch's draft, and the CLI prints the branch it uses. tooljet app checkout <version> overrides the branch. If the branch has no draft of the app yet, open the app on that branch in ToolJet first.

Common Problems​

Message
What to Do
No app.json here or aboveRun the command inside the project folder.
The ToolJet token was rejected by <instance>The sign-in expired or was revoked. Run tooljet auth login again.
<n> TypeScript error(s); not uploadedFix the errors listed. The canvas keeps the last good build.
ToolJet has newer code (revision <n>...)Run tooljet app source-pull, then save again.
Version <name> is <status>, which cannot change.dev and publish need a draft. Pick one with tooljet app checkout, or create one in ToolJet.

For every message, see Common Errors in the CLI reference.

Where to Go Next​