webflow-cli:designer-extension

Designer 拡張機能

テンプレートの選択、ローカル開発サーバー、配布用のバンドルに対応した、Webflow 用 Designer 拡張機能を作成・開発します。

重要な注意事項

Webflow CLI のすべての操作には、必ず Bash ツールを使用してください。

• webflow extension コマンドは Bash ツールで実行してください
• 生成されたファイルとスキーマの確認には Read ツールを使用してください（変更は禁止）
• プロジェクトファイルの検出には Glob ツールを使用してください
• CLI のインストールを確認してください：webflow --version
• 認証を確認してください（必要な場合）：webflow auth login
• CLI ワークフローで Webflow MCP ツールを使用しないでください
• すべての CLI コマンドには、適切な説明が必要です（context パラメーターではありません）

パッケージマネージャーの検出：

• ロックファイルを確認してください：package-lock.json（npm）、pnpm-lock.yaml（pnpm）、yarn.lock（yarn）
• ロックファイルが見つからない場合は、使用するパッケージマネージャー（npm／pnpm／yarn）をユーザーに確認してください
• インストール／ビルドのすべてのコマンドでは、検出したパッケージマネージャーを使用してください

手順

フェーズ 1：環境の確認

1. CLI のインストールを確認：webflow --version を実行して、CLI がインストールされていることを確認します
2. プロジェクトの状態を確認：すでに拡張機能プロジェクト内にいるか確認します（拡張機能スキーマを含む webflow.json を探します）
3. 操作の種類を特定：ユーザーが次のどれを希望しているか判断します：
   • 利用可能なテンプレートの一覧表示
   • 新しい拡張機能の初期化
   • 既存の拡張機能のバンドル
   • 拡張機能のローカルでのサーブ

フェーズ 2：テンプレートの一覧表示と選択

4. テンプレートを一覧表示（ユーザーが求めた場合、または初期化の前）：webflow extension list を実行します
5. 利用可能なテンプレートを表示：
   • default - 基本的な HTML／CSS／JavaScript テンプレート
   • react - React ベースのテンプレート
   • typescript-alt - 代替の TypeScript テンプレート
6. 新しい拡張機能を初期化する場合は、テンプレートを選択するようユーザーに確認

フェーズ 3：拡張機能の初期化

7. プロジェクト名を決定：プロジェクトのディレクトリ名をユーザーに確認します
8. init コマンドを実行：webflow extension init <project-name> <template> を実行します
9. 生成されたスキーマを読む：Read ツールで webflow.json を確認します
10. スキーマ構造を表示：次の 5 つのスキーマフィールドを表示します：
    • name（必須）- Webflow に表示される拡張機能の名前
    • apiVersion（必須）- API バージョン（2）
    • publicDir（必須）- ビルド元のディレクトリ（dist）
    • appIntents（任意）- 接続を作成できる要素の種類
    • appConnections（任意）- 接続の設定
11. 依存関係をインストール：プロジェクトディレクトリで npm install を実行します

フェーズ 4：ローカル開発

12. 開発サーバーを起動：webflow extension serve [port] を実行します
13. 開発サーバーの情報を表示：
    • デフォルトポート：1337（ユーザーが別のポートを指定した場合を除く）
    • ローカル URL：http://localhost:[port]
    • Designer で読み込む方法
14. 読み込み手順を案内：
    • Webflow Designer を開く
    • ローカル URL から拡張機能を読み込む
    • 機能をテストする

フェーズ 5：アップロード用のバンドル

15. bundle コマンドを実行：webflow extension bundle を実行します
16. バンドルの出力を表示：bundle.zip の場所とサイズを表示します
17. アップロード手順を案内：Webflow にアップロードする手順を案内します
18. 次のステップを説明：テストと配布について案内します

例

例 1：利用可能なテンプレートの一覧表示

ユーザーのプロンプト：

Show me the available Designer Extension templates

応答：

🔍 Designer Extension Templates

Listing available templates...
Executing: webflow extension list

Output:
Available templates:
1. default        - Basic HTML, CSS, and JavaScript
2. react          - React-based extension
3. typescript-alt - Alternative TypeScript template

To create a new extension:
webflow extension init <project-name> <template>

