React Builder Project Structure
This page is the reference for the files in a React Builder project: what each one holds, the rules ToolJet applies to them, and what ToolJet stores. To get a project onto a local computer, see Build Locally. To edit the same files in ToolJet, see Edit in the Browser.
A React Builder app is a React and TypeScript project. app.json names the app and its screens, and frontend/ holds the source. ToolJet keeps sign-in, permissions, environments, datasources and queries. A project is created by cloning an app or by creating one with the CLI.
Files and Folders​
orders-desk/
├── app.json App name, app ID, code page and screens
├── README.md Quick command reference
├── .gitignore
├── .tooljet/ Written by CLI commands, local to this folder
├── CLAUDE.md, AGENTS.md, Written by `tooljet skill install`
│ .cursor/rules/tooljet.mdc
└── frontend/
├── package.json
├── package-lock.json
├── .npmrc ignore-scripts=true
├── tsconfig.json
├── postcss.config.cjs
├── tailwind.config.cjs
├── .tooljet/config.json The app's component library
├── styles/
│ ├── theme.css Theme tokens, loaded first
│ └── global.css App-wide rules, loaded last
└── src/
├── index.ts Exports the App component
├── App/index.tsx The screens and the app shell
├── lib/router.tsx Router helpers
├── lib/utils.ts cn() for class names
├── styles/globals.css Tailwind layers and base styles
├── components/ui/ UI kit
└── tooljet.gen.ts Generated typed hooks: don't edit
frontend/src/index.tsmust export only React components. ToolJet builds the app from itsAppexport.- The project's
.gitignoreignoresnode_modules/,frontend/dist/,.tooljet/snapshot.jsonand.tooljet/instance.json. frontend/package.jsonhaslib:*scripts for custom component libraries. To build and run the app, use thetooljet appcommands instead.- ToolJet provides React 18 when the app runs.
reactandreact-domaren't bundled.
For the files the CLI writes in .tooljet/, see the CLI reference.
app.json​
app.json names the app, the ToolJet page that renders the project (the code page), and the app's screens (routes).
{
"name": "Orders Desk",
"appId": "55414690-beaa-4fa6-b41b-b8102bd7d1d8",
"codePage": { "handle": "home", "name": "Home" },
"routes": [
{ "id": "home", "path": "/", "title": "Orders" },
{ "id": "order", "path": "/orders/:id", "title": "Order" },
{ "id": "admin", "path": "/admin", "title": "Admin" }
]
}
Field | Required | Description |
|---|---|---|
name | Yes | The app name. Can't be empty. |
appId | No | The ToolJet app the project belongs to. clone and init --create set it. pull, dev, publish, checkout and source-pull need it. |
codePage | Yes | The code page: handle (lowercase letters, digits and hyphens, starting with a letter or digit) and name. |
routes | Yes | The app's screens. At least one. |
routes[].id | Yes | Starts with a lowercase letter. Lowercase letters, digits, _ and - only. Unique. |
routes[].path | Yes | Starts with /. Unique. Use :name for a parameter, for example /orders/:id. |
routes[].title | No | The screen's title. Shown in menus and in the screen's page name. |
version | No | { "id", "name" } of the version in use. Set it with tooljet app checkout. Local only: ToolJet never stores it. |
branch | No | A workspace Git branch to work on instead of the branch the folder's Git checkout is on. |
The CLI checks app.json every time it reads it, and stops with a message such as app.json: route id "Orders" must start with a letter and use lowercase letters, digits, _ and -. The rules:
nameis required.codePage.handlemust be lowercase letters, digits and hyphens.routesmust list at least one route.- Each route ID is listed once, and each path is used by one route.
- Each route path starts with
/. versionmust be an object withidandname.branchmust be a branch name.
Screens and Their Hidden Pages​
Each route in app.json gets a hidden page in the app, named <code page handle>-<route id>. For the example above, the admin screen's page is home-admin. The page's permissions decide who can open the screen. See Control Access.
tooljet app dev and tooljet app publish create these pages. pull doesn't change them.
Keep the <Route path> elements in the code the same as the paths in app.json. tooljet app check fails when they differ, because permissions are tied to the routes in app.json.
Limiting a screen hides the screen, not its code. Everyone who can open the app downloads every screen's code, constants and query names. Don't put secrets in a screen's code. To protect data, limit the queries the screen uses.
tooljet.gen.ts​
frontend/src/tooljet.gen.ts gives the code typed access to the app's queries, routes and pages. tooljet app pull and tooljet app dev write it from the app. Don't edit it: changes are overwritten on the next pull. GitSync commits it with the rest of the code, because the browser build can't generate it.
It exports:
Export | What It Is |
|---|---|
<Table>Row | One interface per ToolJet Database table that a query uses, with a field per column. For example, table orders gives OrdersRow. |
AppQueries | Each query's result type and the parameters it declares. |
useAppQuery(name) | Runs a query by name, typed. run() accepts only the parameters the query declares. |
ROUTES | Each route's path, by route ID. |
routePath(id, params) | A route's path with its parameters filled in. routePath('order', { id: 36 }) returns /orders/36. |
PAGES | The handles of the app's other visible ToolJet pages, for goToPage. |
Query results are typed as follows:
- ToolJet Database List rows and Join tables queries return
<Table>Row[]. - Other ToolJet Database operations return
<Table>Row[] | unknown. - Every other query (SQL, REST API and so on) returns
unknown. Narrow or cast the result in the code.
Column types map to number, boolean or string. JSON columns map to unknown. Nullable columns add | null.
For how to use these, see Runtime API.
Styling​
The project uses Tailwind CSS with theme tokens defined as CSS variables. The build loads CSS in this order:
frontend/styles/theme.css- The CSS the code imports
frontend/styles/global.css
Theme Tokens​
frontend/styles/theme.css defines the tokens the app uses. By default each token follows the theme picked in the app's settings, and updates live when the theme or dark mode changes:
--primary: var(--tj-brand, #4368e3);
ToolJet sets the --tj-* variables. The second value is a fallback.
Tokens | Used For |
|---|---|
--page, --background, --foreground | Page background, surfaces, text |
--card, --popover and their -foreground | Cards and popups |
--primary, --secondary, --muted, --accent and their -foreground | Brand color and neutral surfaces |
--destructive, --success, --warning and their -foreground | Status colors |
--border, --input, --ring | Borders and focus rings |
--chart-1 to --chart-5 | Chart series |
--radius, --font-sans | Corner radius and font |
To use brand colors instead of the app theme, replace the var(--tj-...) with a color:
--primary: #0f766e;
Any CSS color works. Dark mode fallbacks are under the .dark selectors in the same file.
Tailwind Classes​
The Tailwind config maps the tokens to color utilities: page, background, foreground, primary, secondary, muted, accent, destructive, success, warning, popover, card, border, input, ring and chart-1 to chart-5. For example, bg-primary, text-muted-foreground and bg-page. Opacity modifiers such as bg-primary/10 work. rounded-lg, rounded-md and rounded-sm follow --radius.
Use these classes instead of fixed colors such as bg-blue-600, so the app follows the theme and dark mode.
App-Wide Rules​
Put app-wide rules and overrides for a UI library in frontend/styles/global.css. It loads last, so its rules win over a library's defaults without !important. Tailwind's @apply works there.
.ant-btn-primary { border-radius: var(--radius); }
Reduced Motion​
frontend/src/styles/globals.css stops animations and transitions for users whose system asks for reduced motion (prefers-reduced-motion: reduce). Keep that rule.
UI Kit​
frontend/src/components/ui/ contains components built on Radix UI and Tailwind, in the style of shadcn/ui. They read the theme tokens.
File | Exports |
|---|---|
badge.tsx | Badge, badgeVariants |
button.tsx | Button, buttonVariants |
card.tsx | Card, CardHeader, CardTitle, CardDescription, CardContent, CardFooter |
chart.tsx | ChartContainer, ChartTooltip, ChartTooltipContent, ChartLegend, ChartLegendContent, ChartConfig |
input.tsx | Input, Textarea, Label |
select.tsx | Select, SelectGroup, SelectValue, SelectTrigger, SelectContent, SelectItem |
sheet.tsx | Sheet, SheetTrigger, SheetClose, SheetContent, SheetHeader, SheetFooter, SheetTitle, SheetDescription |
table.tsx | Table, TableHeader, TableBody, TableHead, TableRow, TableCell |
tabs.tsx | Tabs, TabsList, TabsTrigger, TabsContent, Switch, Tooltip, TooltipProvider, TooltipTrigger, TooltipContent, Separator |
These files can be edited, and new components can be added.
Charts​
Draw charts with Recharts inside ChartContainer from components/ui/chart:
import { Bar, BarChart, XAxis } from 'recharts';
import { ChartContainer, ChartTooltip, ChartTooltipContent, type ChartConfig } from '../components/ui/chart';
const config = {
total: { label: 'Orders' },
overdue: { label: 'Overdue', color: 'var(--destructive)' },
} satisfies ChartConfig;
<ChartContainer config={config}>
<BarChart data={rows}>
<XAxis dataKey="month" />
<ChartTooltip content={<ChartTooltipContent />} />
<Bar dataKey="total" />
<Bar dataKey="overdue" />
</BarChart>
</ChartContainer>
A series without a color gets the app's accent, then the theme's chart colors. Give a color that means something through a theme token, as overdue does above. The container animates series, except under reduced motion or past 300 points.
Other UI Libraries​
Another React UI library, such as Ant Design or MUI, can also be used. Connect it to the app theme with useToolJetTheme(), which returns ready-made theme objects for both. See Use the App Theme in Code.
Dependencies​
React Builder installs packages from the npm registry only.
- Every entry in
dependencies,devDependencies,optionalDependencies,peerDependencies,resolutionsandoverridesmust be a version, a range or a dist-tag. Anoverridesentry can also point at a dependency's own version with$<package>. - Git, URL,
file:andlink:dependencies are refused. So arenpm:aliases andworkspaces. - Every package in the lockfile must resolve from an allowed registry:
registry.npmjs.org,registry.yarnpkg.com, or a registry the ToolJet server allows. A self-hosted admin adds registries with the server'sTOOLJET_CODE_NPM_REGISTRIESenvironment variable (comma-separated). See Environment Variables. - Package install scripts never run.
tooljet app installturns them off, andfrontend/.npmrcsetsignore-scripts=true, so a plainnpm installbehaves the same. - To add a package, run
npm install --ignore-scripts <package>infrontend/. tooljet app publishneeds a lockfile, and installs exactly what it lists.
ToolJet refuses to store a project that breaks these rules, with a message such as frontend/package.json: ... React Builder installs packages from the npm registry only: no git, URL, file:, link:, alias or workspace dependencies.
ToolJet stores frontend/.npmrc with only ignore-scripts=true. It drops every other line, including registry tokens. Keep registry authentication in the user-level .npmrc.
To check packages before adding them, run tooljet app vet. It checks for malware and known vulnerabilities, versions published in the last 7 days, licenses and the blocklist. See tooljet app vet.
What ToolJet Stores​
When the CLI or the editor saves the app's code, ToolJet stores only the project's text source files:
app.jsonandREADME.mdfrontend/package.json,frontend/package-lock.json,frontend/tsconfig.json,frontend/.npmrcandfrontend/.tooljet/config.jsonfrontend/tailwind.config.*andfrontend/postcss.config.*(.js,.cjs,.mjsor.ts)- Files under
frontend/src/andfrontend/styles/with these extensions:ts,tsx,js,jsx,mjs,cjs,css,json,md,svg,txt
ToolJet doesn't store:
- Binary files, such as PNG images or fonts. Use SVG, or load them from an address the workspace allows. See Allow Outside Addresses.
- Dot files and folders inside
frontend/src/andfrontend/styles/, andnode_modules. - The
versionfield inapp.json. - Lockfiles other than
package-lock.json.
The source sync never follows a symlink that leads outside the project.
Limits​
Limit | Value |
|---|---|
| Size of one file | 512 KB |
| Size of the lockfile | 4 MB |
| Size of the whole project | 12 MB |
| Number of files | 1000 |
| Length of a file path | 512 characters |
Who Edits the Code​
A React Builder app's code has one owner at a time. Each upload from the CLI sets the owner.
Owner | What It Means |
|---|---|
| ToolJet | The default. The Code panel, the style inspector and ToolJet AI edit the code, and tooljet app dev --source platform stores each local save on ToolJet. |
| Repository | The code is edited in a Git repository and uploaded with tooljet app dev --source repository or tooljet app publish --source repository. In ToolJet, the code is read-only: the Code panel shows "This code lives in your Git repository", and the style inspector and Fix with AI are off. |
Uploading with --source platform hands editing to ToolJet. If ToolJet holds editor or AI changes that the upload would overwrite, the upload is refused until tooljet app source-pull is run, or pass --source-replace to replace them.
With GitSync, the owner also decides what a commit does to the app's code/ folder. See Move an App.