Connect your code editor to Webflow Designer - Execute scripts, stream console output, and bridge your development workflow with Webflow's Designer API
npm install webflow-dev-bridgeVibe code in Webflow - Write and execute Webflow Designer API scripts directly from your code editor, with real-time results streaming to your terminal.
No more copy-pasting code into the Webflow Designer console. Edit in your favorite editor (Cursor, VS Code, etc.), run from terminal, and see results instantly in Webflow.


> ๐ This is a bridge/connection tool only - It doesn't include templates, components, or pre-built functionality. You write your own scripts to interact with the Webflow Designer API however you want.
This tool connects your code editor to Webflow Designer, letting you:
- โ๏ธ Write scripts in your favorite editor
- ๐ Run them from your terminal
- ๐ See results instantly in Webflow Designer
- ๐ Get responses directly in your terminal (no switching between apps!)
- ๐ Auto-reload when you save changes
Think of it as coding directly in Webflow, but from the comfort of your terminal.
The Webflow Designer API is a powerful way to programmatically work inside Webflow. You can build and manage your projects the same way you would in the Designer, but through code.
However, unlike the Webflow Data API (which uses REST endpoints), the Designer API only works through extensions that run directly inside Webflow. You can experiment with Webflow's built-in API Playground, but it's quite limited:
The Problem:
- โ Write scripts directly in the extension (lots of copy-pasting)
- โ Manually copy logs back to your code editor
- โ Inefficient loop: write โ paste โ run โ copy logs โ paste โ fix โ repeat
- โ Especially painful when working with AI agents
The Solution:
Instead of writing scripts in your editor and pasting them into the Designer API Playground, you can:
- โ
Write scripts in Cursor (or any editor)
- โ
Run them directly from your terminal
- โ
Get responses back in your terminal automatically
- โ
Use those responses as context for AI agents to improve scripts
This creates a seamless feedback loop: Write โ Run โ Get Response โ Improve โ Repeat
Speed up your workflow:
- No more switching between Webflow's API playground and your code editor
- See script results and errors directly in your terminal
- Fix issues immediately without context switching
- Iterate faster with instant feedback
Perfect for AI Agents:
- Prompt AI to create a section โ Run script โ Get response
- Success? Store the script for reuse later
- Failure? Get exact error logs that the AI can use to improve the script
- The terminal response becomes context that the agent can use immediately
- This feedback loop makes AI-assisted development incredibly powerful
This tool is a bridge - it connects your IDE to Webflow Designer. What you build with it is entirely up to you.
The bridge enables you to:
- Write scripts in your preferred editor with full syntax highlighting, autocomplete, and version control
- Execute them directly in Webflow Designer through a simple terminal command
- Get responses back in your terminal for debugging and iteration
- Automate workflows that would be tedious to do manually in the Designer
Note: This tool doesn't include any templates, components, or pre-built functionality - it's purely a connection layer. You write the scripts that interact with the Webflow Designer API to do whatever you need.
๐ Want to see what's possible? Check out example scripts and use cases to get inspired!
Make sure you have:
- [ ] Node.js (v18 or higher) - Download here
- [ ] Webflow account with Designer access (you need to be able to open sites in Designer)
- [ ] Webflow CLI installed: npm install -g @webflow/webflow-cli
- [ ] A Webflow site to work with (open it in Designer)
What is Designer access? You need to be able to open your Webflow site in the Designer (not just view the published site). If you can edit a site in Webflow, you have Designer access.
One command installs everything:
``bash`
npm install -g webflow-dev-bridge
That's it! No complex setup, no multiple npm installs, no build steps. ๐
Navigate to your project folder and run the setup wizard:
`bash`
cd /path/to/your/project
wf-bridge setup
The interactive setup wizard will:
- โ
Ask about your preferred folder structure
- โ
Check for available ports (with automatic alternatives)
- โ
Create your project directories (scripts/, input/, output/).env
- โ
Generate a configured filehello-world.js
- โ
Create a sample script.gitignore
- โ
Update your with recommended entries
Example setup:
`
๐ฏ Webflow Dev Bridge Setup Wizard
Welcome! This wizard will help you configure Webflow Dev Bridge.
๐ Let's configure your project settings:
? Where do you want to store your Webflow scripts? โบ ./scripts
? Where should input files be stored? โบ ./input
? Where should script outputs be saved? โบ ./output
๐ Port Configuration:
? HTTP server port for the dev bridge: โบ 3001
? WebSocket server port: โบ 8080
? Enable automatic reload when script files change? โบ Yes
? Enable debug logging for troubleshooting? โบ No
โ
Created .env file
โ
Created project structure
โ
Setup complete!
`
Start everything with one command:
`bash`
wf-bridge serve
This command:
- โ
Loads your .env configuration
- โ
Starts the dev bridge server (HTTP + WebSocket)
- โ
Starts the Webflow extension server
- โ
Watches your scripts folder for changes
- โ
Auto-reloads when you save scripts
First run without setup? No problem! Webflow Dev Bridge will detect this and guide you:
`
๐ฏ Welcome to Webflow Dev Bridge!
It looks like this is your first time using Webflow Dev Bridge in this project.
Let's get you set up with a quick configuration wizard.
Run: wf-bridge setup to get started.
`
1. Open your Webflow site in Designer (not published site)
2. Press "E" to open extensions
3. Find "API Playground" in the extensions list (this is your custom extension)
4. Click "Launch Development App" (NOT "Launch App")
5. You should see:
- โ
Bridge Connected (green indicator)
- โ
Webflow API Available (green checkmark)
- Script dropdown populated with your scripts
The extension panel showing script execution with real-time console output
Let's test that everything works!
1. List available scripts:
`bash`
wf-bridge list
scripts/
This shows all scripts in your folder with their exact paths.
2. Run a script:
`bash`
# Use the exact path from wf-bridge list
wf-bridge run scripts/hello-world.js
# or just the filename if it's in the root of scripts/
wf-bridge run hello-world.js
What to expect:
- Script loads in the extension
- Executes automatically
- You'll see output in your terminal like:
``
๐ Running script: scripts/hello-world.js
๐ก Connecting to dev bridge...
โ
Connected to dev bridge
๐ Hello from Webflow Dev Bridge!
๐ Current page: Home
โ
Done!
If you see errors: Check the troubleshooting section below.
Once everything is working, you can run any script:
`bash`Examples - use paths from wf-bridge list
wf-bridge run scripts/create-hero-section.js
wf-bridge run scripts/helpers/rename-component.js
wf-bridge run scripts/my-custom-script.js
The script will:
1. Load in the Webflow extension
2. Execute automatically in Designer
3. Stream console output to your terminal in real-time
4. Complete immediately when done (success or error)
Not sure what scripts you have? Use the list command:
`bash`
wf-bridge list
This shows:
- All available scripts in scripts/ folderwf-bridge/scripts/
- All available scripts in (if you're using project-level install)wf-bridge run
- The exact path to use with
You can also run scripts directly in Webflow:
1. Select a script from the dropdown
2. Edit the code if needed (in the code editor)
3. Click "Run" or press Cmd+Enter
4. View logs in the Console Output panel
The extension auto-reloads when you save script files.
Here's the basic workflow:
1. Write a script in your preferred editor (VS Code, Cursor, etc.)
2. Save it in your project (e.g., my-script.js)`
3. Run it from terminal:
bash`
wf-bridge run my-script.js
4. See results in both your terminal and Webflow Designer
What your script does is entirely up to you - it could create elements, modify styles, update content, or anything else the Webflow Designer API supports.
The key advantage: You get immediate feedback in your terminal. Errors, console logs, and results appear right where you're working - no need to check the Webflow console or switch between tools.
Here are some common tasks you can do with this tool:
`bash1. Navigate to your project folder
cd /path/to/your/project
$3
`bash
1. Create your script file
touch my-script.js2. Write your script (in your preferred editor)
3. Run it through the bridge
wf-bridge run my-script.js
`What your script does depends entirely on what you code - the bridge just executes it in Webflow Designer and returns the results.
$3
`bash
See all available scripts
wf-bridge listRun any script using the path shown
wf-bridge run scripts/helpers/rename-component.js
`$3
- Create bulk style operations
- Organize CSS classes programmatically
- Maintain consistent naming๐๏ธ How It Works
$3
Webflow Dev Bridge uses a three-tier architecture to connect your code editor to Webflow Designer:
`
โโโโโโโโโโโโโโโ โโโโโโโโโโโโโโโโ โโโโโโโโโโโโโโโโโโโ
โ Your โโโโโโโโโโบโ Dev Bridge โโโโโโโโโโบโ Webflow โ
โ Terminal โWebSocketโ Server โWebSocketโ Extension โ
โ โ โ โ โ โ
โโโโโโโโโโโโโโโ โโโโโโโโโโโโโโโโ โโโโโโโโโโโโโโโโโโโ
โ โ โ
โ โ โผ
โผ โผ โโโโโโโโโโโโโโโโ
wf-bridge run HTTP API :3001 โ Webflow โ
script.js WS Port :8080 โ Designer API โ
โโโโโโโโโโโโโโโโ
`$3
1. Terminal Client (
wf-bridge run)
- Initiates script execution from your terminal
- Connects to Dev Bridge via WebSocket
- Captures and saves JSON output automatically
- Shows real-time console logs from Webflow2. Dev Bridge Server (Port 3001 & 8080)
- HTTP API serves script files to the extension
- WebSocket server handles real-time communication
- Watches for file changes and triggers hot-reload
- Routes messages between terminal and extension
3. Webflow Extension
- Runs inside Webflow Designer
- Executes your scripts with full Designer API access
- Streams console output back to terminal
- Provides secure, sandboxed execution environment
$3
When you run
wf-bridge run my-script.js:1. Terminal client connects to WebSocket server
2. Sends execution command with script path
3. Dev Bridge forwards command to extension
4. Extension fetches script via HTTP API
5. Script executes in Webflow Designer context
6. Console output streams back through WebSocket
7. JSON output (if any) is automatically captured and saved
$3
- Only accepts connections from localhost
- Scripts run in isolated extension context
- Path validation prevents directory traversal
- No external network access from scripts
For deeper technical details, see Architecture Documentation.
๐ Writing Scripts
$3
Scripts are standard JavaScript files that run in the Webflow Designer context:
`javascript
// All Webflow Designer APIs are available globally
const site = await webflow.getSiteInfo();
console.log(Working with site: ${site.displayName});// Async/await is fully supported
const styles = await webflow.getAllStyles();
// Output JSON data for automatic capture
console.log("๐ Copy the JSON below to save:");
console.log("==========================================");
console.log(JSON.stringify(data, null, 2));
console.log("==========================================");
`$3
In your scripts, you have access to:
-
webflow - The main Designer API object
- All standard browser APIs (DOM, fetch, etc.)
- console.log() - Output appears in your terminal
- Top-level await - No need to wrap in async functions$3
1. Use descriptive logging: Help yourself understand what's happening
2. Handle errors gracefully: Use try-catch blocks
3. Output JSON consistently: Use the delimiter pattern for auto-capture
4. Keep scripts focused: One task per script
5. Comment your code: Especially for complex operations
๐ Troubleshooting
$3
If something isn't working, check these in order:
1. โ
Is
wf-bridge serve running? (or wf-bridge start if you're running extension separately)
2. โ
Is the extension showing "Bridge Connected" and "Webflow API Available"?
3. โ
Are you in Webflow Designer (not the published site)?
4. โ
Have you run wf-bridge setup in your project folder?
5. โ
Are your scripts in the scripts/ folder?
6. โ
Use wf-bridge list to see available scripts and their exact paths$3
Symptoms: Extension shows red "Bridge Disconnected" indicator
Solutions:
- โ
Check
wf-bridge serve is running
- โ
Verify it's listening on localhost:3001 and localhost:8080
- โ
Check browser console (F12) for WebSocket connection errors
- โ
Try restarting: wf-bridge serve
- โ
Ensure no firewall is blocking localhost connections$3
Symptoms: Extension shows "Webflow API not available"
Solutions:
- โ
Make sure
wf-bridge serve is running (it starts the extension server automatically)
- โ
Launch via "Launch Development App" (NOT "Launch App")
- โ
Ensure you're in Webflow Designer (not published site)
- โ
Refresh the extension or close and reopen it
- โ
Check that Webflow Designer is fully loaded$3
Symptoms: Script dropdown is empty or scripts fail to load
Solutions:
- โ
Run
wf-bridge list to see if scripts are detected
- โ
Ensure scripts are .js files in the scripts/ folder
- โ
Verify you're in the correct project directory (where you ran wf-bridge setup)
- โ
Check wf-bridge serve terminal for file watching errors
- โ
Try restarting: wf-bridge serve
- โ
Make sure you're using the correct path from wf-bridge list when running scripts$3
Symptoms: Script runs but doesn't finish, or waits for timeout
Solutions:
- โ
Update to latest version (v2.0.2+) - WebSocket connections now close properly after execution
- โ
Check terminal for error messages
- โ
Scripts should complete within seconds and show "โ
Execution complete"
- โ
Look for completion messages like "โ
Script executed successfully"
- โ
If still stuck, check the extension console for errors
$3
Symptoms:
wf-bridge run can't connect to dev bridgeSolutions:
- โ
Verify
wf-bridge serve is running
- โ
Check WebSocket server is on port 8080
- โ
Ensure extension is connected (should show "Bridge Connected")
- โ
Try restarting: wf-bridge serve
- โ
Make sure you're running wf-bridge run from the same project directory$3
Symptoms: Script not found or wrong path errors
Solutions:
- โ
Use
wf-bridge list to see all available scripts and their exact paths
- โ
Use the exact path shown in wf-bridge list when running scripts
- โ
Scripts should be in scripts/ folder at your project root
- โ
The path must be relative to project root (e.g., scripts/my-script.js)
- โ
If using wf-bridge/scripts/, use the full path: wf-bridge/scripts/my-script.js$3
- Check the browser console (F12) for detailed error messages
- Review the
wf-bridge serve terminal output for clues
- Make sure all prerequisites are installed correctly
- Try restarting: wf-bridge serve
- Use wf-bridge list to verify your scripts are detected๐ Project Structure
$3
`
webflow-dev-bridge/
โโโ webflow-port/ # Connects terminal to extension
โโโ webflow-extension/ # Webflow Designer extension
โโโ bin/ # CLI tools and executables
โ โโโ cli.js # Main CLI tool (wf-bridge command)
โ โโโ run-script.js # Script runner (used by CLI)
โ โโโ setup-wizard.js # Interactive setup wizard
โโโ tests/ # Integration tests
โโโ assets/ # Images and resources
โโโ docs/ # Documentation
โ โโโ architecture.md # Technical architecture documentation
โโโ README.md # This file
`$3
`
your-project/
โโโ scripts/ # Your Webflow scripts go here
โ โโโ hello-world.js # Sample script
โ โโโ my-script.js # Your custom scripts
โโโ input/ # Input files for scripts
โโโ output/ # Script outputs saved here
โโโ (other project files)
`Note: The
scripts/ folder is where you put all your Webflow API scripts. The system automatically detects and serves them.โ๏ธ Configuration
$3
You can customize the ports and script directory using environment variables:
| Variable | Default | Description |
|----------|---------|-------------|
|
WEBFLOW_SCRIPT_DIR | (set in config.js) | Directory containing your scripts |
| WEBFLOW_BRIDGE_PORT | 3001 | HTTP server port |
| WEBFLOW_WS_PORT | 8080 | WebSocket server port |Example:
`bash
WEBFLOW_BRIDGE_PORT=4000 WEBFLOW_WS_PORT=9000 npm run dev
`Or set them in your shell profile for persistence.
๐ Reference Documentation
When working with this tool, we use these resources as reference:
$3
We use the Webflow Designer API Reference for all API methods and capabilities. This is your go-to resource for understanding how to interact with Webflow programmatically.$3
When creating new components and sections, we follow Client-First documentation for naming conventions, structure, and best practices. This ensures consistency and maintainability across your projects.$3
For detailed technical information about how the system works internally, see Architecture Documentation. This covers the complete architecture, component breakdown, execution flow, and JSON capture mechanism.๐ฏ Next Steps
Now that you're set up, here's what to do next:
1. Try your first script - Run
wf-bridge run scripts/hello-world.js to test
2. List your scripts - Use wf-bridge list to see all available scripts
3. Explore the API - Check out the Webflow Designer API Reference
4. Learn the architecture - Read Architecture Documentation for technical details
5. Create your own scripts - Start with simple tasks and build up
6. Use with AI agents - Leverage the terminal feedback loop for AI-assisted development๐ Quick Reference
$3
`bash
Initialize project structure
wf-bridge setupStart everything (dev bridge + extension)
wf-bridge serveStart only dev bridge
wf-bridge startList all available scripts
wf-bridge listRun a script
wf-bridge run scripts/my-script.jsShow help
wf-bridge help
`$3
1. Setup (one time per project):
`bash
cd /path/to/your/project
wf-bridge setup
`2. Start working:
`bash
wf-bridge serve
# Keep this running, then launch extension in Webflow
`3. Create and run scripts:
`bash
# Add scripts to scripts/ folder
# Then run them
wf-bridge run scripts/my-script.js
`๐งช Testing
Run the test suite:
`bash
npm test
`Tests cover:
- Configuration with environment variables
- HTTP API endpoints
- WebSocket communication
- Security (directory traversal protection)
๐ค Contributing
This is a development tool. To contribute:
1. Make changes
2. Run tests:
npm test
3. Rebuild extension if needed: cd webflow-extension && npm run build`MIT
Built for the Webflow Designer API. Requires Webflow CLI for extension development.
---
Need help? Review the troubleshooting section above or check Architecture Documentation for technical details.