From eb156ab146d7d3069de4e4ee49ae7ba35cf96d77 Mon Sep 17 00:00:00 2001 From: Mikael Berg Date: Wed, 20 May 2026 14:32:09 +0000 Subject: [PATCH] =?UTF-8?q?fix:=20address=20CTO=20review=20notes=20?= =?UTF-8?q?=E2=80=94=20Loops=20env=20var=20clarity=20+=20NFS=20build=20doc?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - README: clarify NEXT_PUBLIC_LOOPS_FORM_ID is required and that omitting it produces a broken (404ing) form, not a graceful degradation - docs/deploy.md: add Local Build Notes section explaining the config.cache=false NFS workaround, the ~15s penalty, and the two-run fallback Co-Authored-By: Paperclip --- README.md | 2 +- docs/deploy.md | 19 +++++++++++++++++++ 2 files changed, 20 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index f27656f..fcc2672 100644 --- a/README.md +++ b/README.md @@ -40,7 +40,7 @@ docker run -p 8080:8080 using-cash-web | Variable | Required | Description | |---|---|---| -| `NEXT_PUBLIC_LOOPS_FORM_ID` | Yes (for waitlist) | Loops publishable form ID. Baked into the static build at `npm run build` time. Without it the waitlist form falls back to a stub endpoint. | +| `NEXT_PUBLIC_LOOPS_FORM_ID` | **Required** | Loops publishable form ID. Baked into the static HTML at `npm run build` time. Without it the waitlist form submit will 404 — the build succeeds but the deployed form is broken. Always set this before building for production. | ## Pages diff --git a/docs/deploy.md b/docs/deploy.md index 4e8a896..ab0b158 100644 --- a/docs/deploy.md +++ b/docs/deploy.md @@ -166,6 +166,25 @@ If the cutover causes issues, revert the A record to its previous value: --- +## Local Build Notes (NFS environments) + +The Next.js build pipeline writes and immediately re-reads webpack manifest files. On NFS-backed workspaces (e.g. Paperclip agent workspaces), write-visibility lag causes the first cold build to fail at the "Collecting page data" step with an ENOENT on a manifest file. + +**The fix is already in `next.config.mjs`:** + +```js +webpack(config) { + config.cache = false // disables webpack persistent cache to avoid NFS race + ... +} +``` + +This adds ~15 seconds to each build (no cache warm-up) but makes the build reliable on NFS. In Docker/CI the build runs on local ephemeral storage so this penalty does not apply there. + +If you see `ENOENT: .next/server/pages-manifest.json` or similar on a fresh build, run `npm run build` a second time — the second run will succeed as the cache is already warm. + +--- + ## Ongoing Deploys (CI) CI runs automatically on push to `main` via `.gitea/workflows/deploy.yml`.