From Monolith to Monorepo: A Next.js Migration Story

The white cursor in VS Code blinked silently, but no type hints appeared. My coworker's frustrated sigh echoed through our Slack call – his older machine had finally given up on TypeScript suggestions entirely. After a year of building our Next.js application, we'd hit a wall I'd been dreading: our monolithic codebase had become too large for comfort.

The Monolithic Beginning

When I first started this project, Next.js seemed like the perfect choice. Coming from a background in plain React SPAs with React Router and Express – and even earlier experiences with PHP – the idea of colocating server and client code felt intuitive. Following conventional wisdom, we organized our code by functionality rather than technical concerns. Authentication, prospects, accounts, team features – each lived in its own module, complete with its own types, utilities, constants, and server-side code.

"It was beautiful at first," I remember thinking during those early months. Working on the accounts module meant everything you needed was right there – components, hooks, tRPC functions, even Prisma files – all within a single folder. It was the developer experience I'd always wanted.

The Cracks Begin to Show

Seven months in, the first warning signs appeared. TypeScript's language server began to struggle, suggestions emerged slower and slower, and build times crept upward. While my powerful development machine could still handle it, my colleague's older hardware surrendered completely to the complexity.

We faced a classic engineering crossroads: throw money at the problem or invest engineering hours to solve it properly. Sure, we could upgrade our hardware – TypeScript performance only impacts development, not production. But something about that solution felt like a band-aid. We chose the harder path: refactoring our monolith into a monorepo using Turborepo.

The Migration Journey

The first step was surprisingly straightforward – migrate the structure without splitting any code. I created an apps folder containing our web app and added two standard Turborepo packages for ESLint and TypeScript configuration. But the real test would be moving our core functionality while preserving type inference.

I started with our database layer, moving all Prisma-related code into its own package. After some package.json export tweaks, I held my breath and checked the types in our main app. They worked perfectly. Even better, when my colleague pulled the changes, he got IntelliSense suggestions for the first time in weeks. We were onto something.

Next came tRPC, which seemed logical – another self-contained piece of server-side functionality. But here's where things got interesting. What started as "just moving tRPC" cascaded into a series of unexpected dependencies:

• Integration libraries I'd built
• A mailer system built with MJML and React templates
• Trigger.dev workflows split between v2 and v3

The Lessons Learned

This migration taught me several crucial lessons about architecture and development practices:

1. Server-Client Separation Matters: While Next.js makes it easy to mix server and client code, that convenience can lead to messy architectures. I found myself importing types and constants across boundaries without thinking about the implications.

2. Start With Monorepo: If I were starting again today, I'd begin with Turborepo from day one. It adds minimal complexity while forcing you to think about dependencies and architecture in a healthy way.

3. Explicit Dependencies Are Better: Breaking up the monolith forced us to visualize and question our dependency relationships. Are these connections necessary? Have we created circular dependencies? These constraints pushed us toward better architectural decisions.

The Road Ahead

The migration isn't complete yet. Our server code and shared utilities still need proper organization, and we're rethinking our module structure now that tRPC and database layers live separately. But already, our development experience has improved dramatically.

For anyone building a Next.js application that might scale, consider starting with a monorepo structure. The initial investment is minimal, but the architectural guardrails it provides are invaluable. Your future self – and your team's older laptops – will thank you.

The above is the detailed content of From Monolith to Monorepo: A Next.js Migration Story. For more information, please follow other related articles on the PHP Chinese website!