Agent Skill · Webflow

webflow-cli:designer-extension

Build Designer Extensions for custom Webflow Designer functionality. Lists available templates, initializes extension projects from templates (default/react/typescript-alt), bundles extensions for upload, and serves locally for development.

View SKILL.md on GitHub → Source repository Provider profile

Provider: Webflow Path in repo: plugins/webflow-skills/skills/designer-extension-command/SKILL.md

Skill body

Designer Extension

Create and develop Designer Extensions for Webflow with template selection, local development server, and bundling for distribution.

Important Note

ALWAYS use Bash tool for all Webflow CLI operations:

Execute webflow extension commands via Bash tool
Use Read tool to examine generated files and schema (never modify)
Use Glob tool to discover project files
Verify CLI installation: webflow --version
Check authentication: webflow auth login (if needed)
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 --version to confirm CLI is installed
Check project state: Check if already in an extension project (look for webflow.json with extension schema)
Identify operation type: Determine if user wants to:
- List available templates
- Initialize new extension
- Bundle existing extension
- Serve extension locally

Phase 2: Template Listing & Selection

List templates (if user asks or before init): Run webflow extension list
Show available templates:
- default - Basic HTML/CSS/JavaScript template
- react - React-based template
- typescript-alt - Alternative TypeScript template
Ask user to select template if initializing new extension

Phase 3: Extension Initialization

Choose project name: Ask user for project directory name
Run init command: Execute webflow extension init <project-name> <template>
Read generated schema: Use Read tool to examine webflow.json
Show schema structure: Display the 5 schema fields:
- name (required) - Extension name as it appears in Webflow
- apiVersion (required) - API version (2)
- publicDir (required) - Directory to build from (dist)
- appIntents (optional) - Element types that can create connections
- appConnections (optional) - Connection configurations
Install dependencies: Run npm install in project directory

Phase 4: Local Development

Start dev server: Execute webflow extension serve [port]
Show dev server info:
- Default port: 1337 (unless user specifies different port)
- Local URL: http://localhost:[port]
- How to load in Designer
Provide loading instructions:
- Open Webflow Designer
- Load extension from local URL
- Test functionality

Phase 5: Bundling for Upload

Run bundle command: Execute webflow extension bundle
Show bundle output: Display bundle.zip location and size
Provide upload instructions: Guide for uploading to Webflow
Document next steps: Testing and distribution guidance

Examples

Example 1: List Available Templates

User prompt:

Show me the available Designer Extension templates

Response:

🔍 Designer Extension Templates

Listing available templates...
Executing: webflow extension list

Output:
Available templates:
1. default        - Basic HTML, CSS, and JavaScript
2. react          - React-based extension
3. typescript-alt - Alternative TypeScript template

To create a new extension:
webflow extension init <project-name> <template>

Example:
webflow extension init my-extension react

Example 2: Initialize New Extension

User prompt:

Create a new Designer Extension called gallery-manager using React

Step 1: Initialize Project

📋 Initialize Designer Extension

Project name: gallery-manager
Template: react

Executing: webflow extension init gallery-manager react

Output:
✓ Created extension project at ./gallery-manager
✓ Generated project structure
✓ Created webflow.json with extension schema
✓ Set up React template

📁 Project Structure:
./gallery-manager/
├── webflow.json         # Extension schema
├── package.json         # Dependencies
├── src/
│   ├── index.html
│   ├── index.tsx
│   └── styles.css
├── dist/                # Build output
└── README.md

Installing dependencies...
Executing: cd gallery-manager && npm install

✓ Dependencies installed (45 packages)

Step 2: Show Schema

📋 Extension Schema (webflow.json)

Reading webflow.json...

{
  "name": "Gallery Manager",
  "apiVersion": "2",
  "publicDir": "dist",
  "appIntents": {},
  "appConnections": []
}

Schema Fields:
✓ name (required)      - Extension name in Webflow
✓ apiVersion (required) - API version: 2
✓ publicDir (required)  - Build directory: dist
  appIntents (optional) - Element connection types
  appConnections (optional) - Connection configs

Extension ready for development!

Example 3: Serve Extension Locally

User prompt:

Run the extension on my local dev server

Default Port (1337):

🚀 Starting Development Server

Executing: webflow extension serve

Output:
✓ Building extension
✓ Starting dev server
✓ Extension ready

📋 Development Server Running

Local URL: http://localhost:1337
Status: ✓ Active

