Skill v1.0.1
currentAutomated scan100/1003 files
version: "1.0.1" name: webflow-cli:code-component description: Create and deploy reusable React components for Webflow Designer. Configure existing React projects with webflow.json, build and bundle code, validate output, and deploy to workspace using library share. Use when building custom components for designers.
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
webflowCLI 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
- Verify CLI installed: Run
webflow --versionto confirm CLI is installed - Check project state: Determine if user has existing React project or needs guidance
- Identify workspace: Explain that workspace authentication happens on first share
- Review configuration: Check if webflow.json exists with library configuration
Phase 2: Project Configuration
- 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
- 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
- Read configuration files: Use Read tool to show:
webflow.json- Library configurationpackage.json- Dependencies and scripts- Component file structure
- Verify dependencies: Ensure React is installed and build scripts exist
Phase 3: Build & Bundle Validation
- Run build: Execute user's build command (e.g.,
npm run build,yarn build) - Validate build output: Check for build errors or warnings
- Run bundle command: Execute
webflow library bundlefor local validation - Analyze bundle:
- Bundle size (should be < 2MB)
- Dependencies included
- Output location (default:
./dist) - Validation warnings
- Preview bundle details: Show bundle summary with validation status
Phase 4: Preview & Approval
- Show deployment preview:
- Library name from webflow.json
- Component files included
- Bundle size and validation status
- Target workspace (will be selected on first share)
- Explain workspace authentication if first time
- Explain deployment: What happens when library is shared
- Require explicit confirmation: User must type "share" or "deploy" to proceed
- Confirm workspace: Explain browser will open for workspace selection (first time only)
Phase 5: Deployment & Verification
- Execute share command: Run
webflow library share - Monitor deployment: Show CLI output and progress
- Handle workspace auth: If first time, guide user through browser authentication
- Verify deployment success: Confirm library appears in workspace
- Show .env updates: Explain WEBFLOW_WORKSPACE_ID and WEBFLOW_WORKSPACE_API_TOKEN added
- Provide next steps:
- How to use components in Designer
- How to update components
- Testing recommendations
- Using
webflow library logfor debugging
Examples
Example 1: Configure Existing React Project
User prompt:
I have a React project with some components I want to share to Webflow
Step 1: Environment Verification
🔍 Webflow CLI Environment CheckChecking CLI installation...✓ Webflow CLI installed: v1.5.2Current directory: /Users/user/projects/my-components✓ Found package.json with React project✓ Found src/ directory with componentsChecking webflow.json...⚠️ No webflow.json found - needs configurationReady to configure for Code Components? (yes/no)
User confirms: yes
Step 2: Project Configuration
📋 Configure Code Components LibraryI'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.
*User provides: "Acme Components" and "./src/**/.webflow.tsx"
Creating webflow.json configuration...{"library": {"name": "Acme Components","components": ["./src/**/*.webflow.tsx"]}}✓ Configuration readyFound component files:- src/Button.webflow.tsx- src/Card.webflow.tsx- src/Hero.webflow.tsxNext: Build your components and run bundle command.
Step 3: Build & Bundle Validation
🔨 Building ComponentsWhat build command do you use? (e.g., npm run build, yarn build)
User responds: npm run build
Executing: npm run buildOutput:✓ TypeScript compilation successful✓ Components built to dist/Creating bundle for validation...Executing: webflow library bundleOutput:✓ 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: react@18.2.0, react-dom@18.2.0- Output: ./dist- Validation: ✅ All checks passed
Step 4: Preview & Approval
📋 Deployment PreviewLibrary: Acme ComponentsComponents: 3 (Button, Card, Hero)Bundle Size: 287 KBWorkspace Authentication:⚠️ This appears to be your first deployment. When you run 'share':1. Browser will open for workspace authentication2. Select your target Webflow workspace3. Grant access to deploy components4. CLI will create .env with credentials:- WEBFLOW_WORKSPACE_ID- WEBFLOW_WORKSPACE_API_TOKENValidation 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.
User confirms: share
Step 5: Deployment & Verification
🚀 Deploying LibraryExecuting: webflow library shareOutput:✓ 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 ComponentsWorkspace: Acme CorpComponents: 3 (Button, Card, Hero)Version: LatestStatus: 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 Designer2. Go to Add Elements → Code Components3. Find "Acme Components" in the list4. Drag components onto canvas to use💡 To update components:1. Make changes to your component files2. Run: npm run build3. 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 --verboseComponent Library URL: https://webflow.com/dashboard/workspaces/acme-corp/components
Example 2: Update Existing Library
User prompt:
Update my Code Components library with new changes
Step 1: Environment Verification
🔍 Code Components Library CheckChecking configuration...✓ webflow.json found with library config✓ Library name: Acme Components✓ Components pattern: ./src/**/*.webflow.tsxChecking authentication...✓ Found .env with workspace credentials✓ Workspace: Acme CorpFound 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)
Step 2-3: Build & Bundle
🔨 Building ComponentsExecuting: npm run build✓ Build completeBundling 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
Step 4: Preview
📋 Update PreviewLibrary: Acme ComponentsWorkspace: 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.
Step 5: Deployment
🚀 Updating LibraryExecuting: webflow library shareOutput:✓ Bundling library (312 KB)✓ Using workspace: Acme Corp✓ Uploading bundle✓ Validating components✓ Updating library✓ Library updated successfully✅ Library Updated: Acme ComponentsChanges deployed:- Button: Updated ✨- Form: Added 🆕- Card: Unchanged- Hero: Unchanged💡 Refresh Webflow Designer to see changes:1. Open Designer2. Components may auto-refresh3. Or refresh browser if neededComponents updated in workspace!
Example 3: First-Time Bundle Testing
User prompt:
I want to test my bundle locally before sharing
Step 1-2: Verification & Configuration
🔍 Local Bundle Testing✓ webflow.json configured✓ Library: My Components✓ Components: ./src/**/*.webflow.tsxRunning local bundle only (no deployment)...
Step 3: Bundle Validation
🔨 Building ComponentsExecuting: npm run build✓ Build completeCreating local bundle...Executing: webflow library bundleOutput:✓ 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:├── react@18.2.0 (included)├── react-dom@18.2.0 (included)└── classnames@2.3.1 (included)Output Directory: ./dist/- bundle.js (1.2 MB)- manifest.jsonValidation: ✅ All checks passed💡 Bundle is valid and ready to share!Run: webflow library share (when ready to deploy)
Example 4: Bundle Too Large
User prompt:
Share my components library
Bundle Validation Error:
🔨 Building and BundlingExecuting: npm run build✓ Build completeExecuting: webflow library bundleOutput:✓ Analyzing components✓ Bundling dependencies⚠️ Bundle size check...📦 Bundle Analysis:- Size: 2.4 MB (❌ exceeds 2MB limit)- Components: 6- Dependencies: react@18.2.0, react-dom@18.2.0, lodash@4.17.21, moment@2.29.4- Validation: ❌ Issues found❌ Bundle Too LargeCurrent size: 2.4 MBMaximum allowed: 2 MBExceeded 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 functions2. Replace moment with lighter alternative- Use date-fns (~15 KB vs 350 KB)- Or use native Intl.DateTimeFormat3. Optimize component code- Remove unused imports- Enable tree-shaking- Split large components4. Use external assets- Host large images externally- Use CDN for static assetsWould you like to:1. Continue anyway (using --force flag, not recommended)2. Review component imports to optimize3. Cancel and fix manually
Example 5: CI/CD Deployment
User prompt:
How do I deploy in CI/CD pipeline?
Response:
🤖 CI/CD Deployment SetupFor 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 securely2. **Add to CI/CD Secrets**- Add as environment variable: WORKSPACE_API_TOKEN- Never commit tokens to version control3. **Deployment Command**```bashwebflow library share --api-token $WORKSPACE_API_TOKEN --no-input```### Example: 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 }}
### Multiple Workspaces:
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
### Options:- `--no-input` - Disables interactive prompts- `--force` - Continues even with warnings- `--verbose` - Shows detailed output- `--dev` - Bundles in development mode (for testing)⚠️ Security:- Never commit .env files- Use secrets management in CI/CD- Rotate tokens regularly- Limit token permissions
Guidelines
Phase 1: CLI Verification
Installation Check:
# Check if CLI is installedwebflow --version# If not installed, guide user:npm install -g @webflow/webflow-cli
Project Check:
# Check for existing configurationls webflow.json# Check for React projectls package.json# Check for componentsls src/
Authentication Note: Unlike site authentication, workspace authentication for Code Components happens automatically on first webflow library share. The CLI will:
- Open browser for authentication
- Let user select workspace
- Create .env with WEBFLOW_WORKSPACE_ID and WEBFLOW_WORKSPACE_API_TOKEN
Phase 2: Project Configuration
webflow.json Structure:
{"library": {"name": "<Your Library Name>","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
.webflowbefore 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:
# Use project's build scriptnpm run build# oryarn build# orpnpm build# Check for errorsecho $? # 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 <path>- Override output directory (default:./dist)--public-path <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 < 2MB
- Dependencies: React versions compatible
- Output: Bundle created in dist/ directory
- Components: All component files included
Common Build Errors:
- TypeScript compilation errors → Fix type issues
- Missing dependencies → Run npm install
- Import errors → Check file paths
- Bundle too large → Optimize dependencies
Phase 4: Deployment Preview
Preview Format:
📋 Deployment PreviewLibrary: [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
First-Time Authentication: Explain clearly:
- Browser will open
- User authenticates with Webflow
- User selects target workspace
- CLI creates .env with credentials
- Future shares use these credentials (no re-auth)
Phase 5: Deployment Execution
Share Command:
# 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 modewebflow 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:
WEBFLOW_WORKSPACE_ID=your-workspace-idWEBFLOW_WORKSPACE_API_TOKEN=your-api-token
⚠️ Critical: Always add .env to .gitignore!
Verification Steps:
- Check CLI output for success message
- Verify .env file created (first time)
- Provide Designer access instructions
- Show workspace dashboard URL
Phase 6: Debugging
Log Command:
# Show latest log file locationwebflow 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 FoundThe CLI couldn't find webflow.json in the current directory.Solution:1. Ensure you're in the project root2. 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 FoundThe components glob pattern didn't match any files.Current pattern: "./src/**/*.webflow.tsx"Solution:1. Check component files have correct naming2. Verify glob pattern in webflow.json3. 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 FoundThe Webflow CLI is required for Code Components.Installation:npm install -g @webflow/webflow-cliAfter installation, verify:webflow --versionDocumentation: https://developers.webflow.com/cli
Build Failures:
❌ Build FailedError: [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 syntaxShow build output for details.Need help? Run: webflow library log
Bundle Failures:
❌ Bundle FailedError: [Specific error from CLI]Common Causes:- Invalid component files- Webpack configuration errors- Dependency conflicts- File path issuesView detailed logs: webflow library logPossible solutions:1. Check component file syntax2. Verify webflow.json configuration3. Remove bundleConfig to use defaults4. Check dependencies in package.json
Deployment Failures:
❌ Share FailedError: [Specific error from CLI]Possible Causes:- Network connection issues- Workspace authentication expired- Bundle validation failed- Workspace permissionsSolutions:1. Check internet connection2. Re-authenticate: Remove .env and run share again3. Fix bundle issues: Run webflow library bundle first4. Verify workspace access in Webflow dashboardRetry share? (yes/no)
File Operations
Reading Files: Always use Read tool (never modify):
# View library configurationRead: webflow.json# View package dependenciesRead: package.json# View component sourceRead: src/Button.webflow.tsx# View environment (if exists)Read: .env
Discovering Files: Use Glob tool to find files:
# Find all webflow componentsGlob: **/*.webflow.tsx# Find configuration filesGlob: *.json# Find source filesGlob: src/**/*# Find build outputGlob: 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 KBElapsed: 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 (< 1MB ideal)
- Name files with .webflow extension for clarity
- Document component props
Dependency Management:
- Keep dependencies minimal
- Avoid large libraries (lodash, moment)
- Use tree-shakeable packages
- Check bundle impact:
webflow library bundle --verbose - Peer dependencies for React (not bundled)
Updates and Versioning:
- Build before sharing
- Test bundle locally:
webflow library bundle - Share to update:
webflow library share - No version numbers needed (always "latest")
- Test in Designer after deployment
Workspace Management:
- One workspace per .env file
- Use --api-token for multiple workspaces
- Add .env to .gitignore
- Rotate tokens in CI/CD
- Document which workspace is configured
Configuration:
- Keep webflow.json in project root
- Use clear library names
- Use specific component glob patterns
- Add bundleConfig only if needed
- Version control webflow.json (not .env)
Component Lifecycle
Initial Setup:
- Create/have React project
- Add webflow.json with library configuration
- Name component files (e.g., .webflow.tsx)
- Build:
npm run build - Test bundle:
webflow library bundle - Share:
webflow library share(authenticates first time)
Making Updates:
- Edit component source files
- Build:
npm run build - Share:
webflow library share(uses saved credentials) - Refresh Designer to see changes
Testing:
- Bundle locally:
webflow library bundle - Check bundle size and validation
- Fix any issues
- Share when ready:
webflow library share - Open Webflow Designer
- Add components to page
- Test functionality
Debugging:
- View logs:
webflow library log - Bundle with verbose:
webflow library bundle --verbose - Check configuration: cat webflow.json
- Verify build: npm run build
- Test in development mode:
webflow library share --dev
CLI Command Reference
Installation:
# Install CLI globallynpm install -g @webflow/webflow-cli# Verify installationwebflow --version
Library Commands:
# Bundle locally (testing/validation)webflow library bundle [options]# Share to workspace (bundle + deploy)webflow library share [options]# View latest log filewebflow library log
Bundle Options:
# Custom output pathwebflow library bundle --output-path ./build# Force bundling (ignore warnings)webflow library bundle --force# Development modewebflow library bundle --dev# Show bundler configwebflow library bundle --debug-bundler# Verbose outputwebflow library bundle --verbose
Share Options:
# Standard interactive sharewebflow library share# Non-interactive (CI/CD)webflow library share --no-input --api-token <TOKEN># Force share (ignore warnings)webflow library share --force# Development modewebflow library share --dev# Custom manifest locationwebflow library share --manifest ./config/webflow.json
Global Options:
# Show versionwebflow --version# Show helpwebflow --helpwebflow library --helpwebflow library share --help
Quick Reference
Workflow: configure webflow.json → build → bundle → share
Key Commands:
webflow library bundle- Bundle locally for testingwebflow library share- Bundle and deploy to workspacewebflow library log- View debug logs
Configuration: webflow.json with library section
Authentication: Automatic on first webflow library share (opens browser)
Environment: WEBFLOW_WORKSPACE_ID and WEBFLOW_WORKSPACE_API_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