🎨 デザインコミュニティ

bubble-io-plugins

Bubble.ioのプラグイン開発におけるルール、API、コーディング標準全般を網羅し、開発、レビュー、デバッグ、公開などあらゆる作業を支援、セキュリティ監査やパフォーマンス改善にも役立つSkill。

📜 元の英語説明(参考)

Bubble.io plugin development rules, API reference, and coding standards. Use when working on any task in this repo: writing, reviewing, refactoring, or creating initialize.js, update.js, preview.js, header.html, element actions, client-side actions, server-side actions (SSA), Plugin API v4 async/await code, JSDoc, setup files, README, CHANGELOG, marketplace descriptions, or field tooltips. Also use for security audits, code review, debugging, and publishing plugins. Covers instance/properties/context objects, BubbleThing/BubbleList interfaces, data loading suspension, DOM/canvas rules, element vs shared headers, exposed states, event handling, ESLint standards, and Bubble hard limits.

🇯🇵 日本人クリエイター向け解説

一言でいうと

※ jpskill.com 編集部が日本のビジネス現場向けに補足した解説です。Skill本体の挙動とは独立した参考情報です。

⚡ おすすめ: コマンド1行でインストール(60秒)

下記のコマンドをコピーしてターミナル(Mac/Linux)または PowerShell(Windows)に貼り付けてください。ダウンロード → 解凍 → 配置まで全自動。

🍎 Mac / 🐧 Linux

mkdir -p ~/.claude/skills && cd ~/.claude/skills && curl -L -o bubble-io-plugins.zip https://jpskill.com/download/9800.zip && unzip -o bubble-io-plugins.zip && rm bubble-io-plugins.zip

🪟 Windows (PowerShell)

$d = "$env:USERPROFILE\.claude\skills"; ni -Force -ItemType Directory $d | Out-Null; iwr https://jpskill.com/download/9800.zip -OutFile "$d\bubble-io-plugins.zip"; Expand-Archive "$d\bubble-io-plugins.zip" -DestinationPath $d -Force; ri "$d\bubble-io-plugins.zip"

完了後、Claude Code を再起動 → 普通に「動画プロンプト作って」のように話しかけるだけで自動発動します。

💾 手動でダウンロードしたい(コマンドが難しい人向け)

1. 下の青いボタンを押して bubble-io-plugins.zip をダウンロード
2. ZIPファイルをダブルクリックで解凍 → bubble-io-plugins フォルダができる
3. そのフォルダを C:\Users\あなたの名前\.claude\skills\(Win)または ~/.claude/skills/(Mac)へ移動
4. Claude Code を再起動

⬇ .zip でダウンロード(推奨) ⬇ .skill 形式(上級者用) 元のソース ↗

⚠️ ダウンロード・利用は自己責任でお願いします。当サイトは内容・動作・安全性について責任を負いません。

🎯 このSkillでできること

下記の説明文を読むと、このSkillがあなたに何をしてくれるかが分かります。Claudeにこの分野の依頼をすると、自動で発動します。

📦 インストール方法 (3ステップ)

1. 上の「ダウンロード」ボタンを押して .skill ファイルを取得
2. ファイル名の拡張子を .skill から .zip に変えて展開(macは自動展開可)
3. 展開してできたフォルダを、ホームフォルダの .claude/skills/ に置く
- · macOS / Linux: ~/.claude/skills/
- · Windows: %USERPROFILE%\.claude\skills\

Claude Code を再起動すれば完了。「このSkillを使って…」と話しかけなくても、関連する依頼で自動的に呼び出されます。

詳しい使い方ガイドを見る →

最終更新: 2026-05-18
取得日時: 2026-05-18
同梱ファイル: 1

📖 Skill本文(日本語訳)

※ 原文(英語/中国語)を Gemini で日本語化したものです。Claude 自身は原文を読みます。誤訳がある場合は原文をご確認ください。

Bubble.io プラグイン開発 — プロジェクト規則

プロジェクトのアイデンティティ

これは Bubble.io プラグイン開発のボイラープレートです。Bubble.io ノーコードプラットフォーム内で実行されるプラグインを構築するためのフォルダ構造、コーディング規約、およびツールを提供します。

プラグインは、コードを Bubble プラグインエディタにコピーすることでデプロイされます。ビルドステップや npm publish はありません。

プロジェクト構造

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

主要なアーキテクチャ的事実

ローカルファイルはそれぞれ、Bubble プラグインエディタのテキストフィールドに 1:1 で対応します。

