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 モジュールを使用するかどうか
   • 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 を使用している場合）
    • import 文を検証します
    • コンポーネントのエクスポートを確認します
    • CSS モジュールの参照を確認します

フェーズ 4：分析と差分のプレビュー

13. 同期前後を比較する：変更内容を表示します：
    • rootDir に新しく作成されたファイル
    • 変更された既存ファイル
    • 追加または更新されたコンポーネント
14. ファイルの差分を表示する：変更されたファイルの主な変更内容を表示します
15. コンポーネントの構成を分析する：
    • コンポーネント数
    • 新しく追加されたコンポーネント
    • 更新されたコンポーネント
    • 生成された CSS ファイル
16. 依存関係を一覧表示する：インポートが必要な項目を表示します

フェーズ 5：統合ガイダンス

17. import 文を提示する：コンポーネントをインポートするための正確なコードを表示します
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 モジュール）

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 から Navigation コンポーネントのみを同期する

**Configuration Update:**

📋 コンポーネントのフィルタリング

特定のコンポーネントのみを同期するには、webflow.json を更新します：

現在の設定： { "devlink": { "rootDir": "./src/devlink", "cssModules": true, "fileExtensions": { "js": "tsx" } } }

components の正規表現パターンを追加します： { "devlink": { "rootDir": "./src/devlink", "cssModules": true, "fileExtensions": { "js": "tsx" }, "components": "Navigation" // 一致させる正規表現パターン } }

パターンのオプション：

• "Navigation" - Navigation コンポーネントのみ
• "Nav.*" - 「Nav」で始まるすべてのコンポーネント
• "Navigation|Footer" - 指定した複数のコンポーネント
• ".*" - すべてのコンポーネント（デフォルト）

webflow.json を更新しますか？（yes/no）

*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. .env ファイルの WEBFLOW_SITE_ID と WEBFLOW_SITE_API_TOKEN を新しい値に更新する
2. または、複数の .env ファイル（.env.site1、.env.site2）を管理する
3. その後、webflow devlink sync を実行する（.env を使用します）

上書きを続行しますか？（yes/no）

### Example 6: TypeScript Configuration

**User prompt:**

DevLink を TypeScript でセットアップする

**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>
  )
}

同期を開始しますか？（yes/no）

## 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 Modules を有効にする	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 Modules を有効にします
• 大規模なサイトでは、コンポーネントを絞り込む具体的な正規表現パターンを使用します

開発ワークフロー：

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 トークンを上書き

設定： devlink セクションを含む webflow.json

スキーマ（必須）：

{
  "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