Astra migration guide
Astra to Next.js: Migrate an Astra Site Layer by Layer, Rankings Intact
Open an Astra site's database and the design is not where you expect. The colors and header rows sit in one serialized row called astra-settings. The layouts sit in Spectra or Elementor data. The hooks sit in a post type most owners never see. Moving to Next.js starts with finding all three.
October 7, 2026 · 11 min read
The short answer
To migrate an Astra site to Next.js, export the content, rebuild the design from the Customizer values in the astra-settings option, convert Spectra or Elementor layouts into components, recreate Site Builder headers, footers and hooks in code, then map every URL and redirect the ones that change. Content moves cleanly; Astra's styling is rebuilt once, in code.
On this page
- Six layers hiding in a typical Astra install
- Where each Astra piece lands in the new build
- Spectra moves as data, Elementor moves as words
- Nine moves from Astra to a Next.js site
- The Astra URL plan: keep the addresses, redirect the strays
- What makes one Astra move longer than another
- After Astra: the Customizer becomes a few plain fields
Six layers hiding in a typical Astra install
Astra the theme is the smallest part of most Astra sites. The vendor says its front end weighs under 50 KB, and on a blank install that is easy to believe. A working business site piles layers on top, each stored in a different corner of the database, and a migration has to find every one before anyone writes a line of code. Here is where they usually sit.
Customizer settings
Colors, typography, container width, the header and footer builder rows and most layout choices are saved in one serialized row in wp_options called astra-settings. The global palette also prints into each page as CSS variables named --ast-global-color-0 and up.
Site Builder layouts
Astra Pro's Site Builder, once called Custom Layouts, stores custom headers, footers, 404 pages and hook inserts as posts of the type astra-advanced-hook. Each has display rules, and some carry raw code.
Spectra blocks
Pages built with Brainstorm Force's own blocks carry the uagb/ prefix, a leftover from Spectra's earlier name, Ultimate Addons for Gutenberg. The settings sit in the post; the styling is generated from them.
A page builder, if one was added
Plenty of Astra sites run Elementor, often with Ultimate Addons for Elementor from the paid bundles. Astra's pricing page also lists Beaver Builder, Divi Builder, Brizy and others as compatible.
Starter template content
The Starter Templates plugin (astra-sites) imports a full demo: pages, images, menus, forms and sometimes extra plugins. Years later, part of that demo is often still live, half edited and indexed.
Per-page Astra Settings
The Astra Settings panel in the editor sidebar lets each page hide its title, header or footer and choose its own content layout and sidebar. Small toggles, scattered across dozens of pages, easy to forget.
Most owners know about two of these layers. The audit that opens every move we make lists all six, page by page, so nothing vanishes quietly at launch. If you are not sure what your site runs, the Astra review explains how the pieces fit together, and Astra vs Next.js weighs whether leaving is worth it at all.
Where each Astra piece lands in the new build
Nothing in an Astra site is thrown away by default. Each layer has a destination, and the table below is the map we work from. Content travels as data. Design travels as decisions: a designer's choices are read out of WordPress and written into code once, instead of being redrawn by a theme on every request.
| Stored in WordPress as | Rebuilt in Next.js as | |
|---|---|---|
| Global colors and fonts | Values inside astra-settings, printed as CSS variables | Design tokens in one stylesheet; fonts self-hosted with next/font |
| Header builder rows | Above, primary and below rows for desktop, tablet and mobile | One responsive header component, tested on real phones |
| Breakpoints | 921px and 544px, changeable only through PHP filters | Whatever the design needs, set once in CSS |
| Site Builder headers and footers | astra-advanced-hook posts with display rules | Layout components chosen per page type in code |
| Hook inserts and snippets | Code attached to theme hooks | Reviewed one at a time; scripts still in use move into the layout |
| Spectra sections | uagb/ block markup with JSON attributes in the post | Content parsed into fields; sections become reusable components |
| Elementor pages | Layout JSON in post meta, drawn by the plugin | Text and images extracted; layout rebuilt from screenshots |
| Starter template leftovers | Demo pages, images and forms from astra-sites | Kept only if they earn traffic; the rest retired or redirected |
| Per-page toggles | Astra Settings values on each page | Options on the page type in Athena CMS |
| WooCommerce extras | Astra Pro shop features on top of WooCommerce data | Store pages built on Athena's built-in commerce |
Two rows tend to surprise owners. The header row ends a whole class of problems, including the Astra mobile menu that opens empty on real phones. The Customizer row ends another: if your settings have been refusing to save or your styles have been stuck on an old version, those failures leave with the theme, because a Next.js build compiles its CSS once, before deploy.
Spectra moves as data, Elementor moves as words
A Spectra page is the friendlier case. Each block is saved in the post as an HTML comment holding its settings as JSON, followed by the rendered markup. A script can walk that markup, find every uagb/ container, heading, info box and button, and hand the text, links and images to matching components. What does not come along is the CSS that Spectra generates from those settings. That is rebuilt once, as part of the design system, which is also when the spacing that drifted between pages over the years gets quietly corrected.
Elementor pages are a different job. The layout lives in post meta as a long JSON document that only Elementor knows how to draw, and much of the look depends on Elementor's stylesheets and any add-on widgets. We extract the words, headings, links and images reliably. The arrangement is rebuilt from screenshots of the live page. On an Astra site with dozens of Elementor pages, this is where the hours go. The process is set out in Elementor to Next.js, and the pairing itself is reviewed in Astra with Elementor.
Nine moves from Astra to a Next.js site
- 1
Back up and copy the settings
A full database and uploads backup, plus a separate copy of the astra-settings option. The live Astra site keeps running untouched for the whole build.
- 2
List every Site Builder layout
Each astra-advanced-hook entry is opened and recorded: what it shows, which hook it uses, which pages its display rules target, and whether it carries scripts or PHP.
- 3
Crawl the site and pull search data
Every public URL is crawled and matched with Search Console clicks and impressions, so we know which pages carry the traffic before any of them change.
- 4
Sort pages by how they were built
Spectra, Elementor, classic editor or untouched starter template. The sort sets the effort for each page and usually exposes demo pages nobody meant to keep.
- 5
Turn the Customizer into a design system
Palette, type scale, container width and header layout become tokens and components, checked against the live site before any content goes in.
- 6
Move the content into Athena CMS
Posts, pages, services and products are mapped into plain fields. Spectra content is parsed by script; Elementor content is extracted and reassembled.
- 7
Carry the images over
Originals come from the uploads folder, meaningless file names are fixed, alt text is written, and next/image serves the sizes each layout needs.
- 8
Write and test the redirect map
Every URL that changes gets a permanent redirect, tested on a staging address alongside a page-by-page visual comparison with the Astra site.
- 9
Launch and watch the crawl
DNS moves, the redirects go live, and Search Console is watched for 404s and coverage changes in the weeks after.
The third option
Athena CMS, with AI agents on staff.
Not a theme and not a blank Next.js repo. The content system we put behind every custom site: plain fields, a real preview, every version kept, and AI agents that handle the chores a plugin only nags you about.
- PicassoImages
- ApolloSite analysis
- AresCompetitor watch
- PrometheusContent holes
- AtlasPage depth and structure
- DelphiAI search visibility
and 12 more agents. Two come with Athena; the rest are monthly add-ons.
The Astra URL plan: keep the addresses, redirect the strays
Here is the comforting part: Astra does not own your URLs. Permalinks are a WordPress setting, so the addresses of your posts, pages and categories can be reproduced exactly in Next.js, where routing is written in code. Keeping them is our default. The URL structure guide explains when changing an address is worth it and when it is vanity.
- Posts and pages keep their slugs. If the site uses dated permalinks, the new routes reproduce them rather than redirect them.
- Category, tag and author archives are rebuilt or redirected to the closest useful page. Thin archives that never sent anyone anywhere are usually retired.
- Starter template demo pages that were published and indexed get a redirect to the real page they were standing in for.
- Pagination and feeds, such as /page/2/ and /feed/, are handled on purpose so crawlers and subscribers do not hit a wall of 404s.
- Image addresses under /wp-content/uploads/ are kept reachable or redirected, which matters if Google Images sends you visitors.
- WooCommerce paths such as /product/ and /product-category/ are kept or mapped one to one.
Redirects live in the Next.js configuration as permanent redirects, reviewed and tested with the rest of the build rather than added through a plugin on the live site. The method is in WordPress to Next.js redirects, and images have their own guide: moving WordPress images to Next.js. Titles, descriptions, canonicals and schema from your SEO plugin are carried across field by field, as described in migrating without losing SEO.
What makes one Astra move longer than another
Two Astra sites with the same page count can need very different amounts of work. The theme is rarely the reason. These are the things that move the calendar and the quote, roughly in order of weight.
- How many pages run on Elementor. Spectra and classic pages parse; Elementor pages are rebuilt. This one number drives more of the estimate than anything else.
- Site Builder layouts with code inside. A plain footer is quick. A hook that injects a booking widget, a tracking script and a conditional banner needs a decision about each part.
- Astra Pro shop features. Quick view, 2-step checkout and the off-canvas shop sidebar are rebuilt as store features, alongside the catalog and order history. See WooCommerce to Next.js and Astra and WooCommerce.
- Starter template sprawl. Some sites still carry dozens of demo pages and images. Pruning them is cheap; migrating them by accident is not.
- A long blog archive. Hundreds of posts move by script, but categories, featured images and internal links need checking. The blog migration guide covers it.
The drivers, and how quotes are put together, are laid out in what a WordPress to Next.js migration costs and how long a migration takes. One figure is certain: as of October 2026, Astra Pro alone is $69 a year for up to three sites, and the AI bundles renew at $149 to $429 a year. Those renewals stop when the site moves. The full list is on the Astra pricing page.
After Astra: the Customizer becomes a few plain fields
The question owners ask last and care about most: who edits the site afterward? You do, in Athena CMS, which comes with every site we build. A service page becomes a set of plain fields: headline, body, photos, call to action. You change the words, see a real preview and publish. Every version is kept, so a bad edit is one click from undone. There is no Customizer spinner to wait out, no builder panel to hunt through and no theme update waiting to rearrange your header.
What changes is the line between your job and a developer's. Text, images, posts, offers and products are yours. A new kind of page or a redesigned header is developer work, done in code and tested before deploy, which is exactly why it cannot break on a Tuesday. The upkeep that Astra sites hand to plugins goes to agents with one job each: Argus watches for broken links and failing forms, Iris writes search titles and descriptions, Picasso keeps images sized and described, and Apollo reads every page and says what to fix first. Most draft for your approval. The handover is described in switching from WordPress, the wider process sits under WordPress to Next.js, and the work itself is our Next.js rebuild service.
Questions people ask before they call
Not as settings, because Next.js has no Customizer. They are read instead. We copy the astra-settings option from your database and use its values (colors, fonts, widths, header layout) to build the design system in code. The result looks like your site without needing Astra to draw it. If the Customizer has stopped saving, we work from the last good values stored in the database.
The blocks stay behind, because they are a WordPress plugin. Their content does not. Spectra saves each block's settings and text inside the post, so a script can read headings, info boxes, buttons and images and place them into matching Next.js components. The styling is rebuilt once in code, which usually tidies up spacing that drifted from page to page over the years.
Keep it active until launch. The live site runs on it while the new one is built, and you want security and compatibility updates during that time. After the switch the renewal is no longer needed. As of October 2026 that is $69 a year for Astra Pro alone, or $149 to $429 a year for the AI bundles at renewal. The plans are compared in Astra pricing.
Their words, images and links are extracted and kept. Their layouts are rebuilt, because Elementor stores page structure as data only Elementor can render. Rebuilding gives each page clean markup and drops the add-on widgets that weighed it down. If most of your site is Elementor, read Elementor to Next.js for how that part of the job is scoped.
They should not, if the move keeps URLs, redirects every changed address, carries over titles, descriptions and schema, and keeps the content. Expect some movement while Google recrawls the new pages. We keep your URLs and redirect every old one. The full checklist is in migrating WordPress to Next.js without losing SEO.
Keep reading
- Theme vs frameworkAstra vs Next.js: A Light Theme, a Heavy Stack and a Custom BuildAstra vs Next.js, row by row: the 2026 AI bundles, the 3-site Pro cap, Elementor and Spectra, real failure modes, and when Astra is still the smart buy.
- Kadence migration guideKadence to Next.js: Moving Kadence Blocks, Shop Kit and MembersKadence to Next.js, step by step: parse Kadence Blocks, map the global palette, rebuild Hooked Elements, move Shop Kit stores and members, keep every URL.
- GeneratePress migration guideGeneratePress to Next.js: Leaving the Cleanest Theme in WordPressGeneratePress to Next.js: why GP sites cost less to move, how Elements, hooks and GenerateBlocks CSS migrate, and the URL plan that keeps your rankings.
- Leaving BlocksyBlocksy to Next.js: Moving the Customizer, Content Blocks and Shop ExtrasMove a Blocksy site to Next.js: Customizer settings, header builder, Content Blocks, Post Types Extra fields and Shop Extra features, mapped one by one.
- Leaving Hello and ElementorHello Elementor to Next.js: Migrating a Site That Lives Inside ElementorMigrate a Hello Elementor site to Next.js: Theme Builder headers and templates, Site Settings globals, popups, forms and submissions, with every URL kept.
- Bricks migrationBricks to Next.js: A Precise Migration for a Developer-Built SiteMigrate a Bricks Builder site to Next.js: page meta, templates, components, global classes, query loops and custom code, mapped exactly, with URLs kept.
- Everything in WordPress to Next.jsSee the section
Get an Astra migration plan with every layer counted
Send us your site address. We will list its Customizer settings, Site Builder layouts, Spectra and Elementor pages and every URL, then give you a fixed quote, or tell you to stay on Astra if that is the better call.
Which of these sounds like you? (pick any)
Rather talk now? Call (210) 346-0848.