wp-volt

Migrate a WordPress site to a Volt app in one command — content, media, menus, and site config — with your URLs preserved and an honest report of what didn't convert.

Published as @voltjscom/wp-volt. The CLI is wp-volt. Full guide → docs/migrating.md.

npx @voltjscom/wp-volt migrate ./export.wxr --out ./mysite
cd mysite && npm install && npm run dev        # your old site, now on Volt

That one command scaffolds a complete Volt app (server, the :5050 setup admin, add-ons, deploy configs), migrates your content into it, and leaves you a runnable site.

What it does

 acquire ─▶ fingerprint ─▶ convert ─▶ preserve URLs ─▶ scaffold + publish
   WXR        plugin        Gutenberg    permalinks       full Volt app
   URL        catalog       Elementor    _redirects       pages/·posts/·media/
   DB         (~46)         complex →     front page       _nav.md · .env · 404
   bundle                   HTML layout

wp-volt migrate <source> --out <dir> [--port <n>] [--no-scaffold]
#   <source>  a .wxr/.xml export file  ·  an https:// site URL (REST)
#   --db mysql://user:pass@host/db [--prefix <p>]   read straight from the database
#   --user <u> (+ WP_APP_PASSWORD)  ·  --verify <token>   prove you own a live URL
#   --drafts                                        include unpublished content

wp-volt verify <url>          # mint a domain-challenge token for a live-URL migration
wp-volt fingerprint <url>     # detect plugins/builders, print the migration plan (no auth)

Output is a runnable Volt app: pages/*.md + posts/*.md (front-matter + HTML body), pages/_nav.md (nested menu → routes), pages/404.md, .env (site identity + add-ons), _redirects (legacy URLs), and public/media/ (downloaded). Front-matter matches Volt's contract (category, tags, image, permalink, format: html).

URLs are preserved: each item keeps its exact WordPress path (permalink:), a static front page becomes /, a posts home sets HOMEPAGE=posts, and legacy paths (feeds, Redirection rules) land in _redirects — so inbound links and SEO survive.

Migrating a live URL requires proof you own the site — a WordPress application password (--user + WP_APP_PASSWORD) or a .well-known domain challenge (wp-volt verify). WXR and --db need no auth (possession is proof).

The model

The unit of work is a plugin, not a site. We build a clean-room feature equivalent of each popular plugin once, then per-site only fingerprint what's in use and map that site's config onto it — O(plugins), which compounds, not O(sites), which never converges. Every detected plugin gets a disposition:

• port — build an equivalent + map config (blocks, SEO, forms, redirects, tables…)
• drop — no equivalent needed; Volt/host handles it (caching, security, backup)
• flag — too complex/commercial to auto-convert (WooCommerce, LMS, membership)
• fallback — no adapter yet; best-effort, human-reviewed (the long tail)

Fingerprinting is signature matching (asset paths, REST namespaces) — never reverse-engineering the frontend JS, since most plugin logic is server-side PHP.

Layout

bin/wp-volt.js             the CLI (migrate · verify · fingerprint)
src/migrate.mjs            orchestrator: acquire → convert → nav/config → scaffold → publish
src/scaffold.js            scaffold a full create-volt app + merge its .env
src/detect/signatures.js   ~46-plugin signature catalog + matchSignatures()
src/acquire/               crawl · wxr · rest · db · verify (challenge) · php-unserialize
src/adapters/              gutenberg · elementor · seo · forms · redirects · table
src/publish/               project · volt-schema · render-html · layout · nav · config
src/importers/csv.js       CSV → Volt pages or a data collection (add-on)
src/review/report.js       self-contained HTML review console (plan → diff → gaps)
tests/                     11 suites — npm test

Status

Runs end-to-end and proven live: migrates a real WordPress site — pages, posts, featured images, nested menu, tables, site identity, complex multi-column layouts — into a scaffolded, runnable Volt app with identical URLs. Ownership-gated for live URLs. Byte-accurate PHP-unserialize decoder handles serialized theme_mods.

Todo: computed-CSS capture for Elementor visual fidelity; remaining port adapters (i18n, ACF); optional client-rendered html\`component pages.npm test` is green.

License

MIT © Richard Whitney