fix: address CTO review notes — Loops env var clarity + NFS build doc

- 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 <noreply@paperclip.ing>
This commit is contained in:
Mikael Berg
2026-05-20 14:32:09 +00:00
co-authored by Paperclip
parent 230d4f2fec
commit eb156ab146
2 changed files with 20 additions and 1 deletions
+1 -1
View File
@@ -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
+19
View File
@@ -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`.