Webflow Dev Bridge - Code Directly in Webflow from Your Terminal

Vibe 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.

🎯 What This Does

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.

💡 Why This Exists

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

$3

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

🔗 What This Enables You To Do

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!

🚀 Quick Start

$3

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.

$3

One command installs everything:

``bash
npm install -g webflow-dev-bridge
`

That's it! No complex setup, no multiple npm installs, no build steps. 🎉

$3

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/)
- ✅ Generate a configured .env file
- ✅ Create a sample hello-world.js script
- ✅ Update your .gitignore 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!
`

$3

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.
`

$3

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

!Webflow Designer Test Panel

The extension panel showing script execution with real-time console output

💻 Using the Tool

$3

Let's test that everything works!

1. List available scripts:
`bash
wf-bridge list
`

This shows all scripts in your scripts/ 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.

$3

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)

$3

Not sure what scripts you have? Use the list command:

`bash
wf-bridge list
`

This shows:
- All available scripts in scripts/ folder
- All available scripts in wf-bridge/scripts/ (if you're using project-level install)
- The exact path to use with wf-bridge run

$3

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.

💡 Simple Example: Running a Script

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.

🔄 Common Workflows

Here are some common tasks you can do with this tool:

$3

`bash


1. Navigate to your project folder

cd /path/to/your/project

2. Initialize project structure

wf-bridge setup

3. Start the server

wf-bridge serve

4. In Webflow Designer, launch the extension (press "E")

`

$3

`bash

1. Create your script file

touch my-script.js

2. 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 list

Run 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 Webflow

2. 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 bridge

Solutions:
- ✅ 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 setup

Start everything (dev bridge + extension)

wf-bridge serve

Start only dev bridge

wf-bridge start

List all available scripts

wf-bridge list

Run a script

wf-bridge run scripts/my-script.js

Show 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`
4. Restart servers

📄 License

MIT

🙏 Acknowledgments

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.