WPBakery to Astro: a practical migration guide

A WPBakery-to-Astro migration can preserve your website’s content and design while removing its dependence on WPBakery for the public pages. WordPress can remain the content editor. Astro, a framework for building websites from reusable components, takes over the layouts and visitor-facing features.

The challenge is often an inherited system: WPBakery supplies some elements, the theme supplies others, and shortcodes connect them to content or external services. A good migration identifies those responsibilities before trying to clean up the markup.

This guide covers that investigation, a practical way to map shortcode content, design preservation, editing, and the launch. Update and shortcode troubleshooting belong in the same conversation because they help establish what actually needs to change.

Confirm WPBakery, Visual Composer, and the active theme

Check Plugins > Installed Plugins for the product name and version. WPBakery Page Builder was formerly named Visual Composer Page Builder; Visual Composer Website Builder is a separate product. The vendor explains the distinction in its naming guide.

Older agency notes, theme documentation, or screenshots may still use the old name. A saved vc_ shortcode is a clue to investigate, not a complete inventory of the installed software. Use the active plugin and its documentation to identify the product.

If the builder button is missing from a post type, inspect WPBakery Page Builder > Role Manager > Post Types for the affected user’s role. WPBakery’s post-type access guidance identifies this setting. Check the intended role and content type; a missing editor button alone doesn’t establish that the saved layout is gone.

Then check Appearance > Themes, including the child theme. Record theme companion plugins, add-ons, and custom code. Open a homepage, service page, archive, and any page with a distinctive interactive element. Those pages may use different combinations of the builder and theme.

Take a complete database and file backup and restore a working source copy. Preserve purchase records and available custom source code too. A static screenshot won’t explain how a theme-specific pricing calculator or filtered portfolio works.

Untangle theme-bundled updates before changing platforms

WPBakery’s bundled-license guidance says customers using a copy supplied with a theme receive updates through the theme author unless they have a direct license. Confirm the actual purchase and support arrangement with the provider or current maintainer.

A missing vendor login can be an ownership question rather than a broken installation. Establish who supplies updates, who tests theme compatibility, and who restores the site if an update fails. A direct plugin purchase may change the update route; it doesn’t demonstrate that every custom theme element works with the new release.

If the site otherwise serves the business well, resolving this arrangement may be enough. A rebuild becomes a more useful discussion when the investigation reveals features nobody can maintain, repeated failures, or editing that no longer fits the team.

Carry clear ownership into Astro: domain, WordPress hosting, repository, public deployment, and external services should have named account owners and maintainers. Changing frameworks won’t resolve an undocumented handover on its own.

What if WPBakery shortcodes are showing on the page?

Literal shortcode text is a symptom to investigate before deleting anything. Identify a visible tag and the code that is supposed to handle it. It may belong to WPBakery, a theme, or another plugin; WPBakery explicitly supports third-party shortcodes.

Compare with a known working backup on staging. Check whether the relevant plugin or theme component is active, whether an update changed the integration, and whether the content is being displayed through a path that processes shortcodes. Save the original content before changing it.

Don’t remove every bracketed expression to make the page look clean. That can discard image references, button destinations, layout grouping, and custom settings. Recover a working reference where possible, then decide what should survive in the rebuilt site.

For an Astro page, placing [vc_row] in a component doesn’t execute WPBakery’s WordPress code. If an interim solution asks WordPress to render the old shortcodes, document that dependency. The site hasn’t finished leaving the builder while it still needs that renderer.

Read the shortcode structure and map the content

WPBakery’s element development documentation covers registering custom elements. That extensibility is why one site’s content may contain much more than the standard builder elements.

Here is an illustrative fragment showing a row, a column, and a text block. It is a reading example, not an export from a tested website or a complete conversion script:

[vc_row]
  [vc_column]
    [vc_column_text]
      <h2>Office cleaning</h2>
      <p>Regular visits for shared workspaces.</p>
    [/vc_column_text]
  [/vc_column]
[/vc_row]

The title and paragraph carry content. The enclosing elements describe grouping and presentation. For a service page, the content could become a service name and introduction, with an Astro template controlling its layout.

A real page may add nested rows, media IDs, attributes, or theme-specific elements. Inspect those structures before writing conversion rules. Preserve source page IDs and the original source so reviewers can trace a missing link or image back to the right place.

Use a parser suited to the actual nesting and shortcode syntax. A broad regular expression that strips everything between brackets is not a content migration strategy. Unknown structures should stop that item’s automatic conversion and create a review task.

For a small site, manual mapping may be easier to verify than building an importer. For repeated layouts, automate only the patterns you’ve inspected. Either approach needs a comparison of text, links, media, and section order against the source.

Keep the design without keeping its implementation

You can use the current site as the visual brief. Record which details must match and which changes are intentional. Capture fonts, spacing, image crops, content widths, backgrounds, navigation, and mobile behavior.

