The Compiler Was Green. There Was Nothing to Deploy.

The Compiler Was Green. There Was Nothing to Deploy.

A metadata cleanup on a Next.js site had passed every focused check. Types fine, lint fine, unit tests fine. The one thing nobody had run was the production build, and the production build is the thing that actually produces a site.

Running it in the working checkout was not an option. The build writes generated content, and the checkout had someone else's uncommitted edits sitting in it. A production build would have overwritten them.

So we built in isolation, and learned four separate things, one stage at a time.

Stage one: dependency resolution

The isolated copy had its node_modules symlinked to the real one, to save a reinstall. Next's build engine refused to resolve dependencies through the symlink. Not a code problem. An environment problem, and one that looks exactly like a code problem if you read the error quickly.

Copying the installed dependencies into the isolated tree, no symlink, fixed it without touching a line of source.

Stage two: compilation

Compiled clean. TypeScript passed. At this point every signal was green and it would have been easy to report "build passes".

Stage three: prerendering

The build then started rendering static pages, got as far as the trailers page, and stopped with a 401 from the movie database API. No credential was available in the isolated environment, so the page that fetches live data could not be built.

The partial output was still useful. It proved the homepage title was right and that six link labels had the accessible names the cleanup was supposed to give them. That was the point of the change, and the partial build confirmed it.

But a partial build is partial.

Stage four: packaging

There was no deployable Worker bundle. The build had died before packaging. So after all the green, the actual answer to "does this build for production" was no. Not "no, because the code is broken", but "no, because the build did not complete", which has the same consequence on deploy day.

We checked hashes on the original checkout afterwards. Unchanged. The isolation held.

Report the stage, not the color

The lesson is in how you say what happened. "Build passes" was true of stage two and false of stage four, and it is the kind of sentence an assistant reaches for the moment the compiler stops complaining.

The honest report has four lines:

  • Dependencies: resolved, after fixing the symlink layout.
  • Compilation and types: pass.
  • Prerendering: stopped at the trailers page, missing API credential.
  • Packaging: did not run. No deployable artifact.

Each stage is a separate claim with a separate failure mode, and a passing earlier stage cannot stand in for a later one that never finished. If I had read "build passes" and merged, the deploy pipeline would have found stage three for me, in public.

Isolation has its own requirements

The side lesson from stage one: an isolated build is only isolated if the build engine agrees with how you isolated it. A symlink is a perfectly good way to share dependencies until the tool decides to resolve real paths and finds itself outside its project root. Copy the dependencies, or use the tool's own notion of a workspace, but check that the isolated build runs clean before trusting anything it tells you.

What my assistant did well

It separated the stages without being asked. It did not say "build passes" when the bundle did not exist, and it did not say "build fails" in a way that implied the code was wrong. It said which stage stopped and why, and it said what the partial output had proved.

That is the report I want. The compiler being green is one fact. Whether there is anything to deploy is a different fact, and it is the one the deploy cares about.