Webflow Designer Extension Development

Build extensions that run inside Webflow's Designer as iframes, interacting with the Designer API to manipulate elements, styles, pages, and more.

Quick Start Workflow

Prerequisite: Register your app in Webflow first — see references/register-app.md. You'll need a Workspace with Admin permissions.

1. Scaffold: npx create-webflow-extension@latest (interactive prompts for project name, package manager, linter)
2. Develop: cd <name> && pnpm dev (serves at localhost:1337; also works with npm/yarn/bun)
3. Test: Install app on test site via Workspace Settings > Apps & Integrations > Develop
4. Open: Press "E" in Designer to open app panel, launch extension
5. Build: pnpm build for deployment

CLI Options

npx create-webflow-extension@latest [project-name] [options]

Options:
  --pm <pnpm|npm|yarn|bun>           Package manager to use (default: pnpm)
  --linter <oxlint|biome|eslint>     Linter to use
  --skip-git                         Skip git initialization
  --skip-install                     Skip dependency installation
  --quiet                            Suppress output

Designer API

For all API methods, patterns, and code examples, refer to the reference documentation below. Start with the quick lookup reference for a complete overview:

• Designer APIs Reference — all webflow.* methods in one table
• Elements API — element selection, insertion, presets, and the element builder
• Styles API — creating styles, setting CSS properties, breakpoints, and pseudo-states
• Components API — component definitions, instances, and editing context
• Variables API — design token variables (colors, sizes, fonts, numbers, percentages)
• Error Handling — error structure, cause tags, and recovery patterns

Project Structure

Generated by create-webflow-extension (React 19 + TypeScript + Rspack):

my-extension/
├── public/
│   └── index.html        # Entry point
├── src/
│   ├── App.tsx           # Main React component
│   ├── main.tsx          # React entry point
│   └── index.css         # Styles
├── webflow.json          # Extension settings
├── rspack.config.ts      # Rspack bundler configuration
├── package.json
└── tsconfig.json

Reference Documentation

Each reference file includes YAML frontmatter with name, description, and tags for searchability. Use the search script to find relevant references quickly:

# List all references with metadata
python scripts/search_references.py --list

# Search by tag (exact match)
python scripts/search_references.py --tag <tag>

# Search by keyword (across name, description, tags, and content)
python scripts/search_references.py --search <query>

CLI & Tooling

• references/create-webflow-extension-reference.md: create-webflow-extension scaffolding CLI
• references/webflow-cli-reference.md: Webflow CLI for serving, bundling, and listing extensions

Designer API (detailed guides)

• references/designer-apis-reference.md: All APIs and methods in one place (start here)
• references/elements-api.md: Element manipulation and presets
• references/styles-api.md: Styling, breakpoints, pseudo-states
• references/components-api.md: Component definitions and instances
• references/pages-api.md: Page and folder management
• references/variables-api.md: Design token variables and collections
• references/assets-api.md: Asset upload and management
• references/extension-utilities.md: Site info, events, notifications, app discovery, authentication
• references/error-handling.md: Error structure, cause tags, and recovery patterns
• references/code-examples.md: Cross-API workflow examples combining multiple APIs

Design & Marketplace

• references/design-guidelines.md: UI design for native Webflow look
• references/register-app.md: Registering a Webflow App and configuring capabilities
• references/marketplace-guidelines.md: Marketplace review criteria (safety, technical, design, branding)
• references/app-submission-and-listing.md: Submitting your app and creating an effective listing
• references/faq.md: FAQ and troubleshooting for extensions, marketplace, and common issues

Scripts

• scripts/validate-extension.py: Validate extension structure before bundling
• scripts/search_references.py: Search reference files by tag, keyword, or list all with metadata

Assets

• assets/webflow-variables.css: CSS variables for Webflow's design system colors, typography, and shadows

Best Practices

1. Check element capabilities: Always verify element.children before append/prepend, element.textContent before text operations
2. Handle errors gracefully: Use try/catch with webflow.notify() for user feedback — see Error Handling
3. Responsive design: Test on multiple breakpoints when setting styles — see Styles API
4. Use variables: Leverage design token variables for consistent theming — see Variables API
5. Subscribe to events: Use Designer events to keep extension state in sync — see Extension Utilities
6. Appropriate sizing: Use webflow.setExtensionSize() for proper panel dimensions — see Extension Utilities