This article complements Moving Your Site to a Custom Frontend, which covers the basic steps for migrating a Wix Studio or Editor site to a Wix-managed headless site built with Wix's Astro integration.
After you migrate, anything that lived in your Wix Studio or Editor site, such as widgets, page code, and forms, doesn't carry over automatically. Use this checklist to verify or rebuild those features.
Most items apply after you complete the migration. The exceptions are migration setup, cookie consent, unsupported apps, and chat, which you handle before you complete it.
The following table lists areas to review after your migration, and what to check for each area.
| Area | What to check |
|---|---|
| Migration setup | Parent site, preview site, and CLI steps |
| Redirects | Old Editor site URLs that now return 404 |
| SEO | Page SEO, robots.txt, llms.txt, and sitemap |
| Analytics | Event tracking and cookie consent |
| Multilingual | Languages and translations |
| Forms | Form UI and submissions |
| Members | Login, signup, and account pages |
| Checkout and bookings | Wix-hosted checkout and booking pages |
| Velo code | Page code, web modules, and backend code |
| Unsupported apps | Apps that don't render on headless |
| Chat | Chat widgets and Wix AI Site-Chat |
| Accessibility | Keyboard, screen reader, and contrast |
| Performance | Page speed and responsive design |
| 3rd-party scripts | Pixels, tag managers, and embeds |
Migration involves 2 sites:
Before you go live, do the following:
wix env pull so your local .env.local file has the parent site's client ID. Your frontend reads business data from the parent site, even while the preview URL belongs to the preview site..env.local, not with the site ID in wix.config.json. During migration, wix.config.json names the preview site.To go live, open Complete Migration in Headless Settings in your dashboard. The dialog gives you a prompt with the --app-id and --site-id values you need. Run wix finalize-migration only with the flags from that prompt, and only after you open the dialog.
The wix finalize-migration command switches your project's configuration to the parent site, and then builds and releases your project. Until it finishes, your domain still serves your Editor site.
After migration, your domain serves only the pages in your headless frontend. Pages from your Wix Studio or Editor site that you didn't recreate return a 404 error. Add 301 redirects so that bookmarks, campaigns, and search results land on the right pages.
To redirect old URLs:
You can also manage redirects with the SEO Redirects API.
Note: Dashboard redirects apply at the site level on your connected domain. Routing in your frontend code, such as Astro middleware, also works, but it only affects requests that reach your project. Wix serves some paths itself and those never reach your code. See Reserved URL Paths for the Astro Integration.
Your SEO settings follow your new frontend automatically, and Wix generates SEO tags for your headless pages from the settings in your dashboard. The settings apply only to routes that your new frontend serves, so routes that exist only in your new frontend, and URLs that changed, need review. Review SEO after the headless site is live.
Check the following:
wixstatic.com media URLs and alt text as on your Editor site.robots.txt, llms.txt, and sitemap: Wix serves /robots.txt, /llms.txt, and /sitemap.xml from your SEO & GEO settings and your published headless routes. These files aren't copied from your Editor site when you finalize the migration, so review the live files and update your settings if they're out of date. Avoid adding your own robots.txt page to your project unless you intend to override the default behavior. See About SEO Support and About Sitemaps in Managed Headless.<head>. Then resubmit your sitemap and monitor for crawl errors.Wix analytics and your connected analytics and marketing tools follow your new frontend automatically after you switch. Events that come from the UI you build aren't reported unless you send them yourself. To do this, install the @wix/site package and call analytics.trackEvent() wherever the action happens in your frontend:
Events go to Wix analytics, and Wix forwards them to the platforms you connect, such as Google Analytics 4, Facebook Pixel, and Google Tag Manager. For the full steps, see Track Analytics Events.
Do the following:
trackEvent() call for each event you relied on before. Use the standard event names, so external platforms recognize them. For example, use ViewContent for product and other key pages, AddToCart, InitiateCheckout, Purchase, Lead for form submissions and newsletter signups, and Schedule for bookings. For other actions, use CustomEvent.wix build and wix release, then confirm that the events arrive in the dashboard or your connected platform. Wix delivers events only from a released site with a custom domain connected. During local development with wix dev, the calls run without errors, but Wix doesn't deliver any events.If your Editor site uses Wix Multilingual, you can support multiple languages on your headless site, but your Editor site translations don't copy over automatically. You translate the content that your new frontend renders.
To set it up, define translation keys in your project, sync them with the Multilingual dashboard using the wix translation push and wix translation pull CLI commands, and retrieve translated values in your code. See Add Multilingual Support.
Check the following:
hreflang tags.The Wix Forms business app keeps working on your site. Submissions, contacts, automations, and notification emails still run from the dashboard. But the form embeds from your Editor site don't render on the headless frontend. Rebuild the form UI in your frontend, and send submissions to the same form with the Wix Forms APIs. See Form Submissions API.
Check the following:
Migration doesn't delete past submissions. They stay in the dashboard under the forms experience where visitors submitted them. New submissions come from the forms that your frontend posts to.
If your site has members, the member areas of your Editor site, such as login, signup, and account pages, don't carry over. The Astro integration includes built-in authentication endpoints, so you can add Wix's login page or build your own.
Check the following:
For processes that need a user interface, such as checkout and booking a service, you can redirect visitors to Wix-hosted pages instead of building the pages yourself. See About Wix-Hosted Pages.
Check the following:
Velo code that you wrote for your Wix Studio or Editor site doesn't run on the headless frontend. That includes page code, $w element code, and calls to backend/*.jsw web modules from your pages. Your Velo backend code stops working too. After you switch, requests to your site's /_functions URLs no longer reach your Velo backend, so you need to rewrite anything you still need in your headless project.
Replace each piece of Velo code with its headless equivalent:
| Velo code | Headless replacement |
|---|---|
Page code and masterPage.js | Use it as a reference for your business logic, and re-implement the logic in your Astro frontend. Don't port it 1. |
.jsw backend web modules | Create HTTP endpoints at src/pages/api/<name>.ts that use the Wix SDK. Callers switch from importing the module to calling the endpoint with fetch. |
http-functions.js | Create HTTP endpoints at /api/<name>. The URL changes, so update external callers, such as webhooks, Zapier, and partner integrations. |
events.js and after* data hooks | Add an event extension, with 1 handler for each event. |
before* data hooks | There's no direct equivalent. Move the logic into the /api endpoint that writes the data. |
jobs.config scheduled jobs | There's no scheduler extension for headless projects. Call an HTTP endpoint from an external cron service, or use Wix Automations. |
| Secrets | Call the Secrets API with elevated permissions from your /api endpoints. |
| Service plugins | Add a service plugin extension. |
Headless backend code is limited to 1000 CPU milliseconds and 20 sub-requests per request, so long Velo functions might need to be split or simplified. Backend code in preview builds stops working after 3 days.
Check the following:
/_functions URLs.If you switch back to your Editor site's storefront, where your plan allows it, your Velo page and backend files are still on your site.
Some Wix apps don't render on a headless frontend. See supported and unsupported apps. Unsupported apps don't appear to visitors on your headless site, but they stay installed and you can still manage them from the dashboard.
Check the following:
Chat widgets, such as Wix Chat and Wix AI Site-Chat, are elements of your Editor site, so they don't render on your headless site. There's no supported way to place these widgets on your custom frontend.
If you still need chat, you can build the visitor-facing chat UI yourself with the AI Site-Chat APIs. These APIs require the Wix AI Site-Chat app, which is available only in the Wix Editor. Install and configure the app on your Editor site before you complete the migration. The widget stays hidden on your headless site, but the app stays installed on your site, so your frontend can send and read messages through the APIs.
Check the following:
Your Editor site's accessibility settings don't apply to a custom frontend. You're responsible for the accessibility of the pages you build.
Check the following:
Your Editor site's responsive layouts and performance optimizations don't carry over. Test your new frontend on real devices and screen sizes, and measure page speed on your key pages. For caching, see About Page Caching in the Astro Integration.
Scripts that you added to your Editor site, such as advertising pixels, chat widgets, reviews, and embeds, aren't included in your new frontend. Check your Editor site's custom code and embedded elements, and add what you still need to your frontend.
Last updated: 29 October 2026