Why We Migrated Our Blog From Gatsby to Next.js and How You Can Too

When we first launched the Flotiq Blog, Gatsby seemed like the perfect choice. It's a static site generator and focuses on performance aligned with our vision for a fast, reliable platform. But as Gatsby’s limitations became more apparent, particularly its declining relevance as a technology and the challenges we faced with content updates, we realized it was time to reevaluate our approach. This is the story of how we transitioned from Gatsby to Next.js, the issues that prompted the move, and why this migration transformed our blog for the better.

The Road to Migration: Why migrate from Gatsby to Next.js

At Flotiq, we’re always looking for ways to improve - whether it’s enhancing our product, refining processes, or adopting better technology. Initially, Gatsby worked well for our blog. It was fast, simple, and had a vibrant ecosystem of plugins. But over time, cracks started to show.

The Decline of Gatsby

Gatsby, once a favorite among developers for building static sites, has been losing traction in 2024. On the below visual from StateOfJs, you can observe change of sentiment among the dev community for Gatsby and Next.js. While Gatsby sentiment goes down year to year, Next.js grows, not only with positive sentiment but also with the number of people using it. Also community shifts towards Next.js, which is visible in growing resources and toolkits around Next.js.

Source: https://2024.stateofjs.com/en-US/libraries/

Here’s a more detailed breakdown:

1. Evolving Priorities:

After Netlify’s acquisition of Gatsby, the framework’s development trajectory shifted. With a focus on integrating with Netlify’s ecosystem, Gatsby’s innovation appears to be gone. Throughout the entire 2024, we’ve seen only 1 minor update in the 5.x branch, and even that consists mainly of bumped dependencies and small fixes:

This raises serious concerns about Gatsby’s long-term viability and relevance for projects like ours. Many developers have already moved on to frameworks like Next.js, which offer greater flexibility and performance for modern web applications.

2. Dynamic Content Limitations and unreliable Preview mode

As we expanded, we needed a way to handle dynamic routes and real-time content updates. Gatsby’s reliance on static generation made this cumbersome. Each post change/publication required a build on production, which added 5 min to see each change.

Gatsby’s Preview mode required deploying a separate Gatsby site in development mode, which often proved unstable and cumbersome to manage. This lack of a reliable and straightforward preview solution made content updates and collaboration with our team more challenging, ultimately pushing us to seek a more robust alternative. The time needed to regenerate static pages after each content update was just too long for an effective editorial workflow.

3. Plugin Overload

Gatsby’s plugin ecosystem is both a strength and a weakness. Managing and updating Gatsby plugins became a noticeable overhead, in several cases plugin versions were not compatible with each other, similar to the situation happening in the Wordpress plugin ecosystem. Of course, overall the plugin system offered by Gatsby is far more stable than WordPress.

Why Next.js Stood Out

Next.js emerged as the clear winner for our needs. It’s backed by Vercel, has a robust community, and offers the hybrid rendering approach we needed - SSG, SSR (server-side rendering), and even ISR (incremental static regeneration), all in one package. With Next.js, we saw the opportunity to create a blog that was more flexible, easier to maintain, and better aligned with the evolving needs of modern web development.

The Migration: Step-by-Step Guide to Migrate from Gatsby to Next.js

At first, our dev team approached this with reservations, as every migration, the project had some risks, and there was some internal pressure from our Growth team to deliver the new Blog before Christmas. However, after breaking down the migration and realizing that most of the content remains untouched, developers grew more confident that this can actually work. After all, having the ability to easily change frontends is one of the selling points of headless CMS!

Here’s how we tackled this project:

1. Assessing the Existing Site

The first step was understanding what we had. We analyzed the structure of our Gatsby blog, noting critical components like:

• Routes: Static and dynamic pages.
• Content: Pulled from Flotiq, our headless CMS.
• SEO Elements: Titles, meta descriptions, and Open Graph tags.

2. Setting Up a New Next.js Project

We created a fresh Next.js project and configured it to work seamlessly with Flotiq. Thanks to Next.js’s flexibility, this was straightforward. We used npx create-next-app to get started and integrated Flotiq using its API.

3. Migrating Routes and Page Creation

Routes in Gatsby can be created both programmatically as well as using static files. Because of that, it’s not necessarily obvious how to identify all existing routes in your project. To have 100% certainty that we didn’t lose any page, we ran Gatsby’s local development server and connected to the GraphQL API interface to fetch the results of this query:

{
  allSitePage {
    nodes {
      path
      component
    }
  }
}

  This returns a list of all pages in a Gatsby project, along with the path of JS file that was used as the template to generate each page, like this:

