Decision record // Architecture
Next.js route handlers or a separate backend?
Everything in one Next.js app, or a separate API that the front end talks to. This gets argued as though it were a permanent architectural commitment. It is closer to a packaging decision, and it is reversible if you set it up so.
The call
Route handlers, until you have a second consumer or work that outlives a request. But the choice matters far less than where you put the logic, and that is the part almost everyone gets wrong.
When each one is right
Route handlers
- One web client, with no mobile app or public API committed for this year.
- The work fits inside a request: read, write, call something, respond.
- A team small enough that one deploy for everything is a feature rather than a constraint.
A separate service
- A second consumer exists or is committed: a mobile app, a partner API, a CLI.
- You have work that outlives a request. Video processing, large imports, anything measured in minutes.
- You need a runtime Next does not give you cheaply: persistent websockets at volume, sustained CPU, or a language with better libraries for the job.
- Deploy cadence needs to differ. Changing marketing copy should not redeploy the thing that takes payments.
What it costs you later
The switch is cheap when your route handler is three lines of transport wrapped around a plain function, and miserable when the business logic lives inside the handler. Write handlers that parse the request, call a function which knows nothing about HTTP, and serialise the result. Do that and moving to a separate service is largely copying files. Skip it and your domain logic is welded to a framework's request object, and the migration everyone told you would be easy turns into a rewrite. This is the single highest-leverage habit in the whole decision, and it costs nothing to adopt on day one.
Decisions like this one, on your product
This page is a general answer. Yours has constraints I don't know about. The Founding Engineer is 8 weeks with 5 founders where we make these calls on your actual codebase, and your code gets reviewed every week.
New decision records as I write them
One question, one answer, no hedging. Leave your email and I'll send the new ones. No schedule promises, unsubscribe anytime.