--- type: Decision title: Build layer order description: Manifests are copied and installed before any source, so a source edit cannot invalidate the dependency install. tags: [decision, docker, caching] status: stable generated: { by: opencode/deepseek-v4.1-flash, at: 2026-10-18T12:41:52Z } verified: { by: human:noel, at: 2026-10-18T12:41:52Z } sources: - id: docker-cache resource: https://docs.docker.com/build/cache/ title: Docker build cache --- # Decision Order the instructions so that the things that change rarely are installed first, and the things that change constantly are copied last. 1. Base image, then the toolchain (`pnpm`). 2. `COPY` the manifests only — `package.json`, `pnpm-lock.yaml`, `pnpm-workspace.yaml`. 3. `pnpm install --frozen-lockfile`. 4. (In an image that copies source at all) `COPY` the source, then build. # Why Each instruction is a layer, and a change in one layer invalidates that layer and every layer after it. The install is the slow step, so anything that changes often — the source — has to sit after it. Copying the whole source before installing would make every source edit re-run the install, which is exactly the cost the ordering is meant to avoid. # What invalidates what | Change | Effect | |---|---| | Edit `app/app.vue` | Nothing. In the dev image the source is never copied, so no layer depends on it. | | Edit `package.json`, `pnpm-lock.yaml` or `pnpm-workspace.yaml` | The `COPY` of the manifests and the install after it re-run; earlier layers stay cached. | | Change the pinned base image or the `pnpm` version | Everything from that instruction onward re-runs. | # Evidence The second consecutive `docker build -f Dockerfile.dev` reported every layer as `CACHED`, and the context transfer was 108 bytes — it contains only the three manifests, so no source edit can reach any layer. # Not chosen An earlier draft of the dev file ended with `COPY . . --cache` and `pnpm build`. The `COPY` instruction has no `--cache` flag, so that line is a build error, and building the application into a dev image works against running the dev server from a mounted source. # Revisit when The project gains a second package with its own manifest, which changes what belongs in the manifests-only copy.