# 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许可证授权。