Webflow Cli:code Component

Code Component

Create, build, and deploy React components to Webflow Designer with comprehensive validation and deployment verification.

Important Note

ALWAYS use Bash tool for all Webflow CLI operations:

• Execute webflow CLI commands via Bash tool
• Use Read tool to examine generated files (never modify)
• Use Glob tool to discover project files
• Verify CLI installation: webflow --version
• Check authentication: On first webflow library share, workspace authentication happens automatically
• DO NOT use Webflow MCP tools for CLI workflows
• All CLI commands require proper descriptions (not context parameters)

Package Manager Detection:

• Check for lock files: package-lock.json (npm), pnpm-lock.yaml (pnpm), yarn.lock (yarn)
• If no lock file found, ask user which package manager to use (npm/pnpm/yarn)
• Use detected package manager for all install/build commands

Instructions

Phase 1: Environment Verification

1. Verify CLI installed: Run webflow --version to confirm CLI is installed
2. Check project state: Determine if user has existing React project or needs guidance
3. Identify workspace: Explain that workspace authentication happens on first share
4. Review configuration: Check if webflow.json exists with library configuration

Phase 2: Project Configuration

1. Ask operation type: Clarify what user wants to do:

• Configure existing React project for Code Components
• Add components to already-configured project
• Build and share existing library

1. Configure webflow.json: Add library configuration to webflow.json:

• Library name (appears in Webflow Designer)
• Components glob pattern (e.g., ./src/**/*.webflow.tsx)
• Optional bundleConfig for custom webpack

1. Read configuration files: Use Read tool to show:

• webflow.json - Library configuration
• package.json - Dependencies and scripts
• Component file structure

1. Verify dependencies: Ensure React is installed and build scripts exist

Phase 3: Build & Bundle Validation

1. Run build: Execute user's build command (e.g., npm run build, yarn build)
2. Validate build output: Check for build errors or warnings
3. Run bundle command: Execute webflow library bundle for local validation
4. Analyze bundle:

• Bundle size (should be ",

"components": ["./src/**/*.webflow.@(js|jsx|mjs|ts|tsx)"], "bundleConfig": "./webpack.webflow.js" } }

**Configuration Fields:**
- **name** (required): Library name as it appears in Webflow Designer
- **components** (required): Glob pattern matching component files
  - Example: `"./src/**/*.webflow.tsx"` - all .webflow.tsx files in src/
  - Example: `"./src/components/**/*.tsx"` - all .tsx files in src/components/
- **bundleConfig** (optional): Path to custom webpack configuration

**Component Naming Convention:**
- Add `.webflow` before extension: `Button.webflow.tsx`
- Or use glob pattern to include all files in specific directory
- Components must be React components

**No Init Command:**
Unlike other CLI products, Code Components don't have an `init` command. Users configure existing React projects by adding webflow.json with library configuration.

### Phase 3: Build & Bundle

**Build Process:**
```bash
# Use project's build script
npm run build
# or
yarn build
# or
pnpm build

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

Bundle Command:

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

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

Bundle Options:

• --output-path - Override output directory (default: ./dist)
• --public-path - Override public path
• --force - Force bundling even with warnings
• --debug-bundler - Show webpack configuration
• --dev - Bundle in development mode
• --verbose - Show detailed output

Bundle Validation: Check these aspects:

• Size limit: Must be --no-input

Force share (ignore warnings)

webflow library share --force

Development mode

webflow library share --dev

**Share Options:**
- `--manifest` - Path to webflow.json (default: scans current directory)
- `--api-token` - Workspace API token (for CI/CD)
- `--no-input` - Disable interactive prompts
- `--force` - Force bundling even with warnings
- `--debug-bundler` - Show bundler configuration
- `--dev` - Bundle in development mode
- `--verbose` - Show detailed output

**Success Indicators:**
- Bundle uploaded successfully
- Library registered in workspace
- Components available in Designer
- .env file created/updated (first time)

**Environment File (.env):**
After first successful share:

WEBFLOWWORKSPACEID=your-workspace-id WEBFLOWWORKSPACEAPI_TOKEN=your-api-token

⚠️ **Critical**: Always add .env to .gitignore!

**Verification Steps:**
1. Check CLI output for success message
2. Verify .env file created (first time)
3. Provide Designer access instructions
4. Show workspace dashboard URL

### Phase 6: Debugging

**Log Command:**
```bash
# Show latest log file location
webflow library log

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

Use this command when:

• Bundle fails with unclear error
• Share command produces warnings
• Need to debug webpack configuration
• Investigating dependency issues

Common Issues:

Issue: "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

Issue: "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

Error Handling

CLI Not Installed:

❌ 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 Failures:

❌ 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 Failures:

❌ 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

Deployment Failures:

❌ 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)

File Operations

Reading Files: Always use Read tool (never modify):

# 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

Discovering Files: Use Glob tool to find files:

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

# Find configuration files
Glob: *.json

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

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

Never Use Write/Edit Tools:

• Don't create webflow.json with Write (show user the structure)
• Don't modify component files
• Don't edit package.json
• Let user make file changes
• Only read files to show content

Progress Indicators

For Bundling:

🔄 Bundling Components...

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

Elapsed: 8s

For Deployment:

🚀 Sharing Library...

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

Uploaded: 287 KB
Elapsed: 12s

Safety Patterns

Confirmation Keywords:

• "share" - Share library to workspace
• "deploy" - Alternative to "share"
• "proceed" - Continue with operation
• "cancel" - Cancel operation
• "skip" - Skip optional step

Preview Before Share: Always show:

• What will be shared (library name, components)
• Where it will go (workspace, or first-time auth needed)
• Bundle size and validation status
• Impact of changes (new/updated components)

Transparency:

• Show all CLI commands before execution
• Display CLI output in full
• Report success/failure clearly
• Provide troubleshooting guidance
• Show log location for debugging

Best Practices

Component Development:

• Use TypeScript for type safety
• Follow React best practices
• Keep bundle size small (

Force share (ignore warnings)

webflow library share --force

Development mode

webflow library share --dev

Custom manifest location

webflow library share --manifest ./config/webflow.json

**Global Options:**
```bash
# Show version
webflow --version

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

Quick Reference

Workflow: configure webflow.json → build → bundle → share

Key Commands:

• webflow library bundle - Bundle locally for testing
• webflow library share - Bundle and deploy to workspace
• webflow library log - View debug logs

Configuration: webflow.json with library section

Authentication: Automatic on first webflow library share (opens browser)

Environment: WEBFLOWWORKSPACEID and WEBFLOWWORKSPACEAPI_TOKEN in .env

Verification: Always check webflow --version first

Preview: Show bundle details before sharing

Confirmation: Require "share" keyword to proceed

Documentation: https://developers.webflow.com/code-components/introduction

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: webflow
• Source: webflow/webflow-skills
• License: MIT

Install and usage instructions live in the source repository linked above.