DevLink

Export and sync Webflow Designer components to React/Next.js code with validation, diffs, and integration guidance.

Important Note

ALWAYS use Bash tool for all Webflow CLI operations:

Execute webflow devlink sync via Bash tool
Use Read tool to examine synced files and webflow.json (never modify)
Use Glob tool to discover generated components
Verify CLI installation: webflow --version
Check authentication: Use webflow auth login for site authentication
DO NOT use Webflow MCP tools for CLI workflows
All CLI commands require proper descriptions (not context parameters)

Package Manager Detection:

Check for lock files: package-lock.json (npm), pnpm-lock.yaml (pnpm), yarn.lock (yarn)
If no lock file found, ask user which package manager to use (npm/pnpm/yarn)
Use detected package manager for all install/build commands

Instructions

Phase 1: Environment Verification

Verify CLI installed: Run webflow --version to confirm CLI is installed
Check authentication: Verify site authentication (created via webflow auth login)
Discover project state: Check if webflow.json exists with devlink configuration
Identify target framework: Determine if React, Next.js, or other

Phase 2: DevLink Configuration

Check for existing config: Look for webflow.json with devlink section
Read configuration: If exists, show current devlink settings:
- rootDir: Directory to export components into
- cssModules: Whether to use CSS modules
- fileExtensions: File extensions for generated files
- Other configuration options
Ask operation type: Clarify what user wants to do:
- Configure DevLink for first time
- Sync all components
- Sync specific components (using components regex pattern)
- Update existing sync
Store baseline (if updating): Use Read tool to capture current files before sync

Phase 3: Sync Execution

Run sync command: Execute webflow devlink sync with options:
- --api-token or -t: Override API token from .env
- --site-id or -s: Override site ID from .env
Monitor sync progress: Show CLI output and sync status
Capture sync results: Record files created/modified in rootDir
Validate generated code:
- Check for TypeScript errors (if using TS)
- Verify import statements
- Confirm component exports
- Check CSS module references

Phase 4: Analysis & Diff Preview

Compare before/after: Show what changed:
- New files created in rootDir
- Existing files modified
- Components added or updated
Show file diffs: Display key changes for modified files
Analyze component structure:
- Component count
- New components added
- Updated components
- CSS files generated
List dependencies: Show what needs to be imported

Phase 5: Integration Guidance

Provide import statements: Show exact code to import components
Show usage examples: Demonstrate how to use each component
Document sync timestamp: Record when sync occurred
Provide next steps: Guide user on testing and integration

Examples

Example 1: First-Time DevLink Setup

User prompt:

Sync my Webflow components to my Next.js project

Step 1: Environment Verification

🔍 DevLink Environment Check

Checking CLI installation...
✓ Webflow CLI installed: v1.5.2

Current directory: /Users/user/projects/my-nextjs-app
Framework detected: Next.js 14

Checking for DevLink configuration...
⚠️ No webflow.json with devlink configuration found

This appears to be your first DevLink sync.
Ready to configure? (yes/no)

User confirms: yes

Step 2: Configuration Setup

📋 DevLink Configuration

DevLink syncs Webflow components to your local project as React code.

Configuration needed in webflow.json:

{
  "devlink": {
    "rootDir": "./devlink",           // Where to export components
    "cssModules": true,                // Use CSS modules
    "fileExtensions": {
      "js": "jsx"                      // or "tsx" for TypeScript
    }
  }
}

I'll help you create this configuration.

Questions:
1. Where should components be exported? (default: ./devlink)
2. Use TypeScript? (yes for tsx, no for jsx)
3. Use CSS modules? (recommended: yes)

User provides: ./src/devlink, yes (TypeScript), yes (CSS modules)

Creating webflow.json configuration...

{
  "devlink": {
    "rootDir": "./src/devlink",
    "cssModules": true,
    "fileExtensions": {
      "js": "tsx"
    }
  }
}

✓ Configuration created

⚠️ Authentication Required:
DevLink needs your Webflow site ID and API token.

Run: webflow auth login
This will create a .env file with:
- WEBFLOW_SITE_ID
- WEBFLOW_SITE_API_TOKEN

After authentication, run sync again.

Example 2: First Sync After Configuration

User prompt:

Run the DevLink sync

Step 1: Verification

🔍 DevLink Sync Check

Checking configuration...
✓ webflow.json found with devlink config
✓ Root directory: ./src/devlink
✓ CSS modules: enabled
✓ File extensions: tsx

Checking authentication...
✓ .env found with WEBFLOW_SITE_ID and WEBFLOW_SITE_API_TOKEN

Ready to sync components from Webflow.

Step 2: Sync Execution

