webflow-cli:devlink

DevLink

将 Webflow Designer 组件导出并同步到 React/Next.js 代码中，提供验证、差异对比和集成指导。

重要提示

所有 Webflow CLI 操作始终使用 Bash 工具：

• 通过 Bash 工具执行 webflow devlink sync
• 使用 Read 工具检查已同步的文件和 webflow.json（切勿修改）
• 使用 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 auth login 创建）
3. 发现项目状态：检查是否存在包含 devlink 配置的 webflow.json
4. 确定目标框架：判断使用的是 React、Next.js 还是其他框架

阶段 2：DevLink 配置

5. 检查现有配置：查找包含 devlink 部分的 webflow.json
6. 读取配置：如果存在，显示当前 devlink 设置：
   • rootDir：导出组件的目录
   • cssModules：是否使用 CSS Modules
   • fileExtensions：生成文件的扩展名
   • 其他配置选项
7. 询问操作类型：明确用户想要执行的操作：
   • 首次配置 DevLink
   • 同步所有组件
   • 同步指定组件（使用 components 正则表达式模式）
   • 更新现有同步
8. 保存基线（如果要更新）：使用 Read 工具在同步前捕获当前文件

阶段 3：执行同步

9. 运行同步命令：执行 webflow devlink sync 并使用以下选项：
   • --api-token 或 -t：覆盖 .env 中的 API 令牌
   • --site-id 或 -s：覆盖 .env 中的网站 ID
10. 监控同步进度：显示 CLI 输出和同步状态
11. 记录同步结果：记录在 rootDir 中创建/修改的文件
12. 验证生成的代码：
    • 检查 TypeScript 错误（如果使用 TS）
    • 验证导入语句
    • 确认组件导出
    • 检查 CSS 模块引用

阶段 4：分析与差异预览

13. 比较前后状态：显示变更内容：
    • 在 rootDir 中创建的新文件
    • 修改的现有文件
    • 新增或更新的组件
14. 显示文件差异：展示修改文件的关键变更
15. 分析组件结构：
    • 组件数量
    • 新增的组件
    • 更新的组件
    • 生成的 CSS 文件
16. 列出依赖项：显示需要导入的内容

阶段 5：集成指导

17. 提供导入语句：展示导入组件的准确代码
18. 展示用法示例：演示如何使用每个组件
19. 记录同步时间：记录同步发生的时间
20. 提供后续步骤：指导用户进行测试和集成

示例

示例 1：首次设置 DevLink

用户提示：

Sync my Webflow components to my Next.js project

步骤 1：环境验证

🔍 DevLink Environment Check

Checking CLI installation...
✓ Webflow CLI installed: v1.5.2

Current directory: /Users/user/projects/my-nextjs-app
Framework detected: Next.js 14

Checking for DevLink configuration...
⚠️ No webflow.json with devlink configuration found

This appears to be your first DevLink sync.
Ready to configure? (yes/no)

用户确认：是

步骤 2：配置设置

📋 DevLink Configuration

DevLink syncs Webflow components to your local project as React code.

Configuration needed in webflow.json:

{
  "devlink": {
    "rootDir": "./devlink",           // Where to export components
    "cssModules": true,                // Use CSS modules
    "fileExtensions": {
      "js": "jsx"                      // or "tsx" for TypeScript
    }
  }
}

I'll help you create this configuration.

Questions:
1. Where should components be exported? (default: ./devlink)
2. Use TypeScript? (yes for tsx, no for jsx)
3. Use CSS modules? (recommended: yes)

用户提供：./src/devlink，是（TypeScript），是（CSS Modules）

Creating webflow.json configuration...

{
  "devlink": {
    "rootDir": "./src/devlink",
    "cssModules": true,
    "fileExtensions": {
      "js": "tsx"
    }
  }
}

✓ Configuration created

⚠️ Authentication Required:
DevLink needs your Webflow site ID and API token.

Run: webflow auth login
This will create a .env file with:
- WEBFLOW_SITE_ID
- WEBFLOW_SITE_API_TOKEN

After authentication, run sync again.

示例 2：配置后的首次同步

用户提示词：

Run the DevLink sync

步骤 1：验证

🔍 DevLink Sync Check

Checking configuration...
✓ webflow.json found with devlink config
✓ Root directory: ./src/devlink
✓ CSS modules: enabled
✓ File extensions: tsx

Checking authentication...
✓ .env found with WEBFLOW_SITE_ID and WEBFLOW_SITE_API_TOKEN

Ready to sync components from Webflow.

步骤 2：执行同步

🔄 Syncing Components

Executing: webflow devlink sync

Output:
✓ Connecting to Webflow site
✓ Fetching components
✓ Exporting components to ./src/devlink
✓ Generating React components
✓ Creating CSS module files
✓ Creating index file

Sync complete!

