Gatsby to Next.js Migration Checklist

A Gatsby to Next.js migration should start with route, content, and rendering parity, not component rewrites.

The visible work is tempting. Teams want to replace templates, simplify components, remove old plugins, and modernise the codebase. That work matters, but it is not where most migration damage starts.

The expensive failures are quieter. A URL changes without a redirect. A canonical points at the wrong host. A GraphQL query used to include a field that the new data layer forgets. Image handling changes social previews. Draft content cannot be previewed. A sitemap drops important routes. A plugin used to generate pages, feeds, or metadata and nobody notices until launch.

This checklist is for teams planning a Gatsby to Next.js migration where search visibility, editorial workflow, and platform stability matter. The aim is not to keep every Gatsby behaviour. It is to decide what must survive and what should be simplified.

Build a Route Inventory First

Before touching the Next.js implementation, list the current Gatsby route estate.

Include static pages, programmatic pages from createPages, articles, category routes, tag routes, pagination, redirects, legacy paths, XML, and text sitemaps, feeds, static files, and any unusual paths created by plugins. Compare the inventory with the live route set, analytics landing pages, Search Console data, and the pages the business actually cares about.

For each route, decide:

• keep the same URL
• redirect to a new URL
• consolidate into a stronger page
• remove because the route is genuinely obsolete
• rebuild later because it is not launch‑critical

Google's site move guidance is worth reading even when the domain is staying put, because URL mapping, redirects, canonicals, and testing are still the work that prevents avoidable migration loss.

Choose the Rendering Strategy Route by Route

Gatsby usually pushed teams towards static generation for almost everything. Next.js gives you more options.

That does not mean every route should become dynamic. It means each route should have a clear reason for its rendering model. Some pages can stay static. Some can use Incremental Static Regeneration. Some may need server‑side rendering. Some can be generated on demand. Some interactive parts belong on the client, but the page's core content should still be available in useful HTML.

The Next.js ISR documentation is useful for content‑heavy Pages Router sites because it explains how static content can update without rebuilding the whole site. If the site is hosted on Vercel, the hosting‑side cache and revalidation behaviour also needs to be understood.

Map the strategy before implementation:

• article pages
• service or landing pages
• category and pagination pages
• frequently updated CMS pages
• preview routes
• redirects and error pages
• API routes or feed generation

The wrong rendering decision can recreate the Gatsby problem inside Next.js.

Replace Gatsby's GraphQL Data Layer Deliberately

Gatsby's data layer is one of its biggest migration boundaries.

The Gatsby GraphQL data layer documentation describes the central model: source plugins create nodes, Gatsby infers or builds schema, and pages query that graph. Next.js does not have that global data layer. You choose the data access pattern.

That means every Gatsby query needs a migration decision:

• fetch directly from the CMS
• read generated local data
• call an internal API
• move transformation into a build script
• simplify because the old query carried unused fields
• split because one query was doing several jobs

Do not mechanically recreate a site‑wide GraphQL layer unless the new architecture genuinely needs it. Many migrations become cleaner when each route owns a smaller, typed data contract.

This is also the point to decide whether the CMS should change. If Gatsby is tightly coupled to Contentful and the migration is also a chance to move to Sanity, keep the CMS work visible. Hiding a Contentful to Sanity migration inside a framework migration is how scope and launch risk get blurred.

Audit Gatsby Plugins Before Replacing Them

Gatsby plugins can hide more behaviour than teams remember.

One plugin may source content. Another may create image data. Another may generate redirects, manifests, feeds, robots rules, sitemaps, metadata, offline support, analytics, or Contentful rich text rendering. Some of that behaviour needs a Next.js equivalent. Some of it is legacy weight.

Create a plugin table with four columns:

• what the plugin currently does
• which pages or outputs depend on it
• whether the behaviour is still needed
• where the replacement belongs in Next.js

This is where old Gatsby sites often become easier to maintain. Removing plugin behaviour that nobody needs is part of the migration value.

Rebuild Image Handling with Output Parity

Gatsby image handling is usually deeply embedded in templates.

The Gatsby image plugin documentation explains a model built around image data, transformations, placeholders, and responsive output. In Next.js, image handling may move to next/image, CMS image URLs, custom loaders, or a different asset pipeline.

Check the output, not just the component API:

