vc2gut

🔄 Migrate hundreds of Visual Composer pages to Gutenberg in minutes, not months 🚀

---

🤔 The Problem

You've got a WordPress site with hundreds of pages built in Visual Composer (WPBakery). You need to move to Gutenberg. Manually converting each page is weeks of tedious copy-paste work — and you know half the formatting will break anyway.

✅ The Solution

vc2gut parses VC shortcodes into an AST, fingerprints the page structure, and converts to native Gutenberg blocks. Pages that share the same layout get the same fingerprint — accept one, batch-accept them all.

Before	After
[vc_row][vc_column width="1/2"]...	<!-- wp:columns --><!-- wp:column -->...
Manually rewrite each page	Review and batch-accept by pattern
Weeks of migration work	Side-by-side review in minutes

---

⚡ Features

• 🧠 Smart Parsing — tokenizes [vc_*] shortcodes into a full AST
• 🔍 Structural Fingerprinting — groups identical layouts with xxhash for batch operations
• 📦 30+ VC Elements — rows, columns, text, images, buttons, accordions, videos, grids, and more
• 👀 Side-by-Side Review — original VC source (left) vs converted Gutenberg (right)
• ⚡ Pattern Batch Accept — accept one page, batch-accept all pages with the same structure
• 🌐 Polylang Sync — auto-accepts translation pairs when structures match
• 📝 Inline Editing — edit converted output before saving back to WordPress
• 🔒 Non-Destructive — original content preserved until you explicitly accept

---

🚀 Quick Start

git clone https://github.com/erimeilis/vc2gutenberg.git
cd vc2gutenberg

# Install dependencies
npm install

# Configure WordPress database connection
cp .env.example .env
# Edit .env with your DB credentials (or skip — auto-discovers wp-config.php)

# Start dev server (API + React UI)
npm run dev

Open http://localhost:5173 and start reviewing.

⚙️ Configuration

The tool finds your WordPress database automatically:

1. .env file in the project directory (recommended)
2. wp-config.php auto-discovery (walks up parent directories — works with Valet, MAMP, etc.)

# .env — Option A: Individual variables
WP_DB_HOST=localhost
WP_DB_PORT=3306
WP_DB_USER=root
WP_DB_PASSWORD=
WP_DB_NAME=your_wordpress_db
WP_TABLE_PREFIX=wp_

# Option B: Connection URL
WP_DATABASE_URL=mysql://root:password@localhost:3306/your_wordpress_db

---

🔄 How It Works

  Scan           Parse          Fingerprint       Convert         Review          Accept
┌────────┐    ┌────────┐      ┌───────────┐    ┌──────────┐    ┌─────────┐    ┌──────────┐
│ Read   │───▶│ Build  │─────▶│ Group by  │───▶│ VC → WP  │───▶│ Side by │───▶│ Save to  │
│ WP DB  │    │  AST   │      │ structure │    │ blocks   │    │  side   │    │ WP DB    │
└────────┘    └────────┘      └───────────┘    └──────────┘    └─────────┘    └──────────┘
                                    │                                │
                                    └── Same fingerprint ──────────▶ Batch accept all

1. Scan — reads all posts containing [vc_ shortcodes from your WordPress database
2. Parse — tokenizes shortcodes into an Abstract Syntax Tree
3. Fingerprint — generates structural hash (xxhash) to group identical page layouts
4. Convert — maps VC elements to native Gutenberg block markup
5. Review — side-by-side UI for comparing original vs converted output
6. Accept — saves converted content back to post_content in WordPress

---

📦 Supported VC Elements

VC Shortcode	Gutenberg Block	Notes
vc_row (single column)	Unwrapped	Content promoted to top level
vc_row / vc_row_inner (N cols)	core/columns	Column widths preserved
vc_column_text	Split into blocks	Headings, paragraphs, lists, tables
vc_single_image	core/image	Flagged if matches featured image
vc_separator / vc_text_separator	core/separator
vc_btn / vc_button	core/button
vc_video	core/embed	YouTube/Vimeo detection
vc_message	core/paragraph	Preserves legacy CSS class
vc_raw_html / vc_raw_js	Decoded + split	Base64/URL-encoded content handled
vc_tta_accordion / vc_tta_tabs / vc_tta_tour	Flagged	Complex elements for manual review
vc_basic_grid / vc_masonry_grid	Flagged	Archive templates, flag for removal
vc_empty_space	Removed	Not needed in Gutenberg

---

🏗️ Architecture

vc2gut/
├── cli/                  # Backend — Express 5 API + conversion engine
│   └── src/
│       ├── parser/       # VC shortcode tokenizer + AST builder
│       ├── fingerprint/  # Structural fingerprinting (xxhash)
│       ├── converter/    # VC → Gutenberg block serializer + recipes
│       ├── db/           # MySQL (WordPress) + SQLite (app state)
│       └── server/       # Express API (19 endpoints)
├── ui/                   # Frontend — React 19 + Vite
│   └── src/
│       ├── components/   # ReviewQueue, SourcePreview, GutenbergEditor,
│       │                 # ActionBar, Settings, Button, Layout
│       ├── hooks/        # useApi, useAppConfig, useAnimatedNumber
│       └── i18n/         # Translations (English)
└── data/                 # SQLite database (auto-created at runtime)

Two-Database Strategy

Database	Purpose
WordPress MySQL	Source of truth for posts — read during scan, write on accept
SQLite	App state — migration status, fingerprints, user edits, settings

---

🧪 Testing

npm test             # Run all 136 tests
npm test -- --watch  # Watch mode

Suite	Tests	Covers
Parser (tokenizer + AST)	14	Shortcode tokenization, tree building
Converter (serializer + HTML splitter)	40	VC → Gutenberg block output
Recipes	23	Recipe-based conversion rules
Fingerprint	7	Structural hashing, grouping
Database	19	SQLite state, WP config parsing
Integration	17	End-to-end with real-world fixtures

---

📜 Scripts

npm run dev        # Start API (port 3001) + UI (port 5173)
npm run dev:cli    # API server only (hot reload via tsx)
npm run dev:ui     # React UI only (Vite)
npm run build      # Production build (both workspaces)
npm run test       # Run test suite (Vitest)
npm run lint       # TypeScript type checking (both workspaces)

---

🛠️ Tech Stack

Layer	Technology
Runtime	Node.js 22+
Backend	Express 5, TypeScript 5.9, mysql2, better-sqlite3
Frontend	React 19, Vite, React Router 7, i18next
Testing	Vitest 4.0
Monorepo	npm workspaces (cli/ + ui/)

---

🐛 Troubleshooting

ERR_DLOPEN_FAILED / NODE_MODULE_VERSION mismatch

Switched Node versions after installing? Rebuild the native module:

npm rebuild better-sqlite3
# or clean install
rm -rf node_modules && npm install

Cannot find WordPress database

The tool looks for credentials in order:

1. .env file in project root
2. wp-config.php in parent directories

Create one: cp .env.example .env

---

📄 License

MIT — use it, fork it, ship it.