bubble-io-plugins

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Bubble.io Plugin Development — Project Rules

Bubble.io插件开发——项目规则

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.

这是一个Bubble.io插件开发模板，为在Bubble.io无代码平台中运行的插件提供目录结构、编码约定及工具支持。

插件通过将代码复制到Bubble插件编辑器进行部署——无需构建步骤，无需npm发布。

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

project-root/
  actions/
    client/                # 客户端工作流动作
      <action-name>/
        action-setup.md
        client.js
        params.json        # 可选：参数定义
    server/                # 服务端动作（运行在Bubble的Node.js服务器上）
      <action-name>/
        action-setup.md
        server.js
  elements/                # 可视化插件元素
    <element-name>/
      element-setup.md
      initialize.js        # 元素加载时运行一次
      update.js            # 在每次属性变更+数据加载时运行
      preview.js           # 在Bubble编辑器中渲染占位符
      header.html          # <head>内容：CDN链接、外部脚本
      actions/             # 元素专属工作流动作
        <action>.js
  eslint.config.mjs        # ESLint扁平配置
  package.json             # ESLint脚本及依赖
  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)

每个本地文件与Bubble插件编辑器中的文本字段一一对应：

本地文件	Bubble编辑器字段
`initialize.js`	函数：initialize
`update.js`	函数：update
`preview.js`	函数：preview
`header.html`	元素头部
`actions/<name>.js`	元素动作代码
`server/<name>/server.js`	服务端动作代码
`styles.css`	共享/元素头部（需包裹在 `<style>` 标签中）

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.

以下是影响最严重的规则，违反任何一条都会导致难以调试的问题：

切勿捕获
'not ready'
异常——Bubble将其用作数据加载的控制流。如果必须使用
```
try/catch
```
，当
```
err.message === 'not ready'
```
时需重新抛出异常。
在函数顶部加载所有数据——在任何DOM修改之前执行。当数据到达时，Bubble会从头重新运行整个函数。
切勿向
document.body
追加内容——所有可视化输出请使用
```
instance.canvas
```
。
切勿在客户端代码中存放API密钥——使用带有
```
context.keys
```
的服务端动作。
仅将函数体复制到Bubble插件编辑器——不要复制包裹代码。
为所有CSS类添加前缀（例如
```
myPlugin-root
```
）——避免与宿主应用发生冲突。
v4版本的SSA必须为
async
——在
```
.get()
```
、
```
.length()
```
和
```
fetch()
```
上使用
```
await
```
。
头部仅支持
<script>
、
<meta>
、
<link>
标签——其他标签会被自动移至
```
<body>
```
。
请勿在插件函数内使用
$(document).ready()
——这会破坏Bubble的依赖检测机制。

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.

请勿预加载所有文件。请先确定任务类型，再仅加载相关的参考文档：

确定任务类型：
- 编写/评审元素运行时代码（
```
initialize.js
```
  、
```
update.js
```
  、
```
preview.js
```
  、
```
header.html
```
  ）？→ 加载bubble-platform.md
- 需要
  instance
  /
  properties
  /
  context
  API详情，或v4版本迁移指导？ → 加载bubble-api.md
- 处理动作相关工作（客户端或服务端动作）？→ 加载actions-guide.md
- 编写、评审或重构JavaScript代码？ → 加载code-standards.md
- 编写文档、配置文件或用户可见文本？ → 加载documentation.md
- 涉及多个场景？ → 先加载最相关的文件，仅在需要时添加其他文件。

文件	加载场景
bubble-platform.md	元素生命周期、DOM/canvas、数据加载、头部、预览、事件、调试、平台限制。
bubble-api.md	`instance` 、 `properties` 、 `context` API参考。BubbleThing/BubbleList类型。自定义数据类型/API连接器应用类型。Plugin API v4版本迁移。
actions-guide.md	客户端与服务端动作对比。场景选择。SSA Node模块、返回值、选项集。
code-standards.md	ESLint配置、语法规则、安全、性能、错误处理。
documentation.md	JSDoc、配置文件、市场描述、字段提示文本、变更日志、发布流程。

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)

当搭建新元素或动作时，请从

assets/templates/

复制相关模板：

模板	适用场景
`initialize.js`	新元素——容器配置、 `instance.data` 、事件命名空间
`update.js`	新元素——数据优先模式、变更检测、命名空间监听器
`preview.js`	新元素——编辑器占位符（支持响应式尺寸）
`header.html`	新元素——幂等 `<script>` 加载
`client-action.js`	新客户端动作
`server-action.js`	新服务端动作（v4异步/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.

状态说明。当建议修改时，请解释原因——不要仅陈述规则。
保留现有模式。在引入新模式前，请检查代码库中是否已存在针对同一场景的约定。
避免冗余文件。除非任务需要，否则不要创建新文件。优先编辑现有文件。
通过ESLint强制代码检查。配置文件位于
```
eslint.config.mjs
```
（扁平配置格式）。VS Code通过
```
.vscode/settings.json
```
中的
```
source.fixAll.eslint
```
实现保存时自动修复。请勿引入第二种格式化工具。