Astro to WordPress: Migrating Islands to a Real CMS

Astro nailed the developer experience for content sites: fast builds, minimal client JavaScript, island architecture that lets you drop React or Vue components exactly where you need them and nowhere else. What Astro does not solve is content workflow. Every new blog post is a Git commit. Every content edit is a pull request. Every non-technical stakeholder either learns Markdown and Git or waits for a developer. For a personal blog that is charming; for a business site with multiple editors, it is a bottleneck. Migrating to WordPress turns MDX files into database rows editors can update through a browser. The islands still hydrate. The design still ships. But the workflow shifts from `git commit -m "typo"` to clicking a title and editing it in place. That single change often pays for the migration within the first week. The second reason is plugin depth. Astro's integration ecosystem is thoughtful but small. WordPress has 60,000+ plugins covering every conceivable business feature from WooCommerce to MemberPress to booking systems. If you need any of those, WordPress is where they live natively.

Every page in your Astro build output ships as pre-rendered HTML in the WordPress theme. Content collections (blog posts, docs, product pages, whatever collection you configured) become custom post types in WordPress, one entry per row. Frontmatter fields carry across as post meta so titles, dates, tags, and custom fields all survive. Islands stay islands. If you shipped a React island for a comment box, that island's JavaScript loads exactly the way it did before, hydrates against the same DOM anchor, and behaves identically. Tailwind, UnoCSS, or vanilla CSS survive as-is. Image optimization output (multiple sizes, modern formats, srcset attributes) transfers intact. What does not carry over automatically is anything that ran on an Astro adapter — server-side session logic, edge middleware, dynamic API endpoints. Those get flagged in the audit step so you can port them to a WordPress plugin or a serverless function.

Run `astro build` locally and confirm the `dist/` folder contains every page you expect. If any route is missing, check that it is declared under `src/pages/` and that its frontmatter does not include `draft: true`. The pipeline builds against your exact package.json, so lock down dependencies with `npm ci` semantics before you upload. If you use content collections, make sure the schema in `src/content/config.ts` validates against every entry. A single schema violation stops the whole build, and it is easier to catch it locally than to debug it in the converter logs. Remove any experimental Astro features you enabled only for local development — experimental redirects, view transitions in beta modes — unless you have tested them in production output. The pipeline builds in production mode, so anything gated behind an experimental flag needs to actually work there.

Upload your ZIP or paste your GitHub URL. The pipeline detects Astro through the `astro` dependency in package.json and picks the Astro adapter. That adapter runs `astro build`, inspects the `dist/` output, and treats every `.html` file as a route. Because Astro pre-renders by default, headless Chrome is not needed for the static pages — the HTML is already complete. Islands still need a real browser to verify they hydrate correctly, so Chrome runs a validation pass on each island-heavy route to make sure no hydration warnings surface. Content collections are mapped to WordPress custom post types automatically. A collection called `blog` becomes a `blog` CPT with entries; a collection called `docs` becomes a `docs` CPT with a matching template. That means adding a new blog post in WordPress uses the same template as your original Astro content, without touching any code. Assets are rewritten from Astro's hashed convention to the WordPress theme convention, and image srcsets are updated to point at the theme's images directory. Total time for a typical marketing or docs site is three to five minutes.

Install a caching plugin. Astro sites were already fast; the goal is to not regress in WordPress, which caching solves entirely. WP Rocket, LiteSpeed Cache (if your host supports it), or W3 Total Cache all work well. Install Yoast or Rank Math to manage per-post SEO. Your Astro site probably used @astrojs/sitemap and set meta tags in the layout head — those are now editable per page in WordPress. If you used @astrojs/rss, replace it with WordPress's built-in RSS feed (available at /feed/ on every WordPress install by default) and redirect the old RSS URL to the new one. Confirm your custom post type slugs match what Astro used. If your collection lived at `/blog/`, the CPT should be registered with the same rewrite slug so URLs stay identical. The conversion pipeline handles this by default, but double-check in Settings → Permalinks.

Do not treat WordPress like Astro. WordPress wants content in the database, not in files. Once migrated, resist the urge to keep editing MDX and re-running the conversion; let editors work in the block editor instead. Do not skip the free preview. Astro sites often have subtle island behavior (a slider that hydrates on scroll, a modal that only appears on click) that is worth verifying in the preview before you buy. Do not overlook redirects. If your Astro site was on Netlify with `_redirects` rules, those rules do not travel. Recreate them with the Redirection plugin or add them to .htaccess directly. Do not forget SMTP. Fresh WordPress cannot send email reliably without configuring an SMTP plugin. Install WP Mail SMTP with a real transactional provider on day one.

Upload your Astro project on the homepage or connect your GitHub repo. The free preview lets you verify every page and every island before you pay. Conversion is usually done in under five minutes and gives you a WordPress theme that installs on any host running PHP 7.4 or newer.