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.
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 |
- 🧠 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
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 devOpen http://localhost:5173 and start reviewing.
The tool finds your WordPress database automatically:
.envfile in the project directory (recommended)wp-config.phpauto-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 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
- Scan — reads all posts containing
[vc_shortcodes from your WordPress database - Parse — tokenizes shortcodes into an Abstract Syntax Tree
- Fingerprint — generates structural hash (xxhash) to group identical page layouts
- Convert — maps VC elements to native Gutenberg block markup
- Review — side-by-side UI for comparing original vs converted output
- Accept — saves converted content back to
post_contentin WordPress
| 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 |
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)
| Database | Purpose |
|---|---|
| WordPress MySQL | Source of truth for posts — read during scan, write on accept |
| SQLite | App state — migration status, fingerprints, user edits, settings |
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 |
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)| 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/) |
Switched Node versions after installing? Rebuild the native module:
npm rebuild better-sqlite3
# or clean install
rm -rf node_modules && npm installThe tool looks for credentials in order:
.envfile in project rootwp-config.phpin parent directories
Create one: cp .env.example .env
MIT — use it, fork it, ship it.