Why We Moved off Next.js

Join the conversation on X: https://x.com/documenso/status/1907019629652058196

When we started building Documenso, choosing Next.js was a no-brainer. We wanted SSR (server-side rendering), easy routing, and the vibrant community that came with it. It helped us ship fast, iterate quickly, and provided all the essentials in one neat package. For a while, it was exactly what we needed.

Early Adoption and Growing Pains

But as we grew, we started adopting some of Next's newer features specifically, the App Router and Server Actions. Initially, these felt promising. Server Actions, for instance, seemed to simplify interactions without needing separate API routes. The App Router made structuring our app intuitive. We were excited early adopters, eager to leverage cutting-edge tech.

But soon, things got messy.

We ran into consistent issues with debugging and monitoring Server Actions, which became opaque and tricky to track. Worse yet, we encountered bizarre build failures like mysterious async chunks breaking our builds, causing deployment delays and developer frustration. These issues eventually led to us moving off server actions and embracing the simplicity that is tRPC.

After switching things were fine for a while, but over time our developer experience started to take a nose dive.

Hot module reload (HMR) times ballooned from a tolerable few seconds to upwards of 45 seconds, breaking our productivity and dampening morale. Small features and PR reviews stretched painfully as the run, change, test cycle ballooned out with the worsening dev server experience.

The Next.js team had acknowledged these issues that were widespread across a number of projects and promised that changes were coming to fix this. These changes eventually lead to Turbopack, the purported successor to Webpack. Eager to resolve our development environment issues we had tried Turbopack several times both during it’s beta and full release wasting hours and encountering multiple errors that made it a non-starter during each case.

Making the Switch to React Router

By early 2025, we'd had enough.

We made the decision to move from Next.js to React Router. Why React Router? For starters, it's rather straightforward and transparent with a lot less magic, just explicit routing and easy-to-follow logic. React Router is the next iteration of Remix, giving us confidence in its direction and long-term viability.

With this, we executed a quick "lift and shift" same app, no new features, just swapping out the underlying framework. The migration was surprisingly smooth and immediately impactful.

We had encountered a small amount of pain due to the latest version of React Router not being super well supported yet, particularly on the framework side of things in addition to LLM’s knowing less about these recent developments but other than that we have nothing but praise for the React Router/Remix team.

Smooth Sailing with Vite

With the move to React Router, we're now leveraging Vite for bundling, and it’s transformed our workflow completely.

Development feels almost instant. Our dev servers refresh so fast, they're practically indistinguishable from running a production build. We’ve regained momentum, joy, and most importantly, productivity.

The decision allowed us to re-evaluate some of our data-fetching approaches, opting to move specific fetches to the client side. This lets us to ship suspense boundaries and loading skeletons directly within our initial client-side bundle, leading to smoother loading states and better perceived performance. This is possible with Next.js but we opted to use loading.tsx which seems to prefetch and “snap in”.

Another major benefit of switching to Vite has been access to its extensive plugin ecosystem. We now have the flexibility to manage our build and bundle the way we see fit allowing us to make even further improvements to our already speedy build at a later point.

Thoughts on Next.js Moving Forward

While Next.js is undoubtedly great for docs, e-commerce, and content-driven sites, we’ve found its recent trajectory challenging particularly for full-scale applications. The declining developer experience over the past year has forced our hand. If we're to consider Next.js again for future projects, significant improvements around performance, stability, and developer tooling would be essential.

For now, the simpler future for Documenso is React Router and Vite and we couldn't be more excited about what's ahead.