Write an App in Code
Define a BotDojo App's tables, roles, functions, connections, env vars, UI, and icons with @botdojo/app.
A BotDojo App is one code project. botdojo.app.ts declares its tables,
roles, functions, connections, env vars, and UI entry.
Preview
Names and options on this page can change before general availability.
Start with a working App
Install the botdojo-app CLI and create an App from the Purchase
Requests starter. App code imports @botdojo/app, the UI imports
@botdojo/app/ui, and tests import @botdojo/app-cli/testing.
What to try next
- Create and approve requests.
- Change roles and validate data.
- Call a connection.
- Run a workflow and publish a skill.
- Add routes and page tools.
- Share with another person.
Project layout
botdojo.app.ts The App definition
botdojo.app.lock.json Stable IDs for tables, fields, roles, functions, and workflows (commit it)
functions/ One file per function
workflows/ Optional workflow scripts (defineWorkflow)
skills/ Optional skills, one folder each, published on deploy
ui/main.tsx The UI entry
assets/ Optional icons
seed.json Sample rows for local runs and empty non-production environments
fixtures/connections.json Local answers for connection calls
test/ Tests run by botdojo-app test
.env.example Example env var values (pushed)
.env.local Local values (never pushed)
.env.test Test values (pushed; no secrets)
Builds may import only @botdojo/app, react, and react-dom. Anything else
fails the build with UNSUPPORTED_DEPENDENCY.
Define the App
import { defineApp } from "@botdojo/app";
import { approveRequest } from "./functions/approveRequest";
export default defineApp({
name: "Purchase Requests",
description: "Requests and approvals for a team.",
tables: [
{
name: "requests",
fields: {
title: { type: "text", required: true },
amount: { type: "number", required: true },
status: {
type: "choice",
options: ["pending", "approved", "rejected"],
default: "pending",
readOnly: true,
},
},
},
],
roles: [
{
key: "requester",
label: "Requester",
isDefault: true,
permits: { tables: { requests: ["read", "create"] } },
},
{
key: "approver",
label: "Approver",
permits: {
operations: ["approve_request"],
tables: { requests: ["read", "patch"] },
},
},
],
functions: [approveRequest],
env: {
APPROVAL_LIMIT: { type: "backend", valueType: "botdojo/types/number", required: true },
BANNER_TEXT: { type: "frontend", valueType: "botdojo/types/string" },
},
ui: { entry: "ui/main.tsx" },
});
Only name, roles, and ui.entry are required. Not shown:
connections.workflowsandskills.ui.titleandui.icons.ui.routes,ui.chat, andui.displayModes.exports, which App connections do not use yet.
Tables
Each table has a name, optional label and singular, and fields.
- Field types:
text,number,boolean,date(YYYY-MM-DD),datetime(ISO 8601 with a time zone),choice(one ofoptions),json, andreference(the ID of a row in the table named byreferences). - Fields can set
label,required,default, andreadOnly. Only function code writes areadOnlyfield, so a required one forces rows to be created through a function. - Every row has an
id, arevisionthat increases with each change, itsvalues, andarchived_at. Archiving is a soft delete. - Each table gets table operations the UI can call:
list_<table>,get_<singular>,create_<singular>,update_<singular>, andarchive_<singular>.singulardefaults to the table's name without its finals.
Stable IDs and renames
botdojo.app.lock.json gives every table, field, role, function, and workflow
a stable ID, so a rename keeps its data. Rename with renamedFrom:
fields: {
summary: { type: "text", renamedFrom: "title" },
}
Commit the lock file. A repo build fails with LOCK_OUT_OF_DATE when the lock
lacks an ID; run botdojo-app build locally to update it.
Deploys refuse changes that would break existing rows: changing a field's type or reference target, or making a field required without a default. Add a new field and move the data in a function instead.
Roles
A role has a key, a label, an optional description, and permits:
functions under operations, and table actions (read, create, patch,
archive) under tables.
- A table permit also permits that table's operations:
readcoverslist_andget_, andpatchcoversupdate_. - Mark one role
isDefault: true. Anyone with access to the App holds it unless a group picks other roles. A single role needs no mark. - Project administrators hold every role.
- A function call needs a role that permits the function and its table
actions, and the function's own
tablesmust declare them.
Connections
Declare every connection the App calls by alias, with the only tools it may call:
connections: {
vendors: {
path: "vendors",
description: "The company's vendor registry, searched before an expense is approved.",
tools: ["search_vendors"],
},
},
path defaults to the alias. Tool names must match the connection's exactly.
Locally, fixtures/connections.json answers the calls. In BotDojo, see
Connections the App uses.
Env vars
Each env var has a type, a valueType, and optionally required and a
description.
type | Read by |
|---|---|
build | The build. Cannot be a secret. |
backend | Functions, through ctx.env. |
frontend | The UI, through app.context.env. Visible to anyone who opens the App. |
valueType is botdojo/types/ followed by string, number, boolean,
secret, or data (a JSON value). A deploy is blocked until every required
env var has a value.
Icons
Icons are optional square PNGs that BotDojo shows on its own pages:
ui: {
entry: "ui/main.tsx",
icons: [
{ src: "./assets/icon-256.png", size: 256 },
{ src: "./assets/icon-64.png", size: 64 },
],
},
Give up to six, each a different size from 16 to 1024 pixels and at most
256 KB. An icon's width and height must equal its size. 256 suits the
Workspace Apps grid, and 64 suits lists and headers.