📁 Generated Files:
./src/devlink/
├── index.ts (module exports)
├── Navigation.tsx (component)
├── Navigation.module.css (styles)
├── Hero.tsx (component)
├── Hero.module.css (styles)
├── Footer.tsx (component)
├── Footer.module.css (styles)
└── _webflow-style.css (global styles)

📊 Sync Summary:
- Components synced: 3
- Files created: 8
- Total size: 45 KB

步骤 3：集成指南

✅ DevLink Sync Complete!

📋 Components Available:
1. Navigation
2. Hero
3. Footer

💡 How to Use:

Import components in your Next.js pages:
```tsx
import { Navigation, Hero, Footer } from './src/devlink'

export default function Home() {
  return (
    <>
      <Navigation />
      <Hero />
      <Footer />
    </>
  )
}

全局样式： 在 _app.tsx 或 layout 中导入全局 DevLink 样式：

import '../src/devlink/_webflow-style.css'

📦 无需额外依赖！ DevLink 组件仅使用 React（已在你的项目中）。

🔄 后续更新： 再次运行 webflow devlink sync，以获取最新设计变更。

### Example 3: Update Existing Sync

**User prompt:**

从 Webflow 同步最新变更

**Step 1: Pre-Sync State**

🔍 DevLink 更新检查

当前状态： ✓ 配置：./src/devlink ✓ 现有组件：3 个（Navigation、Hero、Footer） ✓ 上次同步：2 天前

正在捕获当前状态以供比较…… ✓ 已捕获基线

**Step 2: Sync**

🔄 正在同步更新

正在执行：webflow devlink sync

输出： ✓ 正在连接 Webflow 站点 ✓ 正在获取组件 ✓ 正在检测变更 ✓ 正在更新组件 ✓ 正在重新生成文件

同步完成！

**Step 3: Diff Analysis**

📊 同步分析

检测到变更：

已修改的组件：

1. Navigation.tsx

   • 添加了新的“Contact”链接
   • 更新了移动视图的样式

2. Hero.tsx

   • 更改了标题文本
   • 更新了按钮样式

新组件： 3. CallToAction.tsx（新建）

• 添加了新的 CTA 区块

未更改：

• Footer.tsx

📁 已更新的文件：

• ./src/devlink/Navigation.tsx（已修改）
• ./src/devlink/Navigation.module.css（已修改）
• ./src/devlink/Hero.tsx（已修改）
• ./src/devlink/Hero.module.css（已修改）
• ./src/devlink/CallToAction.tsx（新建）
• ./src/devlink/CallToAction.module.css（新建）
• ./src/devlink/index.ts（已更新导出）

✅ 已更新 3 个组件，新增 1 个组件

💡 可用的新组件：

import { CallToAction } from './src/devlink'

<CallToAction />

### Example 4: Sync Specific Components

**User prompt:**

仅从 Webflow 同步导航组件

**Configuration Update:**

📋 筛选组件

若要仅同步特定组件，请更新 webflow.json：

当前配置： { "devlink": { "rootDir": "./src/devlink", "cssModules": true, "fileExtensions": { "js": "tsx" } } }

添加组件正则表达式： { "devlink": { "rootDir": "./src/devlink", "cssModules": true, "fileExtensions": { "js": "tsx" }, "components": "Navigation" // 用于匹配的正则表达式 } }

匹配模式选项：

• "Navigation" - 仅 Navigation 组件
• "Nav.*" - 所有以 "Nav" 开头的组件
• "Navigation|Footer" - 多个指定组件
• ".*" - 所有组件（默认）

更新 webflow.json？（是/否）

*User confirms: yes*

✓ 配置已更新

正在使用筛选条件同步：“Navigation”

正在执行：webflow devlink sync

输出： ✓ 正在连接 Webflow 站点 ✓ 正在获取组件 ✓ 正在应用筛选条件：Navigation ✓ 正在导出 1 个组件

📁 已生成： ./src/devlink/ ├── index.ts ├── Navigation.tsx └── Navigation.module.css

✅ 已同步 1 个组件（仅 Navigation）

### Example 5: Override Site ID and Token

**User prompt:**

从其他 Webflow 站点同步

**Response:**

🔄 从其他站点同步

若要从其他站点同步，请使用 --site-id 和 --api-token 选项。

获取凭据：

1. 前往 Webflow 站点设置
2. 获取 Site ID
3. 生成 API 令牌（如需要）

同步命令：

webflow devlink sync --site-id <SITE_ID> --api-token <API_TOKEN>

示例：

webflow devlink sync \
  --site-id 5f8a9b2c3d4e5f6g7h8i9j0k \
  --api-token wfp_1234567890abcdef

此操作仅对本次同步覆盖 .env 文件中的值。

⚠️ 注意：你也可以：

1. 使用新的 WEBFLOW_SITE_ID 和 WEBFLOW_SITE_API_TOKEN 更新 .env 文件
2. 或维护多个 .env 文件（.env.site1、.env.site2）
3. 然后运行：webflow devlink sync（使用 .env）

要继续覆盖吗？（是/否）

### Example 6: TypeScript Configuration

**User prompt:**

使用 TypeScript 设置 DevLink

**Response:**

📋 DevLink TypeScript 配置

对于 TypeScript 项目，请配置文件扩展名：

webflow.json： { "devlink": { "rootDir": "./src/devlink", "cssModules": true, "fileExtensions": { "js": "tsx" // 对 TypeScript 使用 .tsx } } }

优点： ✓ 类型安全的组件 ✓ 更好的 IDE 支持 ✓ 自动补全 ✓ 编译时错误检查

同步后，组件将生成为：

• Navigation.tsx（而非 .jsx）
• Hero.tsx
• Footer.tsx

在 TypeScript 中使用：

import { Navigation } from '@/src/devlink'

export default function Layout({ children }: { children: React.ReactNode }) {
  return (
    <div>
      <Navigation />
      {children}
    </div>
  )
}

准备好同步了吗？（是/否）

## Guidelines

### Phase 1: CLI Verification

**Installation Check:**
```bash
# Check if CLI is installed
webflow --version

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

