Skip to content
AtlasAtlas CMS Docs
Delivery API
Before you plan around a feature, check the capability status.

MigrateMoving to Atlas

Step-by-step migration

Move an existing website to Atlas one page type at a time, without changing how it looks and without downtime.

The safe way to move is gradual. Your public website keeps running unchanged while you connect and check each part in Development.

The rules that keep it safe

Section titled “The rules that keep it safe”
  • The design must not change. Every page must look identical whether Atlas has content for it or not.
  • Fallback is mandatory. If Atlas is unreachable or has nothing published for a page, the site serves its built-in content.
  • Text, never HTML. CMS values render as text or through your components.
  • Development first. Nothing reaches Production until a release passes its checks and a person approves it.

Stage 1: connect one page (about a day)

Section titled “Stage 1: connect one page (about a day)”
  1. Create the site in Studio and draft a minimal contract with one page type.
  2. Follow Connect a Next.js website.
  3. Publish that one page in Development and compare it with the live page.

Done when the page renders from Atlas, looks the same, and still works with Atlas switched off.

Stage 2: model the whole site

Section titled “Stage 2: model the whole site”
  1. List every route the site serves and map each to a page type.
  2. Write the contract bundle: components with typed fields, page types with their regions, collections, media profiles and the header and footer globals. Keep it in your repository as atlas/contract.bundle.json.
  3. Validate and propose it. A site admin activates it in Studio (Site setup).
  4. Refactor each page component so Atlas sections decide order and content, with the built-in data as fallback.

Done when Studio shows the website In sync with the active contract.

Stage 3: move content and images

Section titled “Stage 3: move content and images”
  1. Upload images with the right media profile. Never stretch or upscale; list the ones that do not fit.
  2. Create entries for every repeating item, referencing images by asset id, with alt text.
  3. Fill the header and footer globals with today’s content.
  4. Create a page for every route from its page type and adjust its sections until the draft matches today’s page.
  5. Draft translations, and have a native speaker review them.

An AI coding agent connected over MCP can do most of this as drafts. A person checks each page with Preview on website and publishes it.

Stage 4: refresh, SEO and redirects

Section titled “Stage 4: refresh, SEO and redirects”
  • Add the webhook receiver so publishing updates the site within seconds.
  • Read SEO titles, descriptions and noindex from the Delivery API, and build the sitemap from /routes.
  • Load /redirects and apply them, so old URLs keep their rankings.

Stage 5: go live

Section titled “Stage 5: go live”
  1. Train editors on Studio, drafts, preview and publish.
  2. Build a release. Atlas checks the contract is in sync, there are no publish problems, the website is healthy and a backup is recent.
  3. A person with approval rights approves it. A site admin switches Production on and you create a Production delivery token.
  4. Deploy your website with the Production token. Keep the fallback in place.

Rolling back

Section titled “Rolling back”
  • A content mistake: roll back to an earlier revision, or an earlier Production release.
  • A code mistake: redeploy your previous website build, as you do today.
  • Atlas unavailable: the fallback serves built-in content until Atlas is back.