• image dimensions
• alt text
• responsive sizes
• loading behaviour
• social images
• structured data images
• image URLs that may be indexed or shared
• build‑time image processing cost

Do not let the migration silently remove meaningful alt text, credit data, or image dimensions. Those details affect accessibility, SEO, layout stability, and editorial trust.

Preserve Redirects, Canonicals, and Metadata

Gatsby sites often contain redirect and metadata logic in several places: config files, plugins, generated files, CMS fields, template helpers, and hosting rules.

Next.js centralises some of this, but not all of it. The Next.js redirects configuration is useful for application‑level redirects, whilst hosting‑level redirects may still be more appropriate for some cases.

Before launch, compare old and new output for priority templates:

• HTTP status
• redirect target
• canonical URL
• <title> and meta description
• robots meta tag
• Open Graph metadata
• JSON‑LD structured data
• visible h1
• internal links

If a route changes, the redirect should preserve intent. Sending detailed Gatsby pages to a generic Next.js page can look tidy in a spreadsheet whilst damaging search relevance.

Rebuild Preview as Part of the Migration

Preview is not a nice extra for content‑heavy sites. It is part of the publishing workflow.

If Gatsby preview was slow, partial, or unreliable, do not copy that weakness into Next.js. Define how editors will preview draft content, which content types have direct preview routes, how supporting entries are previewed, and what happens when required fields or slugs are missing.

For headless CMS sites, this often means using Draft Mode, preview‑specific data fetching, auth, cookies, iframe policy, and safe preview URL validation. The migration should also make clear whether the site will keep the same CMS, move to a new CMS, or split that work into a separate phase.

The CMS preview migration requirement article goes deeper into this because preview is one of the first places editors notice whether a migration has actually improved their day‑to‑day work.

Recreate Generated Outputs Intentionally

Gatsby projects often rely on generated outputs beyond pages.

Check:

• sitemap.xml
• robots.txt
• llms.txt or other AI‑facing policy files if present
• urllist.txt
• RSS or Atom feeds
• search indexes
• manifests
• image metadata
• valid‑route data
• redirects
• static files

In a Next.js migration, generated outputs should come from clear source data. Do not leave them as manual files unless the site intentionally owns them that way. If sitemap or robots output changes, validate it against the live route set. That is exactly the sort of issue covered by Next.js sitemap and crawlability debugging.

Validate SEO from Rendered Output

SEO validation should use the built or deployed output, not the component tree.

Before launch, crawl the old and new estates where possible. Compare route status, titles, descriptions, canonicals, headings, internal links, schema, image metadata, robots directives, sitemap inclusion, and important body copy. The article on traffic drops after a replatform covers the recovery version of this work, but the same checks belong before launch.

If the migration affects commercially important pages, technical SEO recovery and debugging should not be treated as an emergency‑only service. The best recovery work is the work you do before the drop happens.

Plan Deployment and Rollback

A Gatsby to Next.js migration changes more than framework code.

It can change build commands, environment variables, Node versions, hosting behaviour, redirects, cache rules, preview domains, image settings, serverless functions, and release ownership. Vercel can be a good fit for many Next.js sites, but the deployment model still needs explicit checks. This is why deployment debugging often sits close to migration work, especially when the move also changes hosting, cache rules, serverless behaviour, or preview domains.

Before launch, document:

• build and runtime environment variables
• CMS tokens and preview tokens
• redirect ownership
• cache and revalidation behaviour
• rollback steps
• post‑launch search, analytics, and error monitoring
• who can pause the launch

The launch should be uneventful because the risky decisions have already been made.

Wrapping Up

A Gatsby to Next.js migration is safer when it starts with the behaviours the site must preserve.

Routes, rendering strategy, data sourcing, plugin replacement, images, redirects, canonicals, metadata, sitemaps, preview, and deployment all need explicit ownership. Component migration matters, but it is only one part of the move.

The practical test is simple: after launch, users should find the same or better pages, editors should trust the publishing workflow, and engineers should have a clearer platform than the one they left behind.

Key Takeaways

• Start with route and content parity before rebuilding components.
• Choose Next.js rendering strategies route by route.
• Replace Gatsby GraphQL and plugins deliberately, not mechanically.
• Validate images, redirects, canonicals, metadata, sitemaps, and preview as migration requirements.
• Use rendered output checks before launch, not only source‑code review.