🔄 Syncing Components

Executing: webflow devlink sync

Output:
✓ Connecting to Webflow site
✓ Fetching components
✓ Exporting components to ./src/devlink
✓ Generating React components
✓ Creating CSS module files
✓ Creating index file

Sync complete!

📁 Generated Files:
./src/devlink/
├── index.ts (module exports)
├── Navigation.tsx (component)
├── Navigation.module.css (styles)
├── Hero.tsx (component)
├── Hero.module.css (styles)
├── Footer.tsx (component)
├── Footer.module.css (styles)
└── _webflow-style.css (global styles)

📊 Sync Summary:
- Components synced: 3
- Files created: 8
- Total size: 45 KB

Step 3: Integration Guidance

✅ DevLink Sync Complete!

📋 Components Available:
1. Navigation
2. Hero
3. Footer

💡 How to Use:

Import components in your Next.js pages:
```tsx
import { Navigation, Hero, Footer } from './src/devlink'

export default function Home() {
  return (
    <>
      <Navigation />
      <Hero />
      <Footer />
    </>
  )
}

Global Styles: Import the global DevLink styles in your _app.tsx or layout:

import '../src/devlink/_webflow-style.css'

📦 No additional dependencies required! DevLink components use only React (already in your project).

🔄 Future Updates: Run webflow devlink sync again to pull latest design changes.


### Example 3: Update Existing Sync

**User prompt:**

Sync latest changes from Webflow


**Step 1: Pre-Sync State**

🔍 DevLink Update Check

Current state: ✓ Configuration: ./src/devlink ✓ Existing components: 3 (Navigation, Hero, Footer) ✓ Last sync: 2 days ago

Capturing current state for comparison... ✓ Baseline captured


**Step 2: Sync**

🔄 Syncing Updates

Executing: webflow devlink sync

Output: ✓ Connecting to Webflow site ✓ Fetching components ✓ Detecting changes ✓ Updating components ✓ Regenerating files

Sync complete!


**Step 3: Diff Analysis**

📊 Sync Analysis

Changes detected:

Modified Components:

Navigation.tsx
- Added new "Contact" link
- Updated styles for mobile view
Hero.tsx
- Changed heading text
- Updated button styling

New Components: 3. CallToAction.tsx (new)

New CTA section added

Unchanged:

Footer.tsx

📁 Files Updated:

./src/devlink/Navigation.tsx (modified)
./src/devlink/Navigation.module.css (modified)
./src/devlink/Hero.tsx (modified)
./src/devlink/Hero.module.css (modified)
./src/devlink/CallToAction.tsx (new)
./src/devlink/CallToAction.module.css (new)
./src/devlink/index.ts (updated exports)

✅ 3 components updated, 1 new component added

💡 New Component Available:

import { CallToAction } from './src/devlink'

<CallToAction />


### Example 4: Sync Specific Components

**User prompt:**

Only sync the navigation component from Webflow


**Configuration Update:**

📋 Filtering Components

To sync only specific components, update webflow.json:

Current configuration: { "devlink": { "rootDir": "./src/devlink", "cssModules": true, "fileExtensions": { "js": "tsx" } } }

Add components regex pattern: { "devlink": { "rootDir": "./src/devlink", "cssModules": true, "fileExtensions": { "js": "tsx" }, "components": "Navigation" // Regex pattern to match } }

Pattern options:

"Navigation" - Only Navigation component
"Nav.*" - All components starting with "Nav"
"Navigation|Footer" - Multiple specific components
".*" - All components (default)

Update webflow.json? (yes/no)


*User confirms: yes*

✓ Configuration updated

Syncing with filter: "Navigation"

Executing: webflow devlink sync

Output: ✓ Connecting to Webflow site ✓ Fetching components ✓ Applying filter: Navigation ✓ Exporting 1 component

📁 Generated: ./src/devlink/ ├── index.ts ├── Navigation.tsx └── Navigation.module.css

✅ Synced 1 component (Navigation only)


### Example 5: Override Site ID and Token

**User prompt:**

Sync from a different Webflow site


**Response:**

🔄 Sync from Different Site

To sync from a different site, use --site-id and --api-token options.

Get credentials:

Go to Webflow site settings
Get Site ID
Generate API token (if needed)

Sync command:

webflow devlink sync --site-id <SITE_ID> --api-token <API_TOKEN>

Example:

webflow devlink sync \
  --site-id 5f8a9b2c3d4e5f6g7h8i9j0k \
  --api-token wfp_1234567890abcdef

This overrides the .env file values for this sync only.

⚠️ Note: You can also:

Update .env file with new WEBFLOW_SITE_ID and WEBFLOW_SITE_API_TOKEN
Or maintain multiple .env files (.env.site1, .env.site2)
Then run: webflow devlink sync (uses .env)

Proceed with override? (yes/no)


### Example 6: TypeScript Configuration

**User prompt:**

Set up DevLink with TypeScript


**Response:**

📋 DevLink TypeScript Configuration

For TypeScript projects, configure file extensions:

webflow.json: { "devlink": { "rootDir": "./src/devlink", "cssModules": true, "fileExtensions": { "js": "tsx" // Use .tsx for TypeScript } } }

Benefits: ✓ Type-safe components ✓ Better IDE support ✓ Auto-completion ✓ Compile-time error checking

After sync, components will be generated as:

Navigation.tsx (instead of .jsx)
Hero.tsx
Footer.tsx

Usage with TypeScript:

import { Navigation } from '@/src/devlink'

export default function Layout({ children }: { children: React.ReactNode }) {
  return (
    <div>
      <Navigation />
      {children}
    </div>
  )
}

Ready to sync? (yes/no)


## Guidelines

### Phase 1: CLI Verification

**Installation Check:**
```bash
# Check if CLI is installed
webflow --version

