Skip to content
Tutorials Center
My learning

Topics

Lesson 33 of 36 ยท Deployment and Migration

Upgrading Gatsby and Migrating to Another Framework

Plan a Gatsby major upgrade, judge the project's maintenance status honestly, and map Gatsby concepts to Next.js and Astro for a safe, step-by-step migration.

Software projects live and age. Two questions come up for every long-running Gatsby site: how do we upgrade to the current version, and should we stay at all? This lesson gives you a practical method for both. It also gives a candid picture of where Gatsby stands, so you can decide with facts.

Where Gatsby stands

Gatsby was one of the most popular React site generators in the late 2010s. In 2023 the company was acquired by Netlify, the commercial Gatsby Cloud product was wound down, and the pace of releases and community plugin updates has slowed since. The framework still works, many production sites run on it, and Gatsby 5 is a stable, well-documented release. But a few things deserve attention when you plan long-term:

  • Some community plugins are no longer maintained, and may not support the newest React or Node versions.
  • Competing frameworks (Next.js, Astro, Remix and others) have strong momentum and large ecosystems.
  • Build time on very large sites is a known weak point, as you saw in build caching.

None of this means "rewrite immediately". A working site with a small team can stay on Gatsby for years. For a new project, weigh the trade-offs honestly (see the end of this lesson).

Upgrading between major versions

Each Gatsby major release comes with a migration guide. The method is the same every time:

  1. Read the official migration guide for your version jump, and do one major at a time (4 to 5, not 3 to 5).
  2. Get a green baseline: make sure the site builds and tests pass before you touch anything. Create a branch.
  3. Update Node to a supported version first. Gatsby 5 requires Node 18 or newer.
  4. Upgrade packages together: gatsby, gatsby-plugin-* and gatsby-source-* packages must be on versions that declare compatibility with the new major (check each plugin's peerDependencies). A tool such as npx npm-check-updates helps list candidates.
  5. Fix breaking changes from the guide, then build.
  6. Clean and rebuild: gatsby clean, then a full build.
  7. Compare output: crawl both builds and compare the list of URLs, titles and key content.

Typical breaking changes in Gatsby 4 to 5 migrations include: React 18 required, Node 18 required, the gatsby-plugin-image and sharp packages moving to new majors, GraphQL sort and group syntax changes (for example sort: { fields: [frontmatter___date], order: DESC } became sort: { frontmatter: { date: DESC } }), and the removal of long-deprecated APIs such as gatsby-plugin-react-helmet (replaced by the Head API). A codemod is available for many of these changes, run with npx gatsby-codemods.

JS Stand-in: a tiny codemod for the sort syntax

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Migrating to another framework

If you decide to move, do it as a gradual project, not a big bang. First map the ideas:

Gatsby Next.js (App Router) Astro
src/pages file routes app/**/page.js src/pages
createPages + templates generateStaticParams getStaticPaths
GraphQL data layer fetch/fs in server components Content Collections
gatsby-plugin-image next/image astro:assets Image
Head API metadata export <head> in layouts
gatsby-plugin-mdx @next/mdx @astrojs/mdx
Functions in src/api Route Handlers Endpoints / adapter functions
DSG / SSR ISR / dynamic rendering output: "server" / hybrid

Content in Markdown or MDX with front matter is the most portable part. Plan to keep it untouched and change only the code around it. The GraphQL layer, by contrast, has no equivalent: each query becomes a function that reads files or an API directly.

A migration plan that works

  1. Inventory: list pages, templates, plugins and data sources. Count which plugin features are used.
  2. Freeze URLs: export every URL from the sitemap. The new site must serve the same paths (or redirect them).
  3. Port the content layer first: write a loader that reads the same Markdown and front matter.
  4. Port templates one at a time, starting with the simplest, and compare rendered HTML.
  5. Replace plugins with built-in features or small modules.
  6. Test: compare URL lists, titles, descriptions, canonical tags, structured data and the sitemap with a crawler. Compare Lighthouse scores.
  7. Launch with redirects in place (see Redirects), watch Search Console for errors, and keep the old build deployable for a quick rollback.

The URL comparison is easy to automate; this stand-in shows the idea.

JS Stand-in: compare URL lists before launch

Press Run (or Ctrl + Enter) to see the console output here.

No output.

The line labelled missing should be empty before you launch. Any URL there needs a page or a redirect.

Should you choose Gatsby for a new project?

Gatsby remains a good fit when you want a content-heavy static site, enjoy a GraphQL data layer, and rely on plugins that are still maintained. Consider alternatives when you need very fast builds at huge scale, tight integration with a platform that has first-class support for another framework, or a larger pool of up-to-date plugins and tutorials. Whatever you choose, the skills in this course (data sourcing, templates, image optimization, rendering modes, SEO) carry over directly.

Common mistakes

  • Skipping a major version and fixing a flood of errors at once.
  • Upgrading Gatsby but leaving old plugin majors in package.json.
  • Migrating without freezing URLs, then losing search traffic.
  • Rewriting content, not just code: it multiplies the work and the risk.

Check your understanding

Quick check ยท 3 questions

of 3 answered You scored / 3 ยท perfect!

  1. 1. What is the safest way to move from Gatsby 3 to Gatsby 5?

    One major at a time keeps each set of breaking changes manageable.
  2. 2. Which part of a Gatsby site is usually the most portable to another framework?

    Plain content files do not depend on Gatsby.
  3. 3. What must be true before launching a migrated site?

    Missing URLs lose traffic and rankings.

Summary

  • Gatsby 5 is stable, but its ecosystem moves slowly; judge plugin health before relying on it.
  • Upgrade one major at a time with the official guide and codemods; keep plugin majors in step.
  • Map Gatsby concepts to your target framework, keep content as-is and freeze URLs.
  • Compare crawls, add redirects, and keep a rollback path.

Next: Project: a Markdown blog