ローカルファイル	Bubble エディタのフィールド
`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 (`<style>` タグで囲む)

コード品質の期待

このプロジェクトでコードを生成または編集する場合は、以下の規則に無条件に従ってください。

整形され、読みやすいコード

すべてのコードは、クリーンで、一貫して整形され、スキャンしやすいものでなければなりません。これは次のことを意味します。

空白行で区切られた論理的なセクション — 関連するステートメントをグループ化します (データロード、ガード、レンダリング、イベントバインディング)。
記述的な変数名 — 一文字または暗号のような省略形は避けてください (container で c ではなく、itemCount で ic ではない)。
一貫したインデント — すべての JS で 2 スペースのインデント。既存のファイルを編集する場合は、周囲のコードに合わせてください。
update.js のセクションバナー — コメントブロック (// === SECTION ===) を使用して、ライフサイクルフェーズを区切ります (データロード → ガード → 変更検出 → クリーンアップ → レンダリング)。
関数ごとに 1 つの関心事 — ~10 行を超えるロジックについてはヘルパーを抽出します。グローバルリークを避けるために、ヘルパーをラッパー関数内で定義します。

インラインドキュメント

すべての非自明なコードブロックには、それが何をするかだけでなく、なぜそれが存在するのかを説明するインラインコメントを含める必要があります。具体的には：

データロード — 各 properties.* フィールドに何が含まれており、なぜ最初にロードされるのかを説明します。
ガード / アーリーリターン — チェックされている条件と、ガードがない場合に何が起こるかを説明します。
DOM の変更 — 構築されている構造と、Bubble 固有の制約 (たとえば、なぜ document.body の代わりに instance.canvas を使用するのか) を説明します。
イベントリスナー — 名前空間の規則と、以前のリスナーが削除される理由を説明します。
回避策 — Bubble の癖またはブラウザの互換性ハックには、理由へのリンクを含むコメントが必要です。

JSDoc コメント

すべての関数 (ラッパーとヘルパー) には JSDoc ブロックが必要です。documentation.md のセクション 1 の規則に従ってください。概要:

ラッパー関数 (initialize、update、preview、actions) — 関数の目的を要約するトップレベルの @description を含め、その後に各引数 (instance、properties、context) の @param タグを続けます。
ヘルパー関数 — @param、@returns、および 1 行の説明。
配置 — JSDoc はラッパーの上ではなく、内側に配置します (Bubble に貼り付けるときにラッパー行は削除されます)。

例 (initialize ラッパー):

let initialize = function(instance, context) {
  /**
   * @description PLUGIN_PREFIX 要素の 1 回限りのセットアップ。
   * ルート DOM コンテナを作成し、一意のイベント名前空間を生成し、
   * デフォルトのエクスポーズドステートを初期化します。
   *
   * @param {object} instance - Bubble 要素インスタンス (canvas, data, publishState, etc.)
   * @param {object} context  - Bubble コンテキスト (keys, currentUser, etc.)
   */

  // ... 実装 ...
};

デバッグログ (`verbose_logging`)

新しい要素またはアクションをゼロからスキャフォールドする場合は、ユーザーに一度質問します。

「このコンポーネントに verbose_logging トグルを含める必要がありますか？これにより、実行時にすべての console.log 出力をゲートするブールフィールドが Bubble プラグインエディタに追加されます。」

編集、レビュー、リファクタリング、またはバグ修正では質問しないでください。新しいスキャフォールドでのみ質問してください。

ユーザーが同意する場合:

Bubble プラグインエディタの要素またはアクション構成に verbose_logging という名前のブールフィールドを追加し、関連するセットアップファイルにドキュメント化します。
すべての console.log 呼び出しを properties.verbose_logging の背後にゲートします。

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

ログの配置 — ゲートされたログステートメントを以下に追加します。
- update.js、クライアントアクション、およびサーバーアクションのエントリポイント
- データロードが完了した後
- 外部 API 呼び出しの前と後 (サーバーアクション)
catch ブロック内の console.error() は常に無条件です — verbose フラグの背後にエラーログをゲートしないでください。
initialize.js は properties を受信しません — verbose ロギングは利用できません。一時的な初期化時のデバッグにのみプレーンな console.log を使用してください。本番環境の前に削除してください。
preview.js および header.html はエディタでのみ実行されます — verbose ロギングは適用されません。

ユーザーが拒否する場合は、すべての console.log ステートメントを省略します。catch ブロック内の console.error() は無条件のままです。

(原文はここで切り詰められています)

📜 原文 SKILL.md(Claudeが読む英語/中国語)を展開

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.