Post-Mortem: Why We Abandoned Gatsby for Next.js

The Premise

In 2021, the "Gold Standard" for static sites was Gatsby. We chose it for a large-scale corporate migration from a legacy WordPress setup. The goal was simple: Headless CMS, blazing fast static generation, and a modern developer experience.

Instead, we built a Complexity Trap.

The Mess: The "Build Tax"

As the project grew to hundreds of pages, our CI/CD pipeline started to groan. We hit a 20-minute "Build Tax" for every minor CSS change.

The HOC Pattern Failure

We were heavily using Higher-Order Components (HOCs) to inject data and layout logic. While this looked "clean" in the code, it confused Gatsby's static analysis. The compiler ended up invalidating the cache and re-generating the entire site twice per build.

The GraphQL Overhead

We used GraphQL to consume data from the WordPress API. While the "Type Safety" was nice, the cognitive load of managing fragments and complex schemas across 50+ components was slowing down the team. We were spending 40% of our time debugging the data layer instead of building features.

The Pivot: Next.js and the Return to Simplicity

We realized that "Modern" doesn't always mean "Productive." We made the high-stakes decision to migrate to Next.js mid-project.

1. Ditching the GraphQL Middleware

We moved back to standard REST fetches. By removing the GraphQL abstraction, we eliminated a massive failure point. The team could now see exactly where data was coming from using standard browser network tools.

2. Standardizing the Toolchain

We replaced the HOC pattern with React Composition and Custom Hooks. This made the build process deterministic. Next.js's "Incremental Static Regeneration" (ISR) allowed us to move from 20-minute full builds to 1-second updates for content changes.

Engineering Lessons Learned

1. Avoid Resume-Driven Development: We chose Gatsby and GraphQL because they were "cool." A Senior Architect chooses tools based on Team Velocity and Build Determinism.
2. Beware of Abstractions: Every layer (like a GraphQL middleware for a REST API) is a potential performance bottleneck and a debugging nightmare.
3. The "Cleanup" Mindset: Sometimes the best engineering is knowing what to remove. By deleting Gatsby and GraphQL, we improved performance by 400% and team happiness by even more.

Final Result

• Lighthouse Score: Jumped from 45 to 98.
• Build Time: Reduced from 20m to < 2m.
• Maintenance: Onboarding a new dev now takes hours, not days.

If you're currently fighting a "Build Tax," it might be time to stop adding features and start auditing your architecture.