Identify who supplies each distinctive section. A gallery may come from a theme companion plugin; a slider may be provided by a separate slider plugin; a row may contain custom HTML. The fact that a feature appears inside the WPBakery editor doesn’t prove WPBakery supplies its behavior.

Rebuild repeated patterns as Astro components and shared styles. For example, the same service-card design can display WordPress service records on both the homepage and service index. Keeping the existing typography and layout doesn’t require carrying its old shortcode structure into the new templates.

Compare the same content at the same viewport. Include open menus, expanded panels, image lightboxes, form errors, and keyboard focus. Test long headings, an additional card, and missing optional images. Those cases show whether the component works as a maintained design rather than a single visual copy.

Review accessibility changes explicitly. Correct heading order, labelled form controls, and usable mobile navigation can be part of preserving the site’s purpose while improving how people use it.

Replace the functionality supplied by themes and plugins

Build an inventory around visitor actions: submit an enquiry, filter projects, search the site, book a visit, sign in, or pay. For each action, identify the provider, data source, processing, and destination.

If a WPBakery page embeds Contact Form 7 or Gravity Forms, the form’s backend is a separate dependency. Keeping that plugin may be possible with a suitable integration, but copying the rendered fields isn’t enough. Confirm how the Astro frontend submits data and how the system validates, stores, and delivers it.

Test successful submissions and useful failure handling. Check required fields, spam controls, files if supported, confirmation messages, and the notification received by the person answering enquiries. Include CRM or mailing-list actions where they are part of the existing feature.

For a project grid, recreate category selection, ordering, pagination, and empty results. For commerce or memberships, scope authentication, account pages, checkout, and confirmations. A working initial screen is only part of that journey.

Our compatibility notes explain why retaining WordPress content and retaining plugin-driven public behavior are different decisions. Make the integration plan specific to the features this site uses.

WPBakery 9 or Astro: give the current builder a fair comparison

An old complaint may not describe the version you can use today. WPBakery’s July 2026 version 9.0 announcement describes interface changes, responsive editing, and modular CSS loading. Those are vendor-described changes, not performance results from this guide.

A targeted update or repair may suit a team that likes the visual editor. An Astro rebuild is worth considering when you want maintained public templates, more deliberate asset loading, and content editing that doesn’t require handling layout details.

Measure with a realistic page. Include its images, fonts, embeds, analytics, and forms in both versions. Record visitor performance and the time or difficulty of ordinary editing as separate findings. Another framework won’t make a large video or external booking widget cost nothing.

Compare the whole cost: rebuilding, content mapping, integrations, WordPress hosting, public hosting, support, and subscriptions you can actually retire. Do not justify the project solely by counting plugins.

Keep WordPress useful for the next edit

WordPress can supply content to Astro through its API, with optional GraphQL integrations described in the Astro WordPress guide. Decide which records, fields, and media the new templates need. A rendered WordPress response may still contain builder markup or depend on shortcode execution, so inspect what is actually being returned.

Give content a shape editors recognize: service name, introduction, benefits, project images, contact details. Decide what is shared across the site and what varies per page. Offer the layout choices the team needs, with a clear process for adding new components.

Build one difficult page early and connect its content and features. Have an editor create or update it, preview a draft, publish, and correct it. If campaign creation is a normal task, include making a new campaign in the trial. Astro doesn’t automatically reproduce WPBakery’s drag-and-drop editor.

For prebuilt pages, a content change needs a successful build and deployment before visitors see it. Other rendering arrangements need defined caching rules. Demonstrate private previews, scheduled changes, media replacements, and what happens when publication fails. Keep credentials server-side and expose only the content the public site needs.

Launch with URLs, enquiries, and recovery checked

The SEO migration inventory and example give the URL checks a place to live. Record theme-supplied features separately in the project brief, with an expected result and someone responsible for checking it.

Keep existing public URLs where possible. Map changed paths to relevant permanent redirects and check downloads and media links that matter. Carry titles, descriptions, canonical URLs, social images, structured data, and sitemap membership into Astro deliberately.

Before cutover, compare important pages, test mobile and keyboard use, exercise forms and other visitor journeys, and complete a final content sync. Keep the source site recoverable and document how to roll back. Preserving URLs and content helps continuity; it doesn’t guarantee search rankings.

After switching traffic, check the public responses, redirect destinations, notification delivery, and a real content update. Retire WPBakery and theme dependencies only after their jobs are replaced. A child theme or companion plugin may still contain a content type or integration the backend needs.

A relatively small set of repeated layouts and known shortcodes makes this work easier to plan. Unidentified custom elements, account systems, and unsupported theme code make it more involved. Scope those findings before promising a timeline.

If you want help making sense of an inherited site, send us its URL, the theme name if you know it, and one feature you’re unsure how to replace. Our WordPress-to-Astro service covers the public rebuild and content connection. That example page gives us a useful starting point for discussing the work.

Use the cost and ownership worksheet to compare quotes against that same feature list, including any licenses and support the replacement still needs.