webflow-cli:code-component

コードコンポーネント

包括的な検証とデプロイ確認を行い、React コンポーネントを作成、ビルドして Webflow Designer にデプロイします。

重要な注意事項

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

• Bash ツールを使用して webflow CLI コマンドを実行します
• Read ツールを使用して生成されたファイルを確認します（変更は加えないでください）
• Glob ツールを使用してプロジェクトファイルを検索します
• CLI のインストールを確認します：webflow --version
• 認証を確認します：初回の webflow library share で、ワークスペース認証が自動的に行われます
• 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. プロジェクトの状態を確認：ユーザーが既存の React プロジェクトを持っているか、ガイダンスが必要かを判断します
3. ワークスペースを確認：初回の共有時にワークスペース認証が行われることを説明します
4. 設定を確認：ライブラリ設定を含む webflow.json が存在するか確認します

フェーズ 2：プロジェクトの設定

5. 操作の種類を尋ねる：ユーザーが何をしたいのか確認します：
   • 既存の React プロジェクトをコードコンポーネント用に設定する
   • 設定済みのプロジェクトにコンポーネントを追加する
   • 既存のライブラリをビルドして共有する
6. webflow.json を設定：webflow.json にライブラリ設定を追加します：
   • ライブラリ名（Webflow Designer に表示されます）
   • コンポーネントの glob パターン（例：./src/**/*.webflow.tsx）
   • カスタム webpack 用の bundleConfig（任意）
7. 設定ファイルを読み取る：Read ツールを使用して、以下を表示します：
   • webflow.json — ライブラリ設定
   • package.json — 依存関係とスクリプト
   • コンポーネントのファイル構成
8. 依存関係を確認：React がインストールされ、ビルドスクリプトが存在することを確認します

フェーズ 3：ビルドとバンドルの検証

9. ビルドを実行：ユーザーのビルドコマンドを実行します（例：npm run build、yarn build）
10. ビルド出力を検証：ビルドエラーや警告がないか確認します
11. バンドルコマンドを実行：webflow library bundle を実行してローカルで検証します
12. バンドルを分析：
    • バンドルサイズ（2MB 未満であること）
    • 含まれている依存関係
    • 出力先（デフォルト：./dist）
    • 検証時の警告
13. バンドルの詳細をプレビュー：検証状況を含むバンドルの概要を表示します

フェーズ 4：プレビューと承認

14. デプロイのプレビューを表示：
    • webflow.json のライブラリ名
    • 含まれるコンポーネントファイル
    • バンドルサイズと検証状況
    • 対象のワークスペース（初回の共有時に選択されます）
    • 初回の場合はワークスペース認証について説明します
15. デプロイについて説明：ライブラリを共有した際に何が起きるか説明します
16. 明示的な確認を求める：続行するには、ユーザーが「share」または「deploy」と入力する必要があります
17. ワークスペースを確認：初回に限り、ワークスペースを選択するためブラウザーが開くことを説明します

フェーズ 5：デプロイと確認

18. 共有コマンドを実行：webflow library share を実行します
19. デプロイの状況を確認：CLI の出力と進行状況を表示します
20. ワークスペース認証に対応：初回の場合は、ブラウザーでの認証をユーザーに案内します
21. デプロイの成功を確認：ライブラリがワークスペースに表示されることを確認します
22. .env の更新内容を表示：WEBFLOW_WORKSPACE_ID と WEBFLOW_WORKSPACE_API_TOKEN が追加されたことを説明します
23. 次の手順を案内：
    • Designer でコンポーネントを使用する方法
    • コンポーネントを更新する方法
    • テストに関する推奨事項
    • デバッグに webflow library log を使用する方法

例

例 1：既存の React プロジェクトを設定する

ユーザープロンプト：

I have a React project with some components I want to share to Webflow

ステップ 1：環境の確認

🔍 Webflow CLI Environment Check

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

Current directory: /Users/user/projects/my-components
✓ Found package.json with React project
✓ Found src/ directory with components

Checking webflow.json...
⚠️ No webflow.json found - needs configuration

Ready to configure for Code Components? (yes/no)

ユーザーが確認：はい

