A partial Astro migration moves the parts of a live website that need a better technical foundation first, while the rest of the site keeps running on the existing platform. Instead of waiting for a full rebuild, a team can move high-value landing pages, resource centers, performance-sensitive pages, or important SEO pages into Astro and learn from that slice before committing the whole site.
This is useful when the current site is slow, fragile, or hard to update, but a full cutover would put search traffic, analytics, forms, or sales campaigns at risk. The point is not to run two platforms forever. The point is to protect business value while proving the new architecture on pages that matter.
Astro fits this phased approach because it is built for content-heavy sites, marketing sites, landing pages, and portfolios. The official Astro migration docs note that existing projects may be able to reuse UI components, stylesheets, Markdown or MDX files, and CMS content through integrations or APIs. Astro also supports fully static pages, on-demand rendered routes, or a mix of both, which gives teams room to modernize a site section by section instead of forcing one launch event.
Use this guide if you are deciding whether to migrate part of a website to Astro before a larger platform migration. The decision is less about Astro itself and more about routing, redirects, analytics continuity, design consistency, content ownership, and how long the business can tolerate two systems.
When partial Astro migration is useful
Partial Astro migration is useful when one part of the site has a stronger business case for change than the rest. The best first slice is usually public, measurable, and somewhat separable from the legacy platform.
Good candidates include:
| Page or section | Why it is a good first move | What to protect |
|---|---|---|
| Campaign landing pages | They need speed, clean tracking, fast iteration, and fewer platform constraints | Forms, pixels, UTMs, thank-you states, design consistency |
| Resource centers | They benefit from structured content, clean internal links, and faster publishing | Authors, categories, search, sitemaps, canonical URLs |
| High-value SEO pages | They already earn traffic or backlinks, so performance and HTML quality matter | Redirects, metadata, schema, internal links, crawl behavior |
| Product or service pages | They influence sales conversations and paid traffic quality | CTAs, forms, proof, analytics events, CRM routing |
| Event or launch microsites | They have a deadline and can be scoped tightly | Domain path, campaign tracking, brand consistency, post-event redirect |
The strongest reason to migrate part of website to Astro is not “Astro is faster.” It is “this part of the site is valuable enough to improve now, but risky enough that a full rebuild should not be the first experiment.”
That is especially true for marketing teams stuck between two bad choices: patch the old platform again, or wait months for a full rebuild. A phased Astro migration gives the team a third option. Move the section where the old system is hurting growth, set up the right migration controls, and use the first release to make the larger rebuild more predictable.
Pick the first slice by business risk, not page count
Do not start with the easiest page if it teaches you nothing. Do not start with the riskiest page if the team has not tested the routing, analytics, content model, and launch process. The right first slice sits in the middle: important enough to matter, contained enough to manage.
A practical scoring model:
| Signal | Low-priority slice | Good first slice | Too risky for phase one |
|---|---|---|---|
| Traffic | Low or unknown | Meaningful traffic with clear measurement | Top organic or revenue page with no rollback plan |
| Integrations | Static content only | Simple forms, analytics, CMS content | Checkout, accounts, personalization, complex APIs |
| Content model | One-off page | Repeatable landing page or article pattern | Many inconsistent legacy templates |
| SEO risk | No ranking history | Some rankings and internal links | Major backlink hub or multilingual URL structure |
| Team learning | Little reusable value | Tests components, content, routing, QA | Requires solving the entire migration at once |
For many businesses, the first slice should be a small set of Astro landing pages or a tightly scoped resource section. Landing pages are visible enough to measure and structured enough to reuse. Resource centers are useful when the team wants better content operations and SEO structure before rebuilding the whole website.
If the first slice includes high-value organic pages, treat it like a real website platform migration, not a design refresh. The page may look simple, but the migration still has to preserve URLs, metadata, canonicals, schema, sitemap behavior, internal links, analytics events, and form behavior.
For timing and staffing decisions, pair this with the Astro migration timeline and the guide to deciding whether you need an Astro developer.
Routing is the architecture decision
Routing decides how visitors, crawlers, analytics tools, and internal teams experience the split. In a partial migration, the big choice is usually subdirectory, subdomain, or separate campaign domain.
| Routing option | Example | Best fit | Main tradeoff |
|---|---|---|---|
| Subdirectory | example.com/resources/ | SEO-sensitive sections, resource hubs, main-site landing pages | Needs reverse proxy, edge routing, or host-level rewrites |
| Subdomain | resources.example.com | Isolated docs, support centers, experimental microsites | Can create more SEO, analytics, and brand continuity work |
| Separate domain | examplecampaign.com | Short-term campaigns, events, tests | Weakest connection to the main site and easiest to forget later |
Subdirectories are usually better when the migrated section should feel like part of the same website. They keep the user path cleaner and make internal links, navigation, and brand continuity easier to reason about. The cost is infrastructure: DNS cannot route a subdirectory by itself. A subdirectory split usually needs a reverse proxy, CDN worker, or hosting rewrite rule.
Cloudflare’s Workers documentation shows one version of this pattern: serving assets from a path such as example.com/blog/* by matching the route and mirroring the desired path inside the asset directory. The exact implementation will vary by host, but the principle is stable. The edge or server layer decides which requests go to Astro and which stay on the legacy origin.
Astro configuration also has to match the routing plan. Astro’s config reference describes site as the final deployed URL used for sitemap and canonical generation, and base as the base path for deploying under a path such as /docs. It also notes that trailing slash behavior affects route matching and redirects. In plain language: choose the URL shape before launch, then make Astro, the proxy, the sitemap, and the legacy platform agree.
Subdomains are easier to isolate. They can work for documentation, internal knowledge bases, or early experiments where the team wants fewer dependencies on the legacy platform. But they add work. Navigation can feel detached, analytics can split, cookies may need extra handling, and search teams may need to watch how the subdomain performs separately from the main site.
Analytics must be rebuilt as a shared system
Analytics continuity is where many phased migrations quietly fail. The new Astro section launches, the pages load quickly, and the design looks right, but campaign reporting, conversion events, form attribution, or session behavior changes.
Before launch, define one measurement plan across both platforms:
| Area | What to verify |
|---|---|
| Page views | Page paths, canonical URLs, content grouping, and source attribution are consistent |
| Events | Form submits, CTA clicks, downloads, video plays, booking clicks, and scroll milestones fire the same way |
| UTMs | Paid, email, partner, and sales campaign parameters survive the route |
| Consent | Consent mode or privacy tools behave consistently across both platforms |
| CRM handoff | Leads arrive with the expected source, page, campaign, and form metadata |
| Dashboards | Reports do not double-count or split the same journey into two unrelated properties |
Do not treat this as a final tag copy. In a phased Astro migration, analytics is a product requirement. Someone should own the event dictionary, the naming convention, the test plan, and the post-launch comparison. If a landing page moves to Astro but marketing cannot compare lead quality before and after, the migration has lost one of its main reasons to exist.
Google’s site move guidance also calls out web analytics before a migration and recommends using analytics to review usage on both old and new sites. That advice matters even when the domain is not changing. A partial migration is still a behavior change in the website system.
Redirects and SEO need a single source of truth
Redirects are not only for the final full rebuild. Any phased Astro migration that changes URLs needs a redirect map from day one.
Google’s migration guidance is clear that old URLs should be mapped to new destinations, internal links should be updated, and server-side permanent redirects should be used where technically possible. It also warns against redirect chains and irrelevant redirects to a single page such as the homepage. For an SEO-sensitive migration, those are not nice-to-have checks. They are the launch floor.
A useful redirect map should include:
| Field | Why it matters |
|---|---|
| Legacy URL | The exact current path, including slash behavior |
| New URL | The intended Astro or retained legacy destination |
| Redirect status | Permanent for permanent moves, temporary only when the move is temporary |
| Page type | Landing page, article, category, author, service page, asset |
| Priority | Traffic, backlinks, revenue importance, campaign use |
| Canonical target | The URL the new page declares as the canonical version |
| Owner | Who approved the mapping |
| Test status | Untested, passed, failed, fixed |
During a phased migration, also decide where redirects live. Some may belong in the legacy platform. Some may belong at the CDN or edge layer. Some may belong in Astro’s config for routes Astro controls. Mixing those without a clear owner creates hard-to-debug loops and chains.
The same discipline applies to sitemaps. If Astro generates a sitemap for the migrated section while the legacy platform generates another sitemap for the old site, the root robots file and Search Console setup need to reflect the full picture. The migrated pages should appear in the right sitemap, use self-referencing canonicals, and be reachable through updated internal links.
Design consistency is operational, not cosmetic
When two platforms run at once, design consistency can decay quickly. The legacy site has its own CSS, components, image ratios, forms, spacing, and navigation patterns. The Astro section may introduce a cleaner component system. If nobody governs the overlap, the site starts to feel like two brands stitched together.
The fix is not to freeze design. The fix is to define what must be shared:
| Shared element | Practical control |
|---|---|
| Navigation and footer | One source of truth, or a scheduled parity check before launch |
| Brand colors and type | Tokens or documented variables used in both systems |
| Page sections | Reusable Astro components that match approved content patterns |
| Forms | Shared labels, validation messages, success states, and tracking |
| CTAs | Same destination logic, copy patterns, and visual hierarchy |
| Images | Shared aspect ratios, compression rules, alt text standards |
| Accessibility | Same contrast, focus, keyboard, and heading expectations |
The goal is not visual sameness at all costs. Sometimes the Astro section should be better. A high-value landing page may need tighter copy, faster load, cleaner forms, and stronger proof. But the improvement should feel intentional, not like a different vendor or platform took over one part of the site.
This is where design tokens, component guidelines, and QA screenshots help. They let the team preserve enough continuity while using the Astro migration to clean up patterns the old platform made hard to maintain.
Do not run two platforms too long
A phased Astro migration reduces launch risk, but it creates operating cost. The longer two platforms run, the more the team pays in coordination.
Common long-tail risks include:
- Navigation updates have to be made twice.
- Brand changes drift between platforms.
- Analytics logic forks.
- Redirect rules end up split across CMS, hosting, CDN, and Astro config.
- Content editors forget which system owns which page.
- Security, dependency, and hosting responsibilities multiply.
- SEO fixes happen in one platform but not the other.
- Developers avoid cleanup because “the full rebuild is coming later.”
That is why a partial migration needs an exit plan. Before phase one launches, define the expected next phase, the decision date, and the criteria for either continuing, pausing, or rolling back.
Good exit criteria include:
| Question | Continue migration if… | Pause or rethink if… |
|---|---|---|
| Performance | Core page experience improves without breaking tracking | Speed improves but conversion or tracking quality drops |
| Content workflow | Marketing can publish or update safely | Every update still needs developer rescue |
| SEO | Crawling, indexing, and internal links remain clean | Redirect, sitemap, or canonical issues keep recurring |
| Conversion | Leads, bookings, or engagement hold steady or improve | Form quality, routing, or attribution becomes unreliable |
| Maintainability | New sections reuse components and patterns | Astro becomes another pile of one-off pages |
The danger is not phased migration. The danger is an unfinished migration that becomes the new normal.
A practical phased Astro migration plan
Use this structure to keep the work honest.
Phase 1: Audit and selection
Crawl the current site, review analytics, identify organic and paid entry pages, list all forms and integrations, and choose the first slice. Include pages that teach the team something about the future platform, not only pages that are easy to rebuild.
Deliverables:
- First-slice page list
- Business reason for each page
- URL and metadata inventory
- Known forms, scripts, integrations, and events
- Rollback criteria
Phase 2: Routing and platform setup
Decide whether the section lives in a subdirectory, subdomain, or separate domain. Configure Astro around the chosen URL shape. Set up preview and staging. Confirm where redirects, headers, cache rules, and sitemap output will live.
Deliverables:
- Routing plan
- Astro
site,base, and trailing slash decision - Hosting or edge routing setup
- Staging URL
- Redirect ownership model
Phase 3: Component and content model
Build the reusable components and content structure before recreating every page. This is especially important for resource centers and landing page systems. The migration should leave the team with a better publishing foundation, not only faster HTML.
Deliverables:
- Layouts and reusable sections
- Content schema or CMS fields
- Metadata and Open Graph pattern
- Form pattern
- Image and alt text rules
Phase 4: SEO, analytics, and QA
Test the first slice like a real launch. Check page output, internal links, redirects, canonicals, sitemap entries, forms, analytics events, CRM payloads, consent behavior, performance, accessibility, and mobile layouts.
Deliverables:
- Redirect test results
- Analytics event test results
- Form and CRM test results
- SEO QA checklist
- Design parity screenshots
Phase 5: Launch, monitor, and decide
Launch the slice, monitor traffic and conversions, compare analytics to the legacy baseline, watch Search Console, and document what the team learned. Then decide whether to move the next section, fix the first slice, or stop.
Deliverables:
- Launch notes
- Post-launch issue log
- Search and analytics review
- Next-slice recommendation
- Cleanup tasks for the legacy platform
The bottom line
Partial Astro migration works best when the first release is treated as a controlled platform migration, not a side project. Move the pages where speed, content control, or SEO quality matters most. Keep routing, analytics, redirects, and design consistency under one plan. Then use the first slice to decide whether the full rebuild should continue.
If the business only needs a few disposable campaign pages, keep the setup simple. If the migrated pages carry rankings, leads, paid traffic, or editorial workflow, give them the same care as a full website migration. Astro can make the site faster and cleaner, but the migration succeeds only if the business can still measure, manage, and trust the website after launch.