# If not installed, guide user:
npm install -g @webflow/webflow-cli

Authentication Check:

# Site authentication creates .env file
# Check for:
cat .env

# Should contain:
# WEBFLOW_SITE_ID=your-site-id
# WEBFLOW_SITE_API_TOKEN=your-token

# If missing, authenticate:
webflow auth login

Phase 2: Configuration

webflow.json DevLink Schema:

{
  "devlink": {
    "rootDir": "./devlink",
    "cssModules": true,
    "fileExtensions": {
      "js": "jsx"
    }
  }
}

All Configuration Options:

Option	Description	Default	Required
`host`	Webflow API host URL	`https://api.webflow.com`	No
`rootDir`	Directory to export components into	`./devlink`	Yes
`siteId`	Webflow site ID	`process.env.WEBFLOW_SITE_ID`	No
`authToken`	Webflow API authentication token	`process.env.WEBFLOW_SITE_API_TOKEN`	No
`cssModules`	Enable CSS modules for component styles	`true`	No
`allowTelemetry`	Allow anonymous usage analytics	`true`	No
`envVariables`	Inject environment variables into exported components	`{}`	No
`components`	Regex pattern to match components to export	`.*`	No
`overwriteModule`	Whether to overwrite the module file	`true`	No
`fileExtensions`	File extensions for exported components	`{ js: ".js", css: ".css" }`	No
`skipTagSelectors`	Exclude tag/ID/attribute selectors from global CSS	`false`	No
`relativeHrefRoot`	Control how relative `href` attributes are resolved	`/`	No

Common Configurations:

React with JavaScript:

{
  "devlink": {
    "rootDir": "./src/components/webflow",
    "cssModules": true,
    "fileExtensions": {
      "js": "jsx"
    }
  }
}

Next.js with TypeScript:

{
  "devlink": {
    "rootDir": "./src/devlink",
    "cssModules": true,
    "fileExtensions": {
      "js": "tsx"
    }
  }
}

Sync Specific Components:

{
  "devlink": {
    "rootDir": "./src/devlink",
    "cssModules": true,
    "components": "Navigation|Hero|Footer"
  }
}

Phase 3: Sync Command

Basic Sync:

# Uses webflow.json config and .env credentials
webflow devlink sync

Sync with Options:

# Override site ID
webflow devlink sync --site-id 5f8a9b2c3d4e5f6g7h8i9j0k

# Override API token
webflow devlink sync --api-token wfp_1234567890abcdef

# Override both
webflow devlink sync \
  --site-id 5f8a9b2c3d4e5f6g7h8i9j0k \
  --api-token wfp_1234567890abcdef

# Short flags
webflow devlink sync -s <site-id> -t <api-token>

Sync Options:

--api-token / -t: The API token to use, overriding the .env file
--site-id / -s: The site ID to sync from, overriding the .env file

Phase 4: Generated Files

Directory Structure: After sync, rootDir contains:

./devlink/
├── index.ts                  // Module exports
├── ComponentName.tsx         // Component file
├── ComponentName.module.css  // Component styles (if cssModules: true)
├── AnotherComponent.tsx
├── AnotherComponent.module.css
└── _webflow-style.css        // Global Webflow styles

Component Structure: Generated components are React functional components:

import React from 'react'
import styles from './ComponentName.module.css'

export function ComponentName() {
  return (
    <div className={styles.container}>
      {/* Component markup */}
    </div>
  )
}

