wp-migrate-core

A command-line tool for getting a WordPress-to-Astro migration started. It reads a WordPress XML export, inventories content, images and links, and can generate an Astro project with a clear list of what still needs rebuilding.

DownloadVersion 0.3.0
wp-migrate-core

About wp-migrate-core

Exporting the posts is usually the straightforward part. Then you remember the shortcodes, the Elementor widgets, the old URLs and that contact form which definitely won’t keep working just because its text made it across.

wp-migrate-core starts by making those jobs visible. You can inspect an export before generating anything and get a local report showing the content it understands, the image references it finds, the proposed routes and the parts that need a decision or a manual fix.

When you’re ready, it can turn supported content into an Astro starter project. It handles a limited set of Gutenberg blocks and Elementor content, keeps classic HTML for review, and leaves visible reminders where something needs rebuilding. Your theme, layouts, forms and plugin features still need your attention.

The URL and link maps help with the less visible parts of the move. You can review old permalinks against proposed routes, spot collisions and unresolved targets, and see which internal links need changing. During conversion, recognized links to generated pages are rewritten to their new routes. Redirect rules are provided for review and manual setup on your host.

Images get their own inventory, including attachment matches and available alt text. The actual files still need bringing over—the tool doesn’t download or copy them.

Everything runs locally from the export, without needing a WordPress login or changing the original site. The generated project starts with indexing disabled, giving you a place to work through the report and compare the rebuild with the original before publishing.

Release history

Version 0.3.0
  • Adds a link inventory to inspection plans, HTML reports, CLI summaries, and generated projects at migration/links.json.
  • Classifies supported HTML, Gutenberg, and Elementor links against exported URLs and generated routes, with per-record warnings for unresolved same-site targets.
  • Rewrites supported same-site hrefs during conversion, preserving query strings and fragments. --keep-source-links and the library's { rewriteLinks: false } option retain source hrefs while keeping proposed rewrites visible.
  • Preserves distinct hrefs, path case, and encoded separators; leaves ambiguous permalinks and unknown external hosts for review instead of guessing a target.
  • Sanitizes credentials and queries in link reporting, including protocol-relative URLs, and sanitizes source URLs in the generated manifest and README.
  • Updates the manifest and link inventory to schema version 0.3; media and redirect inventories remain at 0.2.

External download

Download 0.3.0
Version 0.2.0

This release adds a media inventory and a URL/redirect map to help plan a WordPress-to-Astro migration. Both use only the WXR export; migration commands make no network calls and do not download media or publish redirects.

  • Inventories attachment records, available alt text and dimensions, and references from supported Gutenberg blocks, Elementor image/background settings and text/HTML widgets, featured images, and rendered image tags.
  • Matches attachments by ID or file path, with unambiguous WordPress filename variants as a fallback. Exact filenames take priority; different hosts, folders, or filename case are not silently merged. Repeated references to one asset are grouped per content record.
  • Adds per-record warnings for missing attachment records and missing alt text. Unreferenced uploads remain visible without adding warnings, and trashed attachments are skipped.
  • Maps exported page/post permalinks to proposed routes, identifies path redirects, and explains excluded, skipped, colliding, and query-string URLs. Conversion continues to refuse duplicate routes.
  • Includes both inventories in the HTML report and inspection plan, and their summary counts in CLI output and --json. Generated projects include migration/media.json and migration/redirects.json; these files and the manifest use schema version 0.2 independently of the package version.
  • Preserves encoded source paths and repeated slashes in redirect rules, and sanitizes protocol-relative URLs consistently so credentials cannot leak into review plans, reports, or inventory URL fields.
  • Refreshes the npm README with a demo-first walkthrough, output-file guide, library example, and clearer migration and privacy limits.
  • Extends parser, CLI, privacy, and installed-package regression coverage, including exact media matching, nested blocks, filename variants, Elementor inline images, and redirect path preservation.

External download

Download 0.2.0
Version 0.1.3

This release adds CLI scan controls and machine-readable results for local review and CI.

  • Passes --include-drafts through to the parser so CLI scans can include drafts, pending, private, and other non-published posts and pages.
  • Adds --json to inspect, convert, report, and demo, reporting generator identity, scan settings, summary counts, sanitized issues, output paths, and failure status without the source URL or raw issue evidence.
  • Adds --fail-on none|warning|blocker to set a failing exit status for issues at or above the chosen severity after writing output. The default none preserves existing behavior.
  • Covers draft inclusion, JSON privacy, clean and single-severity scans, and output preservation when a severity gate fails with CLI regression tests.

External download

Download 0.1.3
Version 0.1.2

This release improves CLI argument handling and makes the current release the default npm install.

  • Changes the default npm publishing tag to latest and updates the installation instructions.
  • Rejects missing, blank, or option-like values for --out and --target before reading an export or writing output.
  • Adds --version / -v and supports --help / -h after a command without requiring an input file.
  • Reads the CLI, HTML report, and generated handoff version from the package metadata so they stay in sync.
  • Reports unknown commands and options before attempting to read an export.
  • Adds CLI regression tests and an installed-tarball check for the executable, bundled fixture, ESM exports, and generated version metadata.
  • Adds read-only GitHub Actions CI for Node 20 installation, tests, and npm package checks; publishing also runs the installed-tarball check.

External download

Download 0.1.2
Version 0.1.1

This release makes inspection safer when an export or output path is not quite what the CLI expects.

  • Writes the inspection plan and repair report as one staged handoff, then moves them into place together.
  • Refuses an existing inspection output path without changing its files.
  • Skips missing, invalid, and duplicate WordPress post IDs and explains each skipped item in the repair queue.
  • Keeps malformed numeric XML entities intact instead of letting them crash WXR parsing.
  • Adds regression coverage for the parser edge cases and the CLI's no-clobber behavior.

External download

Download 0.1.1
Version 0.1.0-demo

The first public demo: inspect a WordPress WXR export, surface unsupported migration work, and generate a deliberately private Astro handoff for human review.

External download

Download 0.1.0-demo