From 2692e71297925b7c117108fa9da9defe87dfe88e Mon Sep 17 00:00:00 2001 From: Paul Nothaft Date: Fri, 29 May 2026 21:43:49 +0200 Subject: [PATCH] docs(contributing): note rebuild-after-package.json gotcha for dev compose MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit When PR #555 (CRM module) added pdfkit/swissqrbill/pdf-lib/qrcode to backend/package.json, every dev with an already-built dev image hit a MODULE_NOT_FOUND restart loop on the next pull. Root cause: the dev compose bakes node_modules into the image while live-mounting src/ from disk — a dep added on disk isn't visible to the running container until the image is rebuilt. The symptom doesn't point at the cause, so this adds a short rebuild note to the Local Development section of CONTRIBUTING.md. A self-healing entrypoint (compare node_modules/.package-lock.json vs /app/package-lock.json on boot, npm ci if they differ) would fix this at the runtime layer too; tracked as a follow-up. --- CONTRIBUTING.md | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 87ee9df1..4218cc93 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -79,6 +79,15 @@ cp .env.example .env docker-compose -f docker-compose.dev.yml up ``` +**After pulling changes that touch `backend/package.json` / `backend/package-lock.json` (or the frontend equivalents)**, rebuild the affected image so the live-mounted source can `require()` the new deps: + +```bash +docker compose -f docker-compose.dev.yml up -d --build backend +# (or `frontend`, or both) +``` + +The dev compose bakes `node_modules` into the image while live-mounting `./backend/src` and `./frontend/src` from disk. A dep added on disk won't be picked up until the image is rebuilt — typical symptom is a `MODULE_NOT_FOUND` restart loop on the affected container. + ### Running Tests ```bash