Editing apps with BubbleScript

Agents edit a Bubble app by changing its BubbleScript files, checking the result and applying the checked change to Bubble.

Start from the relevant app area

A task normally touches one or more folders in the cloned workspace.

• Use pages, reusable-elements or mobile-views for interface changes.

• Use the workflows folder inside a page or reusable element for frontend workflows.

• Use backend-workflows for server-side workflows.

• Use data-types for fields and privacy rules.

• Use option-sets for fixed app choices.

• Use api-connector for API Connector groups and calls.

An agent can search across these files to follow references before changing anything.

Edit an existing node

Existing nodes have stable identities that connect the BubbleScript source to Bubble.

For example, an existing button can have an ID and a separate display name:

button("save-task-button", {
  name: "Button save task",
  layout: {
    height: "fit",
    width: "fill",
  },
  properties: {
    text: staticText("Save task"),
  },
})

The agent can change the name, layout or properties while keeping save-task-button. Keeping the ID tells Buildprint to update the existing Bubble element instead of creating another one.

Create UI

UI elements are nested inside a page, reusable element or mobile view.

group("task-card", {
  name: "Group task card",
  layout: {
    container: "column",
    rowGap: "12px",
    width: "fill",
    height: "fit",
    padding: "24px",
  },
  children: [
    text("task-title", {
      name: "Text task title",
      properties: {
        text: staticText("Create the proposal"),
      },
    }),
    button("complete-task", {
      name: "Button complete task",
      properties: {
        text: staticText("Mark as complete"),
      },
    }),
  ],
})

The children array represents the element tree and its order in Bubble. Layout, appearance, typography, properties and conditions are grouped separately so their purpose is clear.

Add responsive behaviour

Conditions can change supported settings when a Bubble expression is true.

conditions: [
  condition({
    when: currentPageWidth().lessThanOrEqual(600),
    layout: {
      padding: "12px",
      width: "fill",
    },
  }),
]

This condition reduces the padding when the page width is 600 pixels or less. The available condition settings depend on the node being edited.

Edit workflows

Each workflow has its own file and contains one event followed by an ordered list of actions.

import {
  elementClicked,
  hideElement,
  showElement,
} from "@buildprint/bubblescript";

export default elementClicked("Button save task", {
  actions: [
    hideElement({ element: "Group task form" }),
    showElement({ element: "Text task saved" }),
  ],
});

Changing the order of the actions array changes the execution order in Bubble. Event and action inputs can use BubbleScript expressions.

Edit the data structure

Data types and option sets are edited as source declarations.

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

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

An agent can add fields, update names and types, and add privacy rules. Existing field IDs should remain in place when a field is changed.

Preserve unsupported settings

Some existing Bubble settings appear as rawBubble(...) or inside a raw property.

The agent should preserve this content unless the task requires changing it and the meaning is clear. Removing raw content can remove the corresponding Bubble setting.

Check and apply the edit

The agent checks the edited source before sending it to Bubble.

buildprint check pages/Dashboard/page.ts
buildprint check
buildprint apply

A targeted check gives fast feedback for one file. A full check validates the workspace and shows the planned Bubble changes. buildprint apply then compiles the checked BubbleScript into Bubble JSON and applies it to the selected branch.