From 62a9e293cb17670192d61c591ce52c17c0f1daf8 Mon Sep 17 00:00:00 2001 From: DeyangChan Date: Tue, 11 Aug 2026 18:25:48 +0800 Subject: [PATCH] docs(vercel-csr): name the precondition behind zero-config Fastify MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The Entrypoint section asserted that Vercel deploys Fastify with no configuration and told the reader not to export a handler or add a vercel.json. That holds only while Vercel's Git integration builds the project, which is the model infra.md mandates — detection runs on the push. A project that has left that model gets no detection: `vercel build --prebuilt` in CI builds from settings fetched by `vercel pull`, so the backend builds as a static site and the deploy stops at `No Output Directory named "public" found`. Observed in a project that had disabled Git deployments so its release could migrate the database before shipping code. Records the precondition, the escape hatch, and the trap in the escape hatch: restoring the vercel.json without restoring the handler export deploys a file that 404s every request, which reaches production instead of failing the build. Co-Authored-By: Claude Opus 5 (1M context) --- stacks/vercel-csr/backend.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/stacks/vercel-csr/backend.md b/stacks/vercel-csr/backend.md index b802c3d..5771a7e 100644 --- a/stacks/vercel-csr/backend.md +++ b/stacks/vercel-csr/backend.md @@ -85,6 +85,10 @@ Vercel detects Fastify and deploys it with no configuration, so the entrypoint i - Add `apps/backend/vercel.json` only when a setting genuinely differs from the defaults. A rewrite to the entrypoint is not one of them. - Run `vercel dev` to exercise the deployed request path locally; a plain `node src/server.js` is enough for unit-level verification. +**This holds because Vercel's Git integration builds the project** — the deployment model `./infra.md` mandates — and detection runs on every push. Check that before applying this section. A project that has left that model, with Git deployments disabled and `vercel build --prebuilt` running in CI, builds from settings fetched by `vercel pull` and gets no detection at all: the backend builds as a static site and the deploy stops at `No Output Directory named "public" found`. + +Restore the Git integration rather than working around it. Where a project genuinely cannot — a deploy that must migrate the database *before* the new code goes live is the usual reason — declare the build instead: `builds: [{ src: "src/server.js", use: "@vercel/node" }]` with a catch-all route to it, and export a default `handler(req, res)` that dispatches through Fastify, guarding the local `listen()` on `!process.env.VERCEL`. **Change both halves together.** The config alone deploys a file that exports no handler, which 404s every request — worse than the failed build, because it reaches production before a health check catches it. + ## Reference - [Fastify on Vercel](https://vercel.com/docs/frameworks/backend/fastify) — entrypoint detection and the supported filenames.