Build without breaking a running dev server

The symptom

A dev server that was working starts throwing Cannot find module './NNN.js' — a numeric chunk filename you have never seen and cannot grep for. Pages that rendered a minute ago return 500s. Restarting the dev server fixes it, right up until the next build.

The tell is the timing: it starts the moment somebody runs a production build in the same checkout.

Why it happens

Both commands use .next/ as their output directory, and the build rewrites it. The dev server is holding references to chunk files by hashed name; the build removes and regenerates those files with different hashes; the next request asks for a module that no longer exists. Nothing is corrupted in any interesting sense — two processes are simply writing to the same folder.

The fix

Make the output directory configurable, defaulting to the normal one:

// NEXT_DIST_DIR lets a build run isolated from the .next/ that concurrently
// running dev servers depend on (this repo gets edited by parallel sessions).
// Unset in normal dev/deploy, so Vercel and `next start` see no change.
distDir: process.env.NEXT_DIST_DIR || ".next",

Then build into a scratch directory whenever something else is running:

NEXT_DIST_DIR=.next-verify npm run build

Four lines of config, and the dev server never notices. Add the directory prefix to .gitignore — these outputs are disposable, and you may end up with several.

When this earns its keep

Any time a build and a dev server share a checkout. That is most obviously two people on one machine, but the case that made it necessary here is parallel agent sessions working in the same repository — each one wanting to verify its own changes with a production build while another is still serving the site locally.

It also makes the build safe to run as a routine check rather than an event, which matters when the check is the thing enforcing a standard — like reading First Load JS out of the route table after every change. A verification step nobody can run without disrupting someone else is a verification step that quietly stops happening.

Small workflow frictions like this compound quietly across a project. Removing them is unglamorous and it is most of what makes a long engagement stay quick.

Questions