catalog/repos/afaraha8403--bubble-io-plugin-boilerplate.md

Bubble.io插件开发模板

Bubble.io 插件开发 ESLint AI编程 模板脚手架

集成ESLint与AI Agent技能的Bubble.io插件模板

本模板为开发Bubble.io插件提供了一个结构化的现代化起点，预置了ESLint用于可靠的代码检查与格式化。

最重要的是，本模板集成了AI编程代理技能（bubble-io-plugins），为你的AI开发代理内置了对Bubble特定编码规范、平台规则、API参考及样板模板的访问能力。

功能特性

• 标准项目结构： 整洁有序的目录结构，清晰地将本地代码映射到Bubble插件编辑器的各文本字段（元素、动作、客户端/服务端执行）。
• ESLint集成： 预配置现代扁平化配置（eslint.config.mjs），包含Bubble专属全局变量（instance、properties、context、$、jQuery）、HTML文件检查及代码风格约束（分号、单引号、严格相等）。
• VS Code就绪： 内置配置，使用官方ESLint扩展实现保存时自动格式化并修复错误。
• AI辅助开发与代理技能： 包含bubble-io-plugins技能，为AI工具提供Bubble平台架构的深度上下文。
• 入门模板： 提供运行时元素（initialize.js、update.js、preview.js、header.html）及客户端/服务端动作的快速启动样板文件。

快速开始

按以下步骤搭建开发环境。

前置条件

• Node.js与npm： 确保系统已安装Node.js和npm。
• Visual Studio Code： 本模板针对VS Code使用进行了优化。
• AI编程代理： 使用能够读取项目技能的AI编程助手（如Opencode、Cline、Cursor等）。

安装步骤

1. 下载或克隆： 将本模板复制到本地机器。
2. 安装VS Code扩展： 在VS Code中，进入扩展选项卡，安装官方ESLint扩展（dbaeumer.vscode-eslint）。
3. 安装依赖： 在VS Code终端中运行以下命令安装ESLint及所需包。

   npm install
   

   若需使用旧版对等依赖：

   npm install --legacy-peer-deps
   

4. 重启VS Code： 重新加载VS Code窗口，确保ESLint服务器启动并应用工作区配置。

AI辅助开发与代理技能

本模板的真正价值在于内置了bubble-io-plugins技能。

当你请求AI开发代理帮助构建或修改插件时，它会自动加载对应任务所需的具体规则、API参考或模板。

工作原理

该技能位于skills/bubble-io-plugins目录，包含：

• 平台规则（bubble-platform.md）： 元素生命周期、DOM操作、数据加载模式及Bubble硬性限制的说明。
• API参考（bubble-api.md）： 深入介绍Bubble专属类型（BubbleThing、BubbleList）和属性（instance、context）。
• 动作指南（actions-guide.md）： 服务端动作（SSA）与客户端动作的最佳实践，包含Plugin API v4的async/await规范。
• 模板（assets/templates/）： JavaScript和HTML文件的起始结构模板库。

每当你向代理发出提示时，它会智能地参考这些指南。例如，当你要求"创建一个新的可视化元素"时，代理会从对应的配置文件和bubble-platform.md参考中提取信息，确保代码正确使用instance.canvas而非document.body。

项目结构

    📁project-root
        ├── 📁actions              # 动作文件
        │   ├── 📁client           # 客户端工作流
        │   └── 📁server           # 服务端动作
        ├── 📁elements             # 可视化UI元素
        │   ├── 📁example-1
        │   └── 📁example-2
        ├── 📁skills               # AI代理技能
        │   └── 📁bubble-io-plugins
        ├── .vscode                # VS Code工作区配置
        │   └── settings.json
        ├── eslint.config.mjs      # ESLint配置
        ├── package.json           # 脚本与依赖
        └── README.md

ESLint配置

ESLint配置（eslint.config.mjs）针对Bubble插件开发进行了优化：

检查的文件类型

• **/*.js - 所有JavaScript文件
• **/*.html - HTML文件（用于元素头部）

Bubble专属全局变量

• instance、properties、context - 元素运行时对象
• $、jQuery - Bubble内置的jQuery

强制规则

• 风格：必须使用分号、单引号、严格相等（===）
• Bubble模式：忽略未使用的initialize、update、preview、action函数及context、instance、properties参数
• 安全：警告使用document.write
• 控制台：允许console.warn和console.error，警告console.log

可用脚本

• npm run lint - 检查代码规范问题
• npm run lint:fix - 自动修复规范问题

关于部署

无需构建步骤或发布包。在本模板中编写的代码可直接复制到Bubble插件编辑器对应的函数字段中。

许可证

本模板基于MIT许可证授权。