How to Load in Designer:
1. Open Webflow Designer
2. Open any site
3. Load extension from URL: http://localhost:1337

Press Ctrl+C to stop server

Custom Port:

User: "Run on port 3000 instead"

🚀 Starting Development Server

Executing: webflow extension serve 3000

Output:
✓ Building extension
✓ Starting dev server on port 3000
✓ Extension ready

📋 Development Server Running

Local URL: http://localhost:3000
Status: ✓ Active

Load in Designer: http://localhost:3000

Example 4: Bundle Extension

User prompt:

Bundle my extension for upload

Step 1: Bundle

📦 Bundling Extension

Executing: webflow extension bundle

Output:
✓ Building production bundle
✓ Creating bundle.zip
✓ Bundle created successfully

Bundle Details:
- File: bundle.zip
- Location: ./dist/bundle.zip
- Size: 245 KB

✅ Bundle ready for upload!

Step 2: Upload Instructions

📤 Upload Instructions

Your extension is bundled and ready to upload.

Upload Steps:
1. Go to Webflow Designer Extensions dashboard
2. Upload bundle.zip
3. Test the extension
4. Submit for review (if distributing)

Bundle location: ./dist/bundle.zip

Example 5: Complete Workflow

User prompt:

Create a new Designer Extension for managing colors

Step 1: List Templates

🔍 Designer Extension Workflow

First, let me show available templates.

Executing: webflow extension list

Available templates:
1. default        - Basic HTML/CSS/JavaScript
2. react          - React-based (recommended)
3. typescript-alt - TypeScript alternative

Which template would you like to use? (default/react/typescript-alt)

User selects: react

Step 2: Initialize

📋 Creating Extension

Project name: color-manager
Template: react

Executing: webflow extension init color-manager react

✓ Project created at ./color-manager
✓ webflow.json generated
✓ React template configured

Installing dependencies...
✓ npm install complete

📋 Extension Schema:
{
  "name": "Color Manager",
  "apiVersion": "2",
  "publicDir": "dist",
  "appIntents": {},
  "appConnections": []
}

Step 3: Start Development

🚀 Starting Dev Server

Executing: webflow extension serve

✓ Server running at http://localhost:1337

Load in Designer:
1. Open Webflow Designer
2. Load extension from: http://localhost:1337
3. Start developing!

Server running... (Press Ctrl+C to stop)

Guidelines

Phase 1: CLI Verification

Installation Check:

# Check if CLI is installed
webflow --version

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

Authentication (if needed):

# Site authentication if required
webflow auth login

Phase 2: Template Management

List Templates Command:

webflow extension list

Available Templates:

default - Basic HTML, CSS, and JavaScript template
react - React-based extension with modern tooling
typescript-alt - Alternative TypeScript template

Phase 3: Initialization

Init Command:

webflow extension init <project-name> <template>

Arguments:

<project-name> (required) - Name of the new project directory
<template> (required) - One of: default, react, typescript-alt

Example Commands:

# Initialize with default template
webflow extension init my-extension default

# Initialize with React template
webflow extension init my-extension react

# Initialize with TypeScript template
webflow extension init my-extension typescript-alt

Project Structure After Init:

/project-name/
├── webflow.json         # Extension schema (required)
├── package.json         # Dependencies
├── src/                 # Source files
│   ├── index.html
│   ├── index.tsx (or .js)
│   └── styles.css
├── dist/                # Build output directory
└── README.md

Phase 4: Extension Schema

Schema in webflow.json:

{
  "name": "<Your Extension Name>",
  "apiVersion": "2",
  "publicDir": "dist",
  "appIntents": {
    "image": ["manage"],
    "form": ["manage"]
  },
  "appConnections": [
    "myAppImageConnection",
    "myAppFormConnection"
  ]
}

Schema Fields:

Field	Description	Default	Required
`name`	Extension name as it appears in Webflow	-	Yes
`apiVersion`	API version to use for extension	`2`	Yes
`publicDir`	Directory to build and serve extension from	`dist`	Yes
`appIntents`	Element types that can create connections	`{}`	No
`appConnections`	Connection configurations for extension	`[]`	No

Required Fields:

name - Must be unique and descriptive
apiVersion - Currently must be “2”
publicDir - Directory where built files are placed (default: “dist”)

Optional Fields:

appIntents - Defines which element types can connect to your extension
- Example: {"image": ["manage"], "form": ["manage"]}
appConnections - Array of connection identifiers
- Example: ["myAppImageConnection", "myAppFormConnection"]

