webflow-designer-extension

name	webflow-designer-extension
description	Build Webflow Designer Extensions that run inside the Webflow Designer. Use when creating, debugging, or modifying Designer Extensions (iframes that interact with Webflow's Designer API). Covers CLI usage, element manipulation, styles, components, pages, variables, assets, error handling, and UI design patterns for Webflow's design system.
license	MIT
compatibility	create-webflow-extension, @webflow/webflow-cli
metadata	{"author":"[Ben Sabic](https://bensabic.dev)","version":"1.1.0"}

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 (default: oxlint)
  --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

• 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/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