Example:
webflow extension init my-extension react

例 2：新しい拡張機能の初期化

ユーザーのプロンプト：

Create a new Designer Extension called gallery-manager using React

ステップ 1：プロジェクトを初期化

📋 Initialize Designer Extension

Project name: gallery-manager
Template: react

Executing: webflow extension init gallery-manager react

Output:
✓ Created extension project at ./gallery-manager
✓ Generated project structure
✓ Created webflow.json with extension schema
✓ Set up React template

📁 Project Structure:
./gallery-manager/
├── webflow.json         # Extension schema
├── package.json         # Dependencies
├── src/
│   ├── index.html
│   ├── index.tsx
│   └── styles.css
├── dist/                # Build output
└── README.md

Installing dependencies...
Executing: cd gallery-manager && npm install

✓ Dependencies installed (45 packages)

ステップ 2：スキーマを表示

📋 Extension Schema (webflow.json)

Reading webflow.json...

{
  "name": "Gallery Manager",
  "apiVersion": "2",
  "publicDir": "dist",
  "appIntents": {},
  "appConnections": []
}

Schema Fields:
✓ name (required)      - Extension name in Webflow
✓ apiVersion (required) - API version: 2
✓ publicDir (required)  - Build directory: dist
  appIntents (optional) - Element connection types
  appConnections (optional) - Connection configs

Extension ready for development!

例 3：拡張機能をローカルでサーブ

ユーザーのプロンプト：

Run the extension on my local dev server

デフォルトポート（1337）：

🚀 Starting Development Server

Executing: webflow extension serve

Output:
✓ Building extension
✓ Starting dev server
✓ Extension ready

📋 Development Server Running

Local URL: http://localhost:1337
Status: ✓ Active

How to Load in Designer:
1. Open Webflow Designer
2. Open any site
3. Load extension from URL: http://localhost:1337

Press Ctrl+C to stop server

カスタムポート：

User: "Run on port 3000 instead"

🚀 Starting Development Server

Executing: webflow extension serve 3000

Output:
✓ Building extension
✓ Starting dev server on port 3000
✓ Extension ready

📋 Development Server Running

Local URL: http://localhost:3000
Status: ✓ Active

Load in Designer: http://localhost:3000

例 4：拡張機能をバンドル

ユーザーのプロンプト：

Bundle my extension for upload

ステップ 1：バンドル

📦 Bundling Extension

Executing: webflow extension bundle

Output:
✓ Building production bundle
✓ Creating bundle.zip
✓ Bundle created successfully

Bundle Details:
- File: bundle.zip
- Location: ./dist/bundle.zip
- Size: 245 KB

✅ Bundle ready for upload!

ステップ 2：アップロード手順

📤 Upload Instructions

Your extension is bundled and ready to upload.

Upload Steps:
1. Go to Webflow Designer Extensions dashboard
2. Upload bundle.zip
3. Test the extension
4. Submit for review (if distributing)

Bundle location: ./dist/bundle.zip

例 5：一連のワークフロー

ユーザーのプロンプト：

Create a new Designer Extension for managing colors

ステップ 1：テンプレートを一覧表示

🔍 Designer Extension Workflow

First, let me show available templates.

Executing: webflow extension list

Available templates:
1. default        - Basic HTML/CSS/JavaScript
2. react          - React-based (recommended)
3. typescript-alt - TypeScript alternative

Which template would you like to use? (default/react/typescript-alt)

ユーザーが選択：react

ステップ 2：初期化

📋 Creating Extension

Project name: color-manager
Template: react

Executing: webflow extension init color-manager react

✓ Project created at ./color-manager
✓ webflow.json generated
✓ React template configured

Installing dependencies...
✓ npm install complete

📋 Extension Schema:
{
  "name": "Color Manager",
  "apiVersion": "2",
  "publicDir": "dist",
  "appIntents": {},
  "appConnections": []
}

ステップ 3：開発を開始

🚀 Starting Dev Server

Executing: webflow extension serve

✓ Server running at http://localhost:1337

Load in Designer:
1. Open Webflow Designer
2. Load extension from: http://localhost:1337
3. Start developing!

Server running... (Press Ctrl+C to stop)

ガイドライン

