BubbleScript

BubbleScript is a readable text representation of a Bubble app that lets AI agents understand and build it.

What BubbleScript is

BubbleScript uses a restricted form of TypeScript to describe Bubble concepts.

It is not normal application code and does not run as JavaScript.

For example, a Bubble data type can look like this:

import { dataType, dataTypeRef } from "@buildprint/bubblescript";

export default dataType("Task", {
  fields: [
    { display: "Title", type: "text" },
    { display: "Owner", type: dataTypeRef("User") },
  ],
});

The clear structure and type information make it easier for an agent to understand relationships and produce accurate changes.

Advantages

BubbleScript gives agents a smaller, clearer and safer representation of a Bubble app than raw Bubble JSON.

Uses fewer tokens

BubbleScript removes much of the repeated structure and low-level detail found in Bubble JSON.

This means an app or feature uses less of the agent’s context window. The agent can inspect more relevant parts of the app in one conversation and spend fewer tokens understanding the format.

Works faster

Smaller files take less time for an agent to read, search and update.

Token efficiency also reduces the amount of information sent to and processed by the model. This can make investigation and editing faster, especially in large Bubble apps.

Improves accuracy

BubbleScript provides typed constructors, properties, references and expressions.

The agent can see which values are valid for the current app, and buildprint check validates the result before it reaches Bubble. This catches invalid names, incorrect types, missing references and unsupported changes.

Produces better changes

BubbleScript is closer to the source code that coding agents are trained to understand.

Clear files, nested structures, imports and typed references help the agent follow relationships across an app. This makes it easier to make focused changes that fit the existing structure.

No dead ends

Any validation errors (diagnostics) flag the next steps rather than just throwing an error. For example, if an expression is invalid, it will say what type it expect. If a UI config option is value, it will provide the possible valid options / recommendations.

Design principles

BubbleScript is designed to be readable for agents while keeping changes accurate in Bubble.

Use friendly names where possible

BubbleScript normally references pages, elements, data types, fields and option values by their Bubble names.

dataTypeRef("Task")
element("Button save task")
option("Task Status", "Complete")

Names make the source easier to understand. When two items have the same name, BubbleScript can include a stable ID to identify the correct one.

Keep identity separate from display names

An existing node can keep the same identity when its Bubble name changes.

Stable IDs connect the source to the existing Bubble object. Agents preserve those IDs when editing or renaming a node, while new nodes can usually let Buildprint create an ID automatically.

Represent Bubble concepts directly

BubbleScript uses concepts that match the Bubble editor, such as pages, groups, repeating groups, workflows, actions, data types and privacy rules.

This is easier to understand than Bubble’s lower-level JSON and helps an agent reason about the app in Bubble terms.

It means when the agent speaks or interacts with the user, the user and the agent are speaking the same 'language'.

Prefer typed source

Constructors and expression methods describe which values are valid in each place and allow exact typing.

For example, a repeating-group data source must produce a list of its content type, and a workflow condition must produce yes/no. This lets Buildprint find mistakes before applying them.

Preserve what is not yet typed

BubbleScript keeps unsupported, corrupted, or legacy Bubble settings inside rawBubble(...) instead of discarding them.

Agents preserve unrelated raw settings when making a typed change. This allows newer Bubble features and unusual app settings to survive a clone and apply.

Organise source like the Bubble app

Files follow their Bubble ownership and behaviour.

UI trees live with their page or reusable element. Frontend workflows live under the UI root that owns them. Data types, option sets and backend workflows have their own areas.

Make small, reviewable changes

An agent should change only the source needed for the task while preserving existing IDs, raw settings and unrelated structure.

buildprint check shows the planned Bubble changes before buildprint apply writes them.

What BubbleScript represents

A BubbleScript workspace can describe the supported parts of a Bubble app.

• Pages, reusable elements, mobile views and global elements

• Elements, layout, styles and responsive conditions

• Page, element and backend workflows

• Data types, fields and privacy rules

• Option sets and values

• Global expressions and app texts

• API Connector groups and calls

Runtime database records are not part of BubbleScript. Agents use separate data commands to inspect or change records.

How a workspace is organised

Cloning a Bubble branch separates the app into folders that match familiar Bubble areas.

acme-app/
  Test/
    pages/
    reusable-elements/
    backend-workflows/
    data-types/
    option-sets/
    api-connector/
    mobile-views/

• pages contains pages, elements and page workflows.

• reusable-elements contains reusable elements.

• backend-workflows contains backend workflows.

• data-types contains data types, fields and privacy rules.

• option-sets contains option sets and values.

• api-connector contains API Connector groups and calls.

• mobile-views contains Bubble mobile views when the app uses them.

An agent can search and read these files with the same tools it uses for a codebase. This makes it possible to trace relationships across the app.

How BubbleScript becomes a Bubble change

The agent edits BubbleScript locally, then the Buildprint CLI checks and applies it.

Bubble editor
    ↓ clone or sync
BubbleScript files
    ↓ agent edits and checks
Bubble JSON
    ↓ apply
Bubble editor

buildprint check validates the source and shows the changes it will produce. It does not write anything to Bubble.

buildprint apply compiles the checked BubbleScript into Bubble JSON and sends it to the selected Bubble branch.

Unsupported and preserved settings

BubbleScript only exposes app areas that Buildprint can represent and change safely.

Some existing Bubble settings appear inside rawBubble(...). This preserves the original Bubble configuration when a typed BubbleScript form is not yet available.

BubbleScript and the Bubble editor

BubbleScript and the Bubble editor describe the same app branch in different formats.

Changes applied through the CLI appear in the Bubble editor. Changes made in the editor return to the workspace when the agent runs buildprint sync.

This lets people continue using Bubble normally while agents work through a source format designed for accurate inspection and editing.