Browse Apps
Apps · Build

Write an App in Code

Define a BotDojo App's tables, roles, functions, connections, env vars, UI, and icons with @botdojo/app.

5 min read

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

  1. Create and approve requests.
  2. Change roles and validate data.
  3. Call a connection.
  4. Run a workflow and publish a skill.
  5. Add routes and page tools.
  6. 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:

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 of options), json, and reference (the ID of a row in the table named by references).
  • Fields can set label, required, default, and readOnly. Only function code writes a readOnly field, so a required one forces rows to be created through a function.
  • Every row has an id, a revision that increases with each change, its values, and archived_at. Archiving is a soft delete.
  • Each table gets table operations the UI can call: list_<table>, get_<singular>, create_<singular>, update_<singular>, and archive_<singular>. singular defaults to the table's name without its final s.

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: read covers list_ and get_, and patch covers update_.
  • 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 tables must 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.

typeRead by
buildThe build. Cannot be a secret.
backendFunctions, through ctx.env.
frontendThe 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.

Next steps