フェーズ 1：CLI の確認

インストールの確認：

# Check if CLI is installed
webflow --version

# If not installed, guide user:
npm install -g @webflow/cli

認証（必要な場合）：

# Site authentication if required
webflow auth login

フェーズ 2：テンプレート管理

テンプレート一覧表示コマンド：

webflow extension list

利用可能なテンプレート：

• default - 基本的な HTML、CSS、JavaScript のテンプレート
• react - 最新のツールを使用した React ベースの拡張機能
• typescript-alt - 代替の TypeScript テンプレート

フェーズ 3：初期化

初期化コマンド：

webflow extension init <project-name> <template>

引数：

• <project-name>（必須）- 新しいプロジェクトディレクトリの名前
• <template>（必須）- 次のいずれか：default、react、typescript-alt

コマンドの例：

# Initialize with default template
webflow extension init my-extension default

# Initialize with React template
webflow extension init my-extension react

# Initialize with TypeScript template
webflow extension init my-extension typescript-alt

初期化後のプロジェクト構成：

/project-name/
├── webflow.json         # Extension schema (required)
├── package.json         # Dependencies
├── src/                 # Source files
│   ├── index.html
│   ├── index.tsx (or .js)
│   └── styles.css
├── dist/                # Build output directory
└── README.md

フェーズ 4：拡張機能のスキーマ

webflow.json のスキーマ：

{
  "name": "<Your Extension Name>",
  "apiVersion": "2",
  "publicDir": "dist",
  "appIntents": {
    "image": ["manage"],
    "form": ["manage"]
  },
  "appConnections": [
    "myAppImageConnection",
    "myAppFormConnection"
  ]
}

スキーマのフィールド：

フィールド	説明	デフォルト	必須
name	Webflow に表示される拡張機能の名前	-	はい
apiVersion	拡張機能で使用する API バージョン	2	はい
publicDir	拡張機能のビルドと配信に使用するディレクトリ	dist	はい
appIntents	接続を作成できる要素タイプ	{}	いいえ
appConnections	拡張機能の接続設定	[]	いいえ

必須フィールド：

• name - 一意で説明的な名前にする必要があります
• apiVersion - 現在は「2」である必要があります
• publicDir - ビルドされたファイルが配置されるディレクトリ（デフォルト：「dist」）

任意のフィールド：

• appIntents - 拡張機能に接続できる要素タイプを定義します
  • 例：{"image": ["manage"], "form": ["manage"]}
• appConnections - 接続識別子の配列
  • 例：["myAppImageConnection", "myAppFormConnection"]

フェーズ 5：ローカル開発

配信コマンド：

# Serve on default port (1337)
webflow extension serve

# Serve on custom port
webflow extension serve 3000

引数：

• [port]（任意）- 配信に使用するポート番号（デフォルト：1337）

開発サーバー：

• デフォルト URL：http://localhost:1337
• カスタムポート：http://localhost:[port]
• ファイルの変更時に自動で再ビルド
• 開発を高速化するホットリロード

Designer での読み込み：

1. Webflow Designer を開きます
2. 任意のサイトを開きます
3. Extensions メニューに移動します
4. ローカル URL から拡張機能を読み込みます：http://localhost:[port]
5. 拡張機能が Designer に表示されます

フェーズ 6：バンドル

バンドルコマンド：

webflow extension bundle

出力：

• プロジェクトディレクトリに bundle.zip ファイルを作成します
• publicDir のビルド済みファイルをすべて含みます
• Webflow にアップロードできる状態になります

バンドルの内容：

• ビルド済みの JavaScript ファイルと CSS ファイル
• HTML のエントリーポイント
• publicDir のアセット
• 拡張機能のスキーマ

エラー処理

CLI がインストールされていない場合：

❌ Webflow CLI Not Found

Designer Extensions require the Webflow CLI.

Installation:
npm install -g @webflow/cli

After installation, verify:
webflow --version

Documentation: https://developers.webflow.com/cli

テンプレートが無効な場合：

❌ Invalid Template

Error: Template "vue" not found

Available templates:
- default
- react
- typescript-alt

Retry with valid template:
webflow extension init my-extension react

ポートがすでに使用されている場合：