ステップ 2：プロジェクトの設定

📋 Configure Code Components Library

I'll help you add the library configuration to webflow.json.

Questions:
1. What should your library be called in Webflow Designer?
   Example: "My Component Library"

2. Where are your component files located?
   Pattern examples:
   - "./src/**/*.webflow.tsx" (components with .webflow.tsx extension)
   - "./src/components/**/*.tsx" (all components in src/components/)
   - "./src/Button.tsx" (specific files)

Let me know the library name and component pattern.

ユーザーが入力：「Acme Components」と「./src/**/.webflow.tsx」*

Creating webflow.json configuration...

{
  "library": {
    "name": "Acme Components",
    "components": ["./src/**/*.webflow.tsx"]
  }
}

✓ Configuration ready

Found component files:
- src/Button.webflow.tsx
- src/Card.webflow.tsx
- src/Hero.webflow.tsx

Next: Build your components and run bundle command.

ステップ 3：ビルドとバンドルの検証

🔨 Building Components

What build command do you use? (e.g., npm run build, yarn build)

ユーザーの応答：npm run build

Executing: npm run build

Output:
✓ TypeScript compilation successful
✓ Components built to dist/

Creating bundle for validation...
Executing: webflow library bundle

Output:
✓ Analyzing 3 components
✓ Bundling dependencies
✓ Creating bundle
✓ Bundle created: dist/bundle.js

📦 Bundle Analysis:
- Size: 287 KB (✓ within 2MB limit)
- Components: 3 (Button, Card, Hero)
- Dependencies: [email protected], [email protected]
- Output: ./dist
- Validation: ✅ All checks passed

ステップ 4：プレビューと承認

📋 Deployment Preview

Library: Acme Components
Components: 3 (Button, Card, Hero)
Bundle Size: 287 KB

Workspace Authentication:
⚠️ This appears to be your first deployment. When you run 'share':
1. Browser will open for workspace authentication
2. Select your target Webflow workspace
3. Grant access to deploy components
4. CLI will create .env with credentials:
   - WEBFLOW_WORKSPACE_ID
   - WEBFLOW_WORKSPACE_API_TOKEN

Validation Status: ✅ Ready to deploy
- Bundle size: ✓ 287 KB (< 2MB limit)
- Dependencies: ✓ Valid (React 18.2.0)
- Configuration: ✓ webflow.json valid
- Components: ✓ 3 components found

⚠️ Type "share" to deploy this library to your workspace.

ユーザーが確認：共有

ステップ 5：デプロイと検証

🚀 Deploying Library

Executing: webflow library share

Output:
✓ Bundling library (287 KB)
✓ Opening browser for workspace authentication...

[Browser opens - user authenticates and selects workspace]

✓ Workspace authenticated: Acme Corp
✓ Uploading bundle
✓ Validating components
✓ Registering with workspace
✓ Library deployed successfully

✅ Library Deployed: Acme Components

Workspace: Acme Corp
Components: 3 (Button, Card, Hero)
Version: Latest
Status: Active

📁 Environment Updated:
Created .env file with:
- WEBFLOW_WORKSPACE_ID=workspace_abc123
- WEBFLOW_WORKSPACE_API_TOKEN=************

⚠️ Important: Add .env to your .gitignore file!

📋 Next Steps:
1. Open Webflow Designer
2. Go to Add Elements → Code Components
3. Find "Acme Components" in the list
4. Drag components onto canvas to use

💡 To update components:
1. Make changes to your component files
2. Run: npm run build
3. Run: webflow library share
   (No re-authentication needed - uses .env credentials)

🔍 For debugging:
- View logs: webflow library log
- Bundle locally: webflow library bundle
- Check bundle size: webflow library bundle --verbose

Component Library URL: https://webflow.com/dashboard/workspaces/acme-corp/components

例 2：既存のライブラリを更新する

ユーザープロンプト：

Update my Code Components library with new changes

ステップ 1：環境の確認

🔍 Code Components Library Check

Checking configuration...
✓ webflow.json found with library config
✓ Library name: Acme Components
✓ Components pattern: ./src/**/*.webflow.tsx