{
  "data": {
    "allSitePage": {
      "nodes": [
        {
          "path": "/",
          "component": "/Users/MyUser/Desktop/flotiq/flotiq-blog/src/templates/index.js"
        },
…

We took this output and ran it through a simple piece of JavaScript to obtain a list of pages organized by template name:

const getRoutes = (pages) => {
  const uniqueRoutes = [];
  const basePath = 'flotiq-blog';
  pages.forEach((page) => {
    
    const relPath = page.component.substring(page.component.indexOf(basePath) + basePath.length+1);
    const arrayKey = relPath === "//" ? "/" : relPath;
    if(typeof (uniqueRoutes[arrayKey]) === 'undefined' ){
        uniqueRoutes[arrayKey] = [];
    }
    uniqueRoutes[arrayKey].push(page.path);
  });
  return uniqueRoutes;
};

console.log(getRoutes(allSitePage.data.allSitePage.nodes));

which returns the following hierarchy:

That helped us tremendously when creating routes and template files. For each template, we had to analyze the React components used and adapt them to match Next.js conventions and requirements.

4. Transferring SEO Metadata

Preserving our SEO was a top priority. We ensured all meta tags, titles, and descriptions were correctly migrated to Next.js using the generateMetadata function. By maintaining the same URLs, we avoided breaking backlinks or losing traffic.

5. Data Fetching with Flotiq

Gatsby’s approach to data fetching is a 2-step process:

• Data has to be fetched from the source (in our case, Flotiq, using our source plugin gatsby-source-flotiq) into Gatsby’s internal GraphQL server
• GraphQL queries are made from templates to fetch the data, so it can be displayed

It’s nice for people who prefer GraphQL, but also a bit complicated at times.
In our Next.js setup, we decided to simplify this, so our developers have more control over the data fetching process, and also to easily get a fully typed API.
Using Flotiq codegen SDK for Typescript, we were able to develop quickly, with intuitive code completion and syntax highlighting in our IDE. This is a major step forward in terms of developer experience.

6. Testing and Optimization

Before deploying, we rigorously tested the new blog. We checked:

• Page load times and performance using Lighthouse and https://pagespeed.web.dev/.
• SEO elements using tools like Google Search Console.
• Compatibility across devices and browsers.

7. Deployment

Finally, we deployed the new blog to Vercel, taking advantage of its automatic builds, previews, and fast global CDN.

The Benefits of Migrating Gatsby to Next.js

Switching from Gatsby to Next.js brought immediate and long-term advantages:

1. Faster Build Times and scalability

With Server-side Rendering (SSR)and selective cache revalidation, we no longer rebuild the entire site for each update. This made updating the content frictionless. As our content grows, we can confidently scale without worrying about build bottlenecks or performance drops.

2. Dynamic Content Made Easy

Next.js’s hybrid rendering lets us combine static pages with server-side rendering for dynamic content. This made it easier to keep our blog fresh and responsive.

With Gatsby, publishing or updating a single blog post was a tedious process. Each change required a full deployment to production, which could take around 5 minutes or more, depending on the content. This meant delays and interruptions, especially for quick updates or time-sensitive posts.
With Next.js, the process is seamless - updates are triggered by a simple webhook that refreshes the cache almost instantly. This efficiency has not only saved us time but also made our workflow far more dynamic and responsive.
Here’s how we configured it in Flotiq:
 

3. Improved SEO

In our previous setup, we used Gatsby with Cloudflare Pages to squeeze the best performance possible for our readers. We still recommend Cloudflare Pages, but we’ve seen many error reports when the pages were not rendered properly (and based on these Github discussions, we’re not alone) in this setup. Specifically, it seemed to impact the indexing of our blog by Google, especially combined with the fact that we were hosting the blog in a sub-path (flotiq.com/blog/). At some point, we even migrated the blog to a separate domain (blog.flotiq.com) to help solve these issues, without much improvement.

4. Simplified Maintenance

Without the plugin dependencies of Gatsby, updates and troubleshooting are now simpler and quicker.

Key Considerations to keep in mind when migrating from Gatsby to Next.js

If you’re planning a similar migration, keep these points in mind:

1. Preserve Your URLs: Maintaining your existing URL structure is essential for SEO and avoiding broken links.
   
2. Focus on Metadata: Ensure all titles, descriptions, and Open Graph tags are correctly migrated.
   
3. Test, Test, Test: Validate every page and feature to avoid surprises post-deployment.
   
4. Leverage Your CMS: Having a headless CMS backend makes it easy to replace the frontend technology without changes to the data.

Next.js and Flotiq: A Perfect Match

The combination of Next.js and Flotiq proved to be a winning formula. Next.js’s modern features, combined with Flotiq’s flexible headless CMS capabilities, allowed us to create a blog that’s fast, scalable, and easy to manage. Whether you’re starting a new project or considering a migration, this duo is ideal for building robust, future-proof websites.

Ready to make the switch? Explore Flotiq and unlock the full potential of Next.js for your next project!

Any questions? Write to us at [email protected]