❌ Development Server Failed to Start

Error: Port 1337 is already in use

Solutions:
1. Stop other process on port 1337
2. Use different port:
   webflow extension serve 3000

Find process using port:
lsof -ti:1337 | xargs kill -9

webflow.json が見つからない場合：

❌ Extension Schema Not Found

Error: webflow.json not found in current directory

This directory is not an extension project.

Solutions:
1. Initialize new extension:
   webflow extension init <name> <template>
2. Navigate to existing extension directory
3. Create webflow.json with required schema

バンドルに失敗した場合：

❌ Bundle Creation Failed

Error: Build failed with errors

Common Causes:
- Missing dependencies (run: npm install)
- Build errors in source files
- Invalid webflow.json schema
- Missing publicDir directory

Fix errors and retry:
webflow extension bundle

ファイル操作

拡張機能ファイルの読み取り： 必ず Read ツールを使用してください（変更は禁止）：

# View extension schema
Read: webflow.json

# View package dependencies
Read: package.json

# View source files
Read: src/index.html
Read: src/index.tsx

プロジェクトファイルの検索： Glob ツールを使用してファイルを検索します：

# Find all source files
Glob: src/**/*

# Find configuration files
Glob: *.json

# Find built files
Glob: dist/**/*

Write/Edit ツールは使用しないでください：

• Write ツールで webflow.json を作成または変更しないでください
• 生成されたファイルを編集しないでください
• CLI にすべてのプロジェクトファイルを生成させてください
• 内容を表示するためにファイルを読み取る場合に限り使用してください

進行状況インジケーター

初期化の場合：

📋 Creating Extension...

[████████████████████████] 100%

✓ Project created
✓ Dependencies installed
Elapsed: 12s

バンドルの場合：

📦 Bundling Extension...

[████████████████████████] 100%

✓ Bundle created: bundle.zip
Elapsed: 5s

配信の場合：

🚀 Starting Server...

[████████████████████████] 100%

✓ Server ready at http://localhost:1337
Elapsed: 3s

ベストプラクティス

テンプレートの選択：

• モダンなコンポーネントベースの開発には react テンプレートを使用します
• シンプルな拡張機能や学習には default テンプレートを使用します
• TypeScript ベースのプロジェクトには typescript-alt を使用します

開発ワークフロー：

1. 利用可能なテンプレートを一覧表示します
2. 選択したテンプレートでプロジェクトを初期化します
3. 依存関係をインストールします
4. 開発用にローカルで起動します
5. Designer でテストします
6. アップロード用にバンドルします
7. Webflow にアップロードします

スキーマの設定：

• 必須フィールドである name、apiVersion、publicDir を必ず含めます
• 拡張機能が要素に接続する場合は、適切な appIntents を設定します
• 要素との連携には appConnections を定義します
• 説明的で一意の name を設定します

ローカル開発：

• 一貫性を保つため、デフォルトのポート 1337 を使用します
• 開発中は開発サーバーを起動したままにします
• Designer で頻繁にテストします
• コンソールでエラーを確認します

バンドル：

• アップロードまたは配布の準備ができてからバンドルします
• エラーなくビルドが完了することを確認します
• bundle.zip のサイズを確認します
• アップロード前にバンドル版をテストします

クイックリファレンス

ワークフロー： テンプレートの一覧表示 → 初期化 → 起動 → 開発 → バンドル → アップロード

主なコマンド：

• webflow extension list - 利用可能なテンプレートを表示します
• webflow extension init <project-name> <template> - 新しい拡張機能を作成します
• webflow extension serve [port] - 開発サーバーを起動します（デフォルト：1337）
• webflow extension bundle - アップロード用の bundle.zip を作成します

テンプレート： default、react、typescript-alt

スキーマフィールド（webflow.json）：

• name（必須）- 拡張機能名
• apiVersion（必須）- API バージョン（2）
• publicDir（必須）- ビルドディレクトリ
• appIntents（任意）- 要素の接続タイプ
• appConnections（任意）- 接続設定

開発サーバー： http://localhost:1337（またはカスタムポート）

バンドル出力： プロジェクトディレクトリ内の bundle.zip

ドキュメント： https://developers.webflow.com/designer/reference/introduction