105 lines
5.0 KiB
Markdown
105 lines
5.0 KiB
Markdown
|
# 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及所需包。
|
|||
|
|
```bash
|
|||
|
|
npm install
|
|||
|
|
```
|
|||
|
|
若需使用旧版对等依赖：
|
|||
|
|
```bash
|
|||
|
|
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`。
|
|||
|
|
|
|||
|
|
## 项目结构
|
|||
|
|
|
|||
|
|
```text
|
|||
|
|
📁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许可证授权。
|