Bubble.io Plugin Development — Project Rules

Project identity

This is a Bubble.io plugin development boilerplate. It provides the folder structure, coding conventions, and tooling for building plugins that run inside the Bubble.io no-code platform.

Plugins are deployed by copying code into the Bubble Plugin Editor — no build step, no npm publish.

Project structure

project-root/
  actions/
    client/                # Client-side workflow actions
      <action-name>/
        action-setup.md
        client.js
        params.json        # Optional: parameter definitions
    server/                # Server-side actions (runs on Bubble's Node.js server)
      <action-name>/
        action-setup.md
        server.js
  elements/                # Visual plugin elements
    <element-name>/
      element-setup.md
      initialize.js        # Runs once on element load
      update.js            # Runs on every property change + data load
      preview.js           # Renders placeholder in Bubble Editor
      header.html          # <head> content: CDN links, external scripts
      actions/             # Element-specific workflow actions
        <action>.js
  eslint.config.mjs        # ESLint flat config
  package.json             # ESLint scripts and dependencies
  README.md

Key architectural fact

Each local file maps 1:1 to a text field in the Bubble Plugin Editor:

Local file	Bubble Editor field
`initialize.js`	Function: initialize
`update.js`	Function: update
`preview.js`	Function: preview
`header.html`	Element Header
`actions/<name>.js`	Element Action code
`server/<name>/server.js`	Server-Side Action code
`styles.css`	Shared/Element Header (wrap in `<style>` tags)

Code quality expectations

When generating or editing any code in this project, follow these rules unconditionally.

Well-formatted, readable code

All code must be clean, consistently formatted, and easy to scan. This means:

Logical sections separated by blank lines — group related statements together (data loading, guards, rendering, event binding).
Descriptive variable names — avoid single-letter or cryptic abbreviations (container not c, itemCount not ic).
Consistent indentation — 2-space indent for all JS; match surrounding code if editing an existing file.
Section banners for update.js — use comment blocks (// === SECTION ===) to delimit lifecycle phases (data loading → guard → change detection → cleanup → render).
One concern per function — extract helpers for any logic longer than ~10 lines; define helpers inside the wrapper function to avoid global leaks.

Inline documentation

Every non-trivial block of code must include an inline comment explaining why it exists, not just what it does. Specifically:

Data loading — explain what each properties.* field contains and why it is loaded first.
Guards / early returns — explain the condition being checked and what would happen without the guard.
DOM mutations — explain the structure being built and any Bubble-specific constraints (e.g., why we use instance.canvas instead of document.body).
Event listeners — explain the namespace convention and why previous listeners are removed.
Workarounds — any Bubble quirk or browser compat hack must have a comment linking to the reason.

JSDoc comments

All functions (wrappers and helpers) must have JSDoc blocks. Follow the rules in documentation.md Section 1. Summary:

Wrapper functions (initialize, update, preview, actions) — include a top-level @description summarising the function's purpose, followed by @param tags for each argument (instance, properties, context).
Helper functions — @param, @returns, and a one-line description.
Placement — JSDoc goes inside the wrapper, not above it (the wrapper line is stripped when pasting into Bubble).

Example (initialize wrapper):

let initialize = function(instance, context) {
  /**
   * @description One-time setup for the PLUGIN_PREFIX element.
   * Creates the root DOM container, generates a unique event namespace,
   * and initialises default exposed states.
   *
   * @param {object} instance - Bubble element instance (canvas, data, publishState, etc.)
   * @param {object} context  - Bubble context (keys, currentUser, etc.)
   */

  // ... implementation ...
};

Debug logging (`verbose_logging`)

When scaffolding a new element or action from scratch, ask the user once:

"Should this component include a verbose_logging toggle? This adds a boolean field in the Bubble Plugin Editor that gates all console.log output at runtime."

Do not ask on edits, reviews, refactors, or bug fixes — only on new scaffolds.

If the user accepts:

Add a boolean field called verbose_logging to the element or action configuration in the Bubble Plugin Editor and document it in the relevant setup file.
Gate all console.log calls behind properties.verbose_logging:

if (properties.verbose_logging) {
  console.log('[PLUGIN_PREFIX] update called', { properties });
}

Log placement — add gated log statements at:
- Entry point of update.js, client actions, and server actions
- After data loading completes
- Before and after external API calls (server actions)
console.error() in catch blocks is always unconditional — never gate error logging behind the verbose flag.
initialize.js does not receive properties — verbose logging is unavailable. Use a plain console.log only for temporary init-time debugging; remove before production.
preview.js and header.html run in the editor only — verbose logging does not apply.

If the user declines, omit all console.log statements. console.error() in catch blocks remains unconditionally.

Critical pitfalls — always keep in mind

These are the highest-consequence rules. Violating any of these causes hard-to-debug failures:

Never catch the 'not ready' exception — Bubble uses it as control flow for data loading. If you must use try/catch, re-throw when err.message === 'not ready'.
Load all data at the TOP of the function — before any DOM mutations. Bubble re-runs the entire function from the start when data arrives.
Never append to document.body — use instance.canvas for all visual output.
Never put API keys in client-side code — use server-side actions with context.keys.
Copy only the function BODY to the Bubble Plugin Editor — not the wrapper.
Prefix all CSS classes (e.g., myPlugin-root) — avoid collisions with the host app.
SSA in v4 must be async — use await on .get(), .length(), and fetch().
Headers only support <script>, <meta>, <link> — anything else gets auto-moved to <body>.
Do NOT use $(document).ready() inside plugin functions — it breaks Bubble's dependency detection.

Which reference to load

Do not preload all files. Determine the task type, then load only the relevant reference:

Determine the task:
- Writing/reviewing element runtime code (initialize.js, update.js, preview.js, header.html)? → Load bubble-platform.md
- Need instance/properties/context API details, or v4 migration? → Load bubble-api.md
- Working on actions (client-side or server-side)? → Load actions-guide.md
- Writing, reviewing, or refactoring any JavaScript? → Load code-standards.md
- Writing docs, setup files, or user-facing text? → Load documentation.md
- Multiple concerns? → Load the most relevant file first, add others only if needed.

File	Load when...
bubble-platform.md	Element lifecycle, DOM/canvas, data loading, headers, preview, events, debugging, hard limits.
bubble-api.md	`instance`, `properties`, `context` API reference. BubbleThing/BubbleList types. Custom data types / API Connector App Types. Plugin API v4 migration.
actions-guide.md	Client vs server actions. When to use which. SSA Node modules, return values, option sets.
code-standards.md	ESLint config, syntax rules, security, performance, error handling.
documentation.md	JSDoc, setup files, marketplace descriptions, field tooltips, changelog, publishing.

Starter templates

When scaffolding a new element or action, copy the relevant template from assets/templates/:

Template	Use for
`initialize.js`	New element — container setup, `instance.data`, event namespace
`update.js`	New element — data-first pattern, change detection, namespaced listeners
`preview.js`	New element — editor placeholder with responsive sizing
`header.html`	New element — idempotent `<script>` loading
`client-action.js`	New client-side action
`server-action.js`	New server-side action (v4 async/await)

General expectations

State reasoning. When recommending a change, explain why — do not just state the rule.
Preserve existing patterns. Before introducing a new pattern, check if the codebase already uses a convention for the same concern.
No unnecessary files. Do not create files unless the task requires it. Prefer editing existing files.
Linting is enforced via ESLint. Configuration lives in eslint.config.mjs (flat config format). VS Code auto-fixes on save via .vscode/settings.json (source.fixAll.eslint). Do not introduce a second formatter.

bubble-io-plugins