Checking authentication...
✓ Found .env with workspace credentials
✓ Workspace: Acme Corp

Found components:
- src/Button.webflow.tsx (modified)
- src/Card.webflow.tsx
- src/Hero.webflow.tsx
- src/Form.webflow.tsx (new)

Ready to build and share updates? (yes/no)

ステップ 2～3：ビルドとバンドル

🔨 Building Components

Executing: npm run build
✓ Build complete

Bundling for validation...
Executing: webflow library bundle

📦 Bundle Analysis:
- Size: 312 KB (✓ within 2MB limit)
- Components: 4 (Button, Card, Hero, Form) [+1 new]
- Changes: Button updated, Form added
- Validation: ✅ All checks passed

ステップ 4：プレビュー

📋 Update Preview

Library: Acme Components
Workspace: Acme Corp (already authenticated)

Changes:
✓ Button component (updated)
✓ Form component (new)
  Card component (unchanged)
  Hero component (unchanged)

Bundle Size: 312 KB (+25 KB from 287 KB)

No re-authentication needed - using existing workspace credentials.

⚠️ Type "share" to update the library.

ステップ 5：デプロイ

🚀 Updating Library

Executing: webflow library share

Output:
✓ Bundling library (312 KB)
✓ Using workspace: Acme Corp
✓ Uploading bundle
✓ Validating components
✓ Updating library
✓ Library updated successfully

✅ Library Updated: Acme Components

Changes deployed:
- Button: Updated ✨
- Form: Added 🆕
- Card: Unchanged
- Hero: Unchanged

💡 Refresh Webflow Designer to see changes:
1. Open Designer
2. Components may auto-refresh
3. Or refresh browser if needed

Components updated in workspace!

例 3：初めてのバンドルテスト

ユーザープロンプト：

I want to test my bundle locally before sharing

ステップ 1～2：確認と設定

🔍 Local Bundle Testing

✓ webflow.json configured
✓ Library: My Components
✓ Components: ./src/**/*.webflow.tsx

Running local bundle only (no deployment)...

ステップ 3：バンドルの検証

🔨 Building Components

Executing: npm run build
✓ Build complete

Creating local bundle...
Executing: webflow library bundle

Output:
✓ Analyzing components
✓ Bundling dependencies
✓ Optimizing output
✓ Bundle created: dist/bundle.js

📦 Bundle Details:

Size: 1.2 MB (✓ within 2MB limit)

Components (5):
├── Button.webflow.tsx (25 KB)
├── Card.webflow.tsx (18 KB)
├── Hero.webflow.tsx (45 KB)
├── Form.webflow.tsx (32 KB)
└── Modal.webflow.tsx (28 KB)

Dependencies:
├── [email protected] (included)
├── [email protected] (included)
└── [email protected] (included)

Output Directory: ./dist/
- bundle.js (1.2 MB)
- manifest.json

Validation: ✅ All checks passed

💡 Bundle is valid and ready to share!
   Run: webflow library share (when ready to deploy)

例 4：バンドルが大きすぎる場合

ユーザープロンプト：

Share my components library

バンドル検証エラー：

🔨 Building and Bundling

Executing: npm run build
✓ Build complete

Executing: webflow library bundle

Output:
✓ Analyzing components
✓ Bundling dependencies
⚠️ Bundle size check...

📦 Bundle Analysis:
- Size: 2.4 MB (❌ exceeds 2MB limit)
- Components: 6
- Dependencies: [email protected], [email protected], [email protected], [email protected]
- Validation: ❌ Issues found

❌ Bundle Too Large

Current size: 2.4 MB
Maximum allowed: 2 MB
Exceeded by: 400 KB

📊 Size Breakdown:
- React + React DOM: ~800 KB
- lodash: ~500 KB ⚠️
- moment: ~350 KB ⚠️
- Your components: ~750 KB

💡 Recommendations:
1. Remove lodash (use native JS instead)
   - Replace _.map with Array.map
   - Replace _.filter with Array.filter
   - Or use lodash-es and import specific functions

2. Replace moment with lighter alternative
   - Use date-fns (~15 KB vs 350 KB)
   - Or use native Intl.DateTimeFormat