Index File: Exports all components for easy importing:

export { ComponentName } from './ComponentName'
export { AnotherComponent } from './AnotherComponent'

Error Handling

CLI Not Installed:

❌ Webflow CLI Not Found

The Webflow CLI is required for DevLink.

Installation:
npm install -g @webflow/webflow-cli

After installation, verify:
webflow --version

Documentation: https://developers.webflow.com/cli

Not Authenticated:

❌ Not Authenticated

DevLink needs authentication to access your Webflow site.

Steps:
1. Run: webflow auth login
2. Follow authentication prompts in browser
3. Select your site when prompted
4. Verify: .env file created with:
   - WEBFLOW_SITE_ID
   - WEBFLOW_SITE_API_TOKEN
5. Retry sync

Need help? https://developers.webflow.com/cli/authentication

No Configuration:

❌ DevLink Not Configured

No webflow.json with devlink configuration found.

Create webflow.json in project root:
{
  "devlink": {
    "rootDir": "./devlink",
    "cssModules": true,
    "fileExtensions": {
      "js": "jsx"  // or "tsx" for TypeScript
    }
  }
}

Required fields:
- rootDir: Where to export components

After configuration, run: webflow devlink sync

Sync Failures:

❌ Sync Failed

Error: [Specific error from CLI]

Common Causes:
- Network connection issues
- Invalid site ID or API token
- Insufficient permissions
- Site has no components to export

Solutions:
1. Check internet connection
2. Verify credentials in .env
3. Check site permissions in Webflow
4. Ensure site has published components
5. Try: webflow devlink sync --site-id <id> --api-token <token>

Retry sync? (yes/no)

Invalid Site ID:

❌ Invalid Site ID

The provided site ID is invalid or inaccessible.

Check:
1. Verify WEBFLOW_SITE_ID in .env
2. Ensure you have access to the site
3. Check site ID in Webflow dashboard

Get site ID:
1. Open site in Webflow
2. Go to Site Settings
3. Find Site ID in General tab

Update .env and retry sync.

File Operations

Reading Files: Always use Read tool (never modify):

# View DevLink configuration
Read: webflow.json

# View environment
Read: .env

# View generated component
Read: ./devlink/Navigation.tsx

# View generated styles
Read: ./devlink/Navigation.module.css

Discovering Files: Use Glob tool to find files:

# Find all generated components
Glob: ./devlink/**/*.tsx

# Find all CSS modules
Glob: ./devlink/**/*.module.css

# Find configuration
Glob: webflow.json

Never Use Write/Edit Tools:

Don't create webflow.json with Write (show user the structure)
Don't modify generated components
Let CLI handle file generation
Only read files to show content and diffs

Progress Indicators

For Sync:

🔄 Syncing Components...

Connecting to Webflow... ✓
Fetching components... ✓
Generating React code... ⏳
Creating CSS modules... ⏳

Processed: 3/5 components
Elapsed: 8s

Best Practices

Configuration:

Keep webflow.json in project root
Use TypeScript (.tsx) for better type safety
Enable CSS modules for scoped styling
Use specific component regex patterns for large sites

Development Workflow:

Design in Webflow Designer
Publish changes
Run webflow devlink sync
Review diffs before integrating
Test components in your app

Integration:

Import global styles (_webflow-style.css) in app entry point
Import components where needed
Don't modify generated files (will be overwritten)
Wrap DevLink components if customization needed

Version Control:

Commit webflow.json
Add .env to .gitignore
Commit generated devlink/ directory (or add to .gitignore)
Document last sync timestamp

Multiple Sites:

Use different rootDir for each site
Or use components pattern to filter
Override credentials with --site-id and --api-token
Maintain separate .env files

Quick Reference

Workflow: configure webflow.json → authenticate → sync

Key Commands:

webflow devlink sync - Sync components from Webflow
webflow devlink sync -s <id> -t <token> - Sync with overrides

Sync Options:

-s / --site-id - Override site ID
-t / --api-token - Override API token

Configuration: webflow.json with devlink section

Schema (Required):

{
  "devlink": {
    "rootDir": "./devlink"  // Required
  }
}

Schema (Common):

{
  "devlink": {
    "rootDir": "./devlink",
    "cssModules": true,
    "fileExtensions": {
      "js": "jsx"  // or "tsx"
    }
  }
}

Authentication: Site authentication via webflow auth login

Environment: WEBFLOW_SITE_ID and WEBFLOW_SITE_API_TOKEN in .env

Verification: Check webflow --version and site authentication first

Generated Files: React components in rootDir with CSS modules

Documentation: https://developers.webflow.com/devlink

webflow-cli:devlink