身份验证检查：

# Site authentication creates .env file
# Check for:
cat .env

# Should contain:
# WEBFLOW_SITE_ID=your-site-id
# WEBFLOW_SITE_API_TOKEN=your-token

# If missing, authenticate:
webflow auth login

阶段 2：配置

webflow.json DevLink 架构：

{
  "devlink": {
    "rootDir": "./devlink",
    "cssModules": true,
    "fileExtensions": {
      "js": "jsx"
    }
  }
}

所有配置选项：

选项	描述	默认值	必填
host	Webflow API 主机 URL	https://api.webflow.com	否
rootDir	导出组件的目录	./devlink	是
siteId	Webflow 站点 ID	process.env.WEBFLOW_SITE_ID	否
authToken	Webflow API 身份验证令牌	process.env.WEBFLOW_SITE_API_TOKEN	否
cssModules	为组件样式启用 CSS 模块	true	否
allowTelemetry	允许匿名使用情况分析	true	否
envVariables	将环境变量注入导出的组件	{}	否
components	用于匹配要导出的组件的正则表达式	.*	否
overwriteModule	是否覆盖模块文件	true	否
fileExtensions	导出组件的文件扩展名	{ js: ".js", css: ".css" }	否
skipTagSelectors	从全局 CSS 中排除标签／ID／属性选择器	false	否
relativeHrefRoot	控制如何解析相对 href 属性	/	否

常见配置：

使用 JavaScript 的 React：

{
  "devlink": {
    "rootDir": "./src/components/webflow",
    "cssModules": true,
    "fileExtensions": {
      "js": "jsx"
    }
  }
}

使用 TypeScript 的 Next.js：

{
  "devlink": {
    "rootDir": "./src/devlink",
    "cssModules": true,
    "fileExtensions": {
      "js": "tsx"
    }
  }
}

同步特定组件：

{
  "devlink": {
    "rootDir": "./src/devlink",
    "cssModules": true,
    "components": "Navigation|Hero|Footer"
  }
}

阶段 3：同步命令

基本同步：

# Uses webflow.json config and .env credentials
webflow devlink sync

使用选项同步：

# Override site ID
webflow devlink sync --site-id 5f8a9b2c3d4e5f6g7h8i9j0k

# Override API token
webflow devlink sync --api-token wfp_1234567890abcdef

# Override both
webflow devlink sync \
  --site-id 5f8a9b2c3d4e5f6g7h8i9j0k \
  --api-token wfp_1234567890abcdef

# Short flags
webflow devlink sync -s <site-id> -t <api-token>

同步选项：

• --api-token / -t：要使用的 API 令牌，覆盖 .env 文件中的设置
• --site-id / -s：要从中同步的站点 ID，覆盖 .env 文件中的设置

阶段 4：生成的文件

目录结构： 同步后，rootDir 包含：

./devlink/
├── index.ts                  // Module exports
├── ComponentName.tsx         // Component file
├── ComponentName.module.css  // Component styles (if cssModules: true)
├── AnotherComponent.tsx
├── AnotherComponent.module.css
└── _webflow-style.css        // Global Webflow styles

组件结构： 生成的组件是 React 函数式组件：

import React from 'react'
import styles from './ComponentName.module.css'

export function ComponentName() {
  return (
    <div className={styles.container}>
      {/* Component markup */}
    </div>
  )
}

索引文件： 导出所有组件，方便导入：

export { ComponentName } from './ComponentName'
export { AnotherComponent } from './AnotherComponent'

错误处理

未安装 CLI：

❌ Webflow CLI Not Found