3. Optimize component code
   - Remove unused imports
   - Enable tree-shaking
   - Split large components

4. Use external assets
   - Host large images externally
   - Use CDN for static assets

Would you like to:
1. Continue anyway (using --force flag, not recommended)
2. Review component imports to optimize
3. Cancel and fix manually

例 5：CI/CD デプロイ

ユーザープロンプト：

How do I deploy in CI/CD pipeline?

応答：

🤖 CI/CD Deployment Setup

For automated deployments, use non-interactive mode with API tokens.

### Setup Steps:

1. **Get Workspace API Token**
   - Open Workspace Settings in Webflow
   - Go to Integrations → Workspace API Token
   - Generate new token
   - Copy token securely

2. **Add to CI/CD Secrets**
   - Add as environment variable: WORKSPACE_API_TOKEN
   - Never commit tokens to version control

3. **Deployment Command**
   ```bash
   webflow library share --api-token $WORKSPACE_API_TOKEN --no-input

例：GitHub Actions

name: Deploy Components
on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3

      - name: Setup Node
        uses: actions/setup-node@v3
        with:
          node-version: 18

      - name: Install dependencies
        run: npm install

      - name: Install Webflow CLI
        run: npm install -g @webflow/webflow-cli

      - name: Build components
        run: npm run build

      - name: Deploy to Webflow
        run: |
          webflow library share \
            --api-token ${{ secrets.WORKSPACE_API_TOKEN }} \
            --no-input \
            --force
        env:
          WORKSPACE_API_TOKEN: ${{ secrets.WORKSPACE_API_TOKEN }}

複数のワークスペース：

# Deploy to workspace 1
webflow library share \
  --api-token $WORKSPACE_1_TOKEN \
  --no-input

# Deploy to workspace 2
webflow library share \
  --api-token $WORKSPACE_2_TOKEN \
  --no-input

オプション：

• --no-input - 対話型プロンプトを無効にします
• --force - 警告があっても続行します
• --verbose - 詳細な出力を表示します
• --dev - 開発モードでバンドルします（テスト用）

⚠️ セキュリティ：

• .env ファイルをコミットしないでください
• CI/CD ではシークレット管理を使用してください
• トークンを定期的にローテーションしてください
• トークンの権限を制限してください

## 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

プロジェクトの確認：

# Check for existing configuration
ls webflow.json

# Check for React project
ls package.json

# Check for components
ls src/

認証に関する注意： サイト認証とは異なり、Code Components のワークスペース認証は、初回の webflow library share 時に自動的に行われます。CLI は次の処理を行います。

1. 認証のためにブラウザーを開きます
2. ユーザーがワークスペースを選択できるようにします
3. WEBFLOW_WORKSPACE_ID と WEBFLOW_WORKSPACE_API_TOKEN を含む .env を作成します

フェーズ 2：プロジェクトの設定

webflow.json の構造：

{
  "library": {
    "name": "<Your Library Name>",
    "components": ["./src/**/*.webflow.@(js|jsx|mjs|ts|tsx)"],
    "bundleConfig": "./webpack.webflow.js"
  }
}

設定フィールド：

• name（必須）：Webflow Designer に表示されるライブラリ名
• components（必須）：コンポーネントファイルに一致する Glob パターン
  • 例："./src/**/*.webflow.tsx" - src/ 内のすべての .webflow.tsx ファイル
  • 例："./src/components/**/*.tsx" - src/components/ 内のすべての .tsx ファイル
• bundleConfig（任意）：カスタム webpack 設定へのパス

コンポーネントの命名規則：

• 拡張子の前に .webflow を追加します：Button.webflow.tsx
• または、Glob パターンを使って特定のディレクトリ内のすべてのファイルを含めます
• コンポーネントは React コンポーネントである必要があります

init コマンドはありません： 他の CLI 製品とは異なり、Code Components には init コマンドがありません。ユーザーはライブラリ設定を含む webflow.json を追加して、既存の React プロジェクトを設定します。

フェーズ 3：ビルドとバンドル

ビルドプロセス：

# Use project's build script
npm run build
# or
yarn build
# or
pnpm build

# Check for errors
echo $?  # 0 = success, non-zero = failure

バンドルコマンド：

# Bundle locally (optional - for testing/validation)
webflow library bundle

# Bundle output: ./dist/ (default)
# Can override: webflow library bundle --output-path ./build

バンドルオプション：

• --output-path <path> - 出力ディレクトリを上書きします（デフォルト：./dist）
• --public-path <path> - パブリックパスを上書きします
• --force - 警告があっても強制的にバンドルします
• --debug-bundler - webpack の設定を表示します
• --dev - 開発モードでバンドルします
• --verbose - 詳細な出力を表示します

バンドルの検証： 次の項目を確認してください。

• サイズ制限：2MB 未満であること
• 依存関係：React のバージョンに互換性があること
• 出力：バンドルが dist/ ディレクトリに作成されていること
• コンポーネント：すべてのコンポーネントファイルが含まれていること

よくあるビルドエラー：

• TypeScript のコンパイルエラー → 型の問題を修正します
• 依存関係の不足 → npm install を実行します
• インポートエラー → ファイルパスを確認します
• バンドルが大きすぎる → 依存関係を最適化します

フェーズ 4：デプロイのプレビュー

プレビュー形式：

📋 Deployment Preview

Library: [Name from webflow.json]
Components: [Count] ([List of components])
Bundle Size: [Size in KB/MB]

Workspace Authentication:
[First time: Explain browser auth flow]
[Subsequent: Show workspace from .env]

Validation Status:
✓ Bundle size: [X KB] (< 2MB limit)
✓ Dependencies: Valid
✓ Configuration: webflow.json valid
✓ Components: [N] components found

⚠️ Type "share" to proceed

初回認証： 次の点を明確に説明します。

1. ブラウザーが開きます
2. ユーザーが Webflow で認証します
3. ユーザーが対象のワークスペースを選択します
4. CLI が認証情報を含む .env を作成します
5. 以降の共有ではこの認証情報が使用されます（再認証は不要です）

フェーズ 5：デプロイの実行

共有コマンド：

# Standard share (interactive)
webflow library share

# Non-interactive (for CI/CD)
webflow library share --api-token <TOKEN> --no-input

# Force share (ignore warnings)
webflow library share --force

# Development mode
webflow library share --dev

共有オプション：

• --manifest - webflow.json のパス（デフォルトでは現在のディレクトリをスキャンします）
• --api-token - ワークスペースの API トークン（CI/CD 用）
• --no-input - 対話型プロンプトを無効にします
• --force - 警告があっても強制的にバンドルします
• --debug-bundler - バンドラーの設定を表示します
• --dev - 開発モードでバンドルします
• --verbose - 詳細な出力を表示します

成功を示す項目：

• バンドルが正常にアップロードされている
• ライブラリがワークスペースに登録されている
• コンポーネントが Designer で利用できる
• .env ファイルが作成／更新されている（初回）

環境ファイル（.env）： 初回の共有が正常に完了すると：

WEBFLOW_WORKSPACE_ID=your-workspace-id
WEBFLOW_WORKSPACE_API_TOKEN=your-api-token

⚠️ 重要：必ず .env を .gitignore に追加してください！

確認手順：

1. CLI の出力に成功メッセージがあることを確認します
2. .env ファイルが作成されていることを確認します（初回）
3. Designer へのアクセス手順を案内します
4. ワークスペースのダッシュボード URL を表示します

フェーズ 6：デバッグ

ログコマンド：

# Show latest log file location
webflow library log

# Example output:
# Latest log: /Users/user/.webflow/logs/library-2024-01-20-15-30-45.log

次の場合にこのコマンドを使用します：

• バンドルが原因の不明なエラーで失敗する場合
• 共有コマンドで警告が発生する場合
• webpack の設定をデバッグする必要がある場合
• 依存関係の問題を調査する場合

よくある問題：

問題：「Could not find webflow.json」

❌ Configuration Not Found

The CLI couldn't find webflow.json in the current directory.

Solution:
1. Ensure you're in the project root
2. Create webflow.json with library configuration:
   {
     "library": {
       "name": "Your Library Name",
       "components": ["./src/**/*.webflow.tsx"]
     }
   }
3. Run command again

問題：「No components found」

❌ No Components Found

The components glob pattern didn't match any files.

Current pattern: "./src/**/*.webflow.tsx"

Solution:
1. Check component files have correct naming
2. Verify glob pattern in webflow.json
3. Common patterns:
   - "./src/**/*.webflow.tsx" (requires .webflow in name)
   - "./src/components/**/*.tsx" (all tsx in folder)
   - "./src/Button.tsx" (specific file)

Found files:
- src/Button.tsx (not matching pattern)
- src/Card.tsx (not matching pattern)

Suggestion: Rename to Button.webflow.tsx or update pattern

エラー処理

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

❌ Webflow CLI Not Found

The Webflow CLI is required for Code Components.

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

After installation, verify:
webflow --version

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

ビルドの失敗：

❌ Build Failed

Error: [Specific error message]

Common Fixes:
- TypeScript errors: Review type definitions
- Missing deps: Run npm install
- Import errors: Check file paths
- Syntax errors: Check React component syntax

Show build output for details.
Need help? Run: webflow library log

バンドルの失敗：

❌ Bundle Failed

Error: [Specific error from CLI]

Common Causes:
- Invalid component files
- Webpack configuration errors
- Dependency conflicts
- File path issues

View detailed logs: webflow library log

Possible solutions:
1. Check component file syntax
2. Verify webflow.json configuration
3. Remove bundleConfig to use defaults
4. Check dependencies in package.json

デプロイの失敗：

❌ Share Failed

Error: [Specific error from CLI]

Possible Causes:
- Network connection issues
- Workspace authentication expired
- Bundle validation failed
- Workspace permissions

Solutions:
1. Check internet connection
2. Re-authenticate: Remove .env and run share again
3. Fix bundle issues: Run webflow library bundle first
4. Verify workspace access in Webflow dashboard

Retry share? (yes/no)

ファイル操作

ファイルの読み取り： 必ず Read ツールを使用します（変更はしません）：

# View library configuration
Read: webflow.json

# View package dependencies
Read: package.json

# View component source
Read: src/Button.webflow.tsx

# View environment (if exists)
Read: .env

ファイルの検索： Glob ツールを使ってファイルを検索します：

# Find all webflow components
Glob: **/*.webflow.tsx

# Find configuration files
Glob: *.json

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

# Find build output
Glob: dist/**/*

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

• Write を使って webflow.json を作成しないでください（構造をユーザーに提示します）
• コンポーネントファイルを変更しないでください
• package.json を編集しないでください
• ファイルの変更はユーザーに任せてください
• 内容を表示するためにファイルを読み取ることだけを行ってください

進行状況の表示

バンドルの場合：

🔄 Bundling Components...

Analyzing components... ✓
Resolving dependencies... ✓
Building bundle... ⏳
Optimizing... ⏳

Elapsed: 8s

デプロイの場合：

🚀 Sharing Library...

Creating bundle... ✓
Uploading to workspace... ⏳
Validating components... ⏳

Uploaded: 287 KB
Elapsed: 12s

安全な操作パターン

確認キーワード：

• "share" - ライブラリをワークスペースに共有します
• "deploy" - "share" の代わりに使用します
• "proceed" - 操作を続行します
• "cancel" - 操作をキャンセルします
• "skip" - オプションの手順をスキップします

共有前のプレビュー： 必ず次の内容を表示します：

• 共有するもの（ライブラリ名、コンポーネント）
• 共有先（ワークスペース、または初回認証が必要かどうか）
• バンドルサイズと検証状況
• 変更の影響（新規／更新されるコンポーネント）

透明性：

• 実行前にすべての CLI コマンドを表示します
• CLI の出力全体を表示します
• 成功／失敗を明確に報告します
• トラブルシューティングの手引きを提示します
• デバッグ用にログの保存場所を示します

ベストプラクティス

コンポーネント開発：

• 型安全性のために TypeScript を使用します
• React のベストプラクティスに従います
• バンドルサイズを小さく保ちます（理想は 1 MB 未満）
• 分かりやすいように、ファイル名に .webflow 拡張子を付けます
• コンポーネントの props をドキュメント化します

依存関係の管理：

• 依存関係を最小限に抑えます
• 大規模なライブラリ（lodash、moment）は避けます
• ツリーシェイキング可能なパッケージを使用します
• バンドルへの影響を確認します：webflow library bundle --verbose
• React はピア依存関係として指定します（バンドルされません）

更新とバージョン管理：

• 共有前にビルドします
• バンドルをローカルでテストします：webflow library bundle
• 更新するには共有します：webflow library share
• バージョン番号は不要です（常に「latest」）
• デプロイ後に Designer でテストします

ワークスペースの管理：

• .env ファイルごとにワークスペースを 1 つ使用します
• 複数のワークスペースには --api-token を使用します
• .env を .gitignore に追加します
• CI/CD でトークンをローテーションします
• 設定されているワークスペースを記録します

設定：

• webflow.json はプロジェクトのルートに置きます
• 分かりやすいライブラリ名を使用します
• 具体的なコンポーネントの glob パターンを使用します
• 必要な場合にのみ bundleConfig を追加します
• webflow.json はバージョン管理し、.env は管理対象に含めません

コンポーネントのライフサイクル

初期設定：

1. React プロジェクトを作成するか、既存のプロジェクトを用意します
2. ライブラリ設定を含む webflow.json を追加します
3. コンポーネントファイルに名前を付けます（例：.webflow.tsx）
4. ビルドします：npm run build
5. バンドルをテストします：webflow library bundle
6. 共有します：webflow library share（初回は認証が必要です）

更新時：

1. コンポーネントのソースファイルを編集します
2. ビルドします：npm run build
3. 共有します：webflow library share（保存済みの認証情報を使用します）
4. Designer を更新して変更を確認します

テスト：

1. ローカルでバンドルします：webflow library bundle
2. バンドルサイズと検証結果を確認します
3. 問題があれば修正します
4. 準備ができたら共有します：webflow library share
5. Webflow Designer を開きます
6. コンポーネントをページに追加します
7. 動作をテストします

デバッグ：

1. ログを表示します：webflow library log
2. 詳細出力付きでバンドルします：webflow library bundle --verbose
3. 設定を確認します：cat webflow.json
4. ビルドを確認します：npm run build
5. 開発モードでテストします：webflow library share --dev

CLI コマンドリファレンス

インストール：

# Install CLI globally
npm install -g @webflow/webflow-cli

# Verify installation
webflow --version

ライブラリコマンド：

# Bundle locally (testing/validation)
webflow library bundle [options]

# Share to workspace (bundle + deploy)
webflow library share [options]

# View latest log file
webflow library log

バンドルオプション：

# Custom output path
webflow library bundle --output-path ./build

# Force bundling (ignore warnings)
webflow library bundle --force

# Development mode
webflow library bundle --dev

# Show bundler config
webflow library bundle --debug-bundler

# Verbose output
webflow library bundle --verbose

共有オプション：

# Standard interactive share
webflow library share

# Non-interactive (CI/CD)
webflow library share --no-input --api-token <TOKEN>

# Force share (ignore warnings)
webflow library share --force

# Development mode
webflow library share --dev

# Custom manifest location
webflow library share --manifest ./config/webflow.json

グローバルオプション：

# Show version
webflow --version

# Show help
webflow --help
webflow library --help
webflow library share --help

クイックリファレンス

ワークフロー： webflow.json の設定 → ビルド → バンドル → 共有

主要なコマンド：

• webflow library bundle - テスト用にローカルでバンドルします
• webflow library share - バンドルしてワークスペースにデプロイします
• webflow library log - デバッグログを表示します

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

認証： 初回の webflow library share 実行時に自動で行われます（ブラウザーが開きます）

環境： .env 内の WEBFLOW_WORKSPACE_ID と WEBFLOW_WORKSPACE_API_TOKEN

確認： まず webflow --version を必ず確認します

プレビュー： 共有前にバンドルの詳細を表示します

確認： 続行するには「share」というキーワードが必要です

ドキュメント： https://developers.webflow.com/code-components/introduction