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

Why This is a Game Changer

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

Prerequisites

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.

Installation

One command installs everything:

npm install -g webflow-dev-bridge

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

First Time Setup

Navigate to your project folder and run the setup wizard:

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!

Running the System

Start everything with one command:

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.

Launch in Webflow

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

💻 Using the Tool

Your First Script

Let's test that everything works!

1. List available scripts:

   wf-bridge list

   This shows all scripts in your scripts/ folder with their exact paths.

2. Run a script:

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

Run Scripts from Terminal

Once everything is working, you can run any script:

# 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)

Finding Your Scripts

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

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

Use the Extension UI

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:

   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:

Setting Up a New Project

# 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")

Running Your Scripts

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

Finding and Running Scripts

# See all available scripts
wf-bridge list

# Run any script using the path shown
wf-bridge run scripts/helpers/rename-component.js

Managing Styles

• Create bulk style operations
• Organize CSS classes programmatically
• Maintain consistent naming

🏗️ How It Works

Architecture Overview

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 │
                                                   └──────────────┘

Component Breakdown

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

Script Execution Flow

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

Security & Validation

• 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

Script Structure

Scripts are standard JavaScript files that run in the Webflow Designer context:

// 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("==========================================");

Available APIs

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

Best Practices

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

First Things to Check

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

"Bridge Disconnected"

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

"Webflow API not available"

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

Scripts not loading

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

Scripts hanging or not completing

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

Terminal shows connection errors

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

Script path issues

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

Still Stuck?

• 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

Repository Structure

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

Your Project Structure (after wf-bridge setup)

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

Environment Variables

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:

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:

Webflow Designer API

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.

Client-First Methodology

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.

Technical Architecture

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

Commands

# 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

Workflow

1. Setup (one time per project):

   cd /path/to/your/project
   wf-bridge setup

2. Start working:

   wf-bridge serve
   # Keep this running, then launch extension in Webflow

3. Create and run scripts:

   # Add scripts to scripts/ folder
   # Then run them
   wf-bridge run scripts/my-script.js

🧪 Testing

Run the test suite:

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.