Phase 5: Local Development

Serve Command:

# Serve on default port (1337)
webflow extension serve

# Serve on custom port
webflow extension serve 3000

Arguments:

[port] (optional) - Port number to serve on (default: 1337)

Development Server:

Default URL: http://localhost:1337
Custom port: http://localhost:[port]
Auto-rebuilds on file changes
Hot reload for faster development

Loading in Designer:

Open Webflow Designer
Open any site
Go to Extensions menu
Load extension from local URL: http://localhost:[port]
Extension appears in Designer

Phase 6: Bundling

Bundle Command:

webflow extension bundle

Output:

Creates bundle.zip file in project directory
Contains all built files from publicDir
Ready to upload to Webflow

Bundle Contents:

Built JavaScript and CSS files
HTML entry points
Assets from publicDir
Extension schema

Error Handling

CLI Not Installed:

❌ Webflow CLI Not Found

Designer Extensions require the Webflow CLI.

Installation:
npm install -g @webflow/cli

After installation, verify:
webflow --version

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

Invalid Template:

❌ Invalid Template

Error: Template "vue" not found

Available templates:
- default
- react
- typescript-alt

Retry with valid template:
webflow extension init my-extension react

Port Already in Use:

❌ Development Server Failed to Start

Error: Port 1337 is already in use

Solutions:
1. Stop other process on port 1337
2. Use different port:
   webflow extension serve 3000

Find process using port:
lsof -ti:1337 | xargs kill -9

Missing webflow.json:

❌ Extension Schema Not Found

Error: webflow.json not found in current directory

This directory is not an extension project.

Solutions:
1. Initialize new extension:
   webflow extension init <name> <template>
2. Navigate to existing extension directory
3. Create webflow.json with required schema

Bundle Failed:

❌ Bundle Creation Failed

Error: Build failed with errors

Common Causes:
- Missing dependencies (run: npm install)
- Build errors in source files
- Invalid webflow.json schema
- Missing publicDir directory

Fix errors and retry:
webflow extension bundle

File Operations

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

# View extension schema
Read: webflow.json

# View package dependencies
Read: package.json

# View source files
Read: src/index.html
Read: src/index.tsx

Discovering Project Files: Use Glob tool to find files:

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

# Find configuration files
Glob: *.json

# Find built files
Glob: dist/**/*

Never Use Write/Edit Tools:

Don’t create or modify webflow.json with Write tool
Don’t edit generated files
Let CLI generate all project files
Only read files to show content

Progress Indicators

For Init:

📋 Creating Extension...

[████████████████████████] 100%

✓ Project created
✓ Dependencies installed
Elapsed: 12s

For Bundle:

📦 Bundling Extension...

[████████████████████████] 100%

✓ Bundle created: bundle.zip
Elapsed: 5s

For Serve:

🚀 Starting Server...

[████████████████████████] 100%

✓ Server ready at http://localhost:1337
Elapsed: 3s

Best Practices

Template Selection:

Use react template for modern component-based development
Use default template for simple extensions or learning
Use typescript-alt for TypeScript-based projects

Development Workflow:

List available templates
Initialize project with chosen template
Install dependencies
Serve locally for development
Test in Designer
Bundle for upload
Upload to Webflow

Schema Configuration:

Always include required fields: name, apiVersion, publicDir
Set appropriate appIntents if your extension connects to elements
Define appConnections for element integrations
Keep name descriptive and unique

Local Development:

Use default port 1337 for consistency
Keep dev server running during development
Test frequently in Designer
Check console for errors

Bundling:

Bundle only when ready for upload or distribution
Verify build completes without errors
Check bundle.zip size
Test bundled version before uploading

Quick Reference

Workflow: list templates → init → serve → develop → bundle → upload

Key Commands:

webflow extension list - Show available templates
webflow extension init <project-name> <template> - Create new extension
webflow extension serve [port] - Start dev server (default: 1337)
webflow extension bundle - Create bundle.zip for upload

Templates: default, react, typescript-alt

Schema Fields (webflow.json):

name (required) - Extension name
apiVersion (required) - API version (2)
publicDir (required) - Build directory
appIntents (optional) - Element connection types
appConnections (optional) - Connection configs

Dev Server: http://localhost:1337 (or custom port)

Bundle Output: bundle.zip in project directory

Documentation: https://developers.webflow.com/designer/reference/introduction