webflow-cli:designer-extension

Designer 扩展

为 Webflow 创建和开发 Designer 扩展，支持选择模板、本地开发服务器和打包分发。

重要提示

所有 Webflow CLI 操作都必须使用 Bash 工具：

• 通过 Bash 工具执行 webflow extension 命令
• 使用 Read 工具检查生成的文件和架构（切勿修改）
• 使用 Glob 工具查找项目文件
• 验证 CLI 是否已安装：webflow --version
• 检查身份验证状态：webflow auth login（如有需要）
• CLI 工作流中不得使用 Webflow MCP 工具
• 所有 CLI 命令都必须包含恰当的描述（而非上下文参数）

包管理器检测：

• 检查锁定文件：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. 运行初始化命令：执行 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. 运行打包命令：执行 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 生成所有项目文件
• 只读取文件以展示内容

进度指示器

用于 Init：

📋 Creating Extension...

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

✓ Project created
✓ Dependencies installed
Elapsed: 12s

用于 Bundle：

📦 Bundling Extension...

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

✓ Bundle created: bundle.zip
Elapsed: 5s

用于 Serve：

🚀 Starting Server...

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

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

最佳实践

模板选择：

• 使用 react 模板进行现代化的组件式开发
• 使用 default 模板创建简单扩展或用于学习
• 使用 typescript-alt 进行基于 TypeScript 的项目开发

开发工作流：

1. 列出可用模板
2. 使用选定的模板初始化项目
3. 安装依赖项
4. 在本地启动服务进行开发
5. 在 Designer 中测试
6. 打包以上传
7. 上传到 Webflow

Schema 配置：

• 始终包含必填字段：name、apiVersion、publicDir
• 如果扩展会连接到元素，请设置适当的 appIntents
• 为元素集成定义 appConnections
• 使用描述性且唯一的名称

本地开发：

• 使用默认端口 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

Schema 字段（webflow.json）：

• name（必填）- 扩展名称
• apiVersion（必填）- API 版本（2）
• publicDir（必填）- 构建目录
• appIntents（可选）- 元素连接类型
• appConnections（可选）- 连接配置

开发服务器： http://localhost:1337（或自定义端口）

打包输出： 项目目录中的 bundle.zip

文档： https://developers.webflow.com/designer/reference/introduction