The Webflow CLI is required for DevLink.

Installation:
npm install -g @webflow/webflow-cli

After installation, verify:
webflow --version

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

未通过身份验证：

❌ Not Authenticated

DevLink needs authentication to access your Webflow site.

Steps:
1. Run: webflow auth login
2. Follow authentication prompts in browser
3. Select your site when prompted
4. Verify: .env file created with:
   - WEBFLOW_SITE_ID
   - WEBFLOW_SITE_API_TOKEN
5. Retry sync

Need help? https://developers.webflow.com/cli/authentication

没有配置：

❌ DevLink Not Configured

No webflow.json with devlink configuration found.

Create webflow.json in project root:
{
  "devlink": {
    "rootDir": "./devlink",
    "cssModules": true,
    "fileExtensions": {
      "js": "jsx"  // or "tsx" for TypeScript
    }
  }
}

Required fields:
- rootDir: Where to export components

After configuration, run: webflow devlink sync

同步失败：

❌ Sync Failed

Error: [Specific error from CLI]

Common Causes:
- Network connection issues
- Invalid site ID or API token
- Insufficient permissions
- Site has no components to export

Solutions:
1. Check internet connection
2. Verify credentials in .env
3. Check site permissions in Webflow
4. Ensure site has published components
5. Try: webflow devlink sync --site-id <id> --api-token <token>

Retry sync? (yes/no)

站点 ID 无效：

❌ Invalid Site ID

The provided site ID is invalid or inaccessible.

Check:
1. Verify WEBFLOW_SITE_ID in .env
2. Ensure you have access to the site
3. Check site ID in Webflow dashboard

Get site ID:
1. Open site in Webflow
2. Go to Site Settings
3. Find Site ID in General tab

Update .env and retry sync.

文件操作

读取文件： 始终使用 Read 工具（绝不修改）：

# View DevLink configuration
Read: webflow.json

# View environment
Read: .env

# View generated component
Read: ./devlink/Navigation.tsx

# View generated styles
Read: ./devlink/Navigation.module.css

查找文件： 使用 Glob 工具查找文件：

# Find all generated components
Glob: ./devlink/**/*.tsx

# Find all CSS modules
Glob: ./devlink/**/*.module.css

# Find configuration
Glob: webflow.json

绝不使用 Write/Edit 工具：

• 不要使用 Write 创建 webflow.json（向用户展示其结构）
• 不要修改生成的组件
• 让 CLI 负责生成文件
• 仅读取文件以展示内容和差异

进度指示

同步时：

🔄 Syncing Components...

Connecting to Webflow... ✓
Fetching components... ✓
Generating React code... ⏳
Creating CSS modules... ⏳

Processed: 3/5 components
Elapsed: 8s

最佳实践

配置：

• 将 webflow.json 放在项目根目录
• 使用 TypeScript（.tsx）以获得更好的类型安全性
• 启用 CSS 模块，实现作用域样式
• 对大型站点使用精确的组件正则表达式

开发工作流：

1. 在 Webflow Designer 中设计
2. 发布更改
3. 运行 webflow devlink sync
4. 集成前检查差异
5. 在应用中测试组件

集成：

• 在应用入口点导入全局样式（_webflow-style.css）
• 在需要的位置导入组件
• 不要修改生成的文件（它们会被覆盖）
• 如需自定义，请封装 DevLink 组件

版本控制：

• 提交 webflow.json
• 将 .env 添加到 .gitignore
• 提交生成的 devlink/ 目录（或将其添加到 .gitignore）
• 记录上次同步的时间戳

多个站点：

• 为每个站点使用不同的 rootDir
• 或使用 components 模式进行筛选
• 使用 --site-id 和 --api-token 覆盖凭据
• 维护单独的 .env 文件

快速参考

工作流： 配置 webflow.json → 进行身份验证 → 同步

主要命令：

• webflow devlink sync - 从 Webflow 同步组件
• webflow devlink sync -s <id> -t <token> - 使用覆盖值进行同步

同步选项：

• -s / --site-id - 覆盖站点 ID
• -t / --api-token - 覆盖 API 令牌

配置： webflow.json 中的 devlink 部分

架构（必需）：

{
  "devlink": {
    "rootDir": "./devlink"  // Required
  }
}

架构（常用）：

{
  "devlink": {
    "rootDir": "./devlink",
    "cssModules": true,
    "fileExtensions": {
      "js": "jsx"  // or "tsx"
    }
  }
}

身份验证： 通过 webflow auth login 进行站点身份验证

环境变量： 在 .env 中设置 WEBFLOW_SITE_ID 和 WEBFLOW_SITE_API_TOKEN

验证： 首先检查 webflow --version 和站点身份验证

生成的文件： 在 rootDir 中生成带 CSS 模块的 React 组件

文档： https://developers.webflow.com/devlink