Files
CV_Site_Nuxt/OKF_Nuxt/decisions/build-layer-order.md
Noel Sabia 8fa078707c docs(okf): add Nuxt knowledge bundle in OKF v0.2
Record the design decisions behind the Nuxt site as an OKF v0.2 bundle: dev
container shape, build layer order, build context filter, repository and
compose layout, and the mockup layout, plus the open questions.

Conformant per the spec: every concept carries a non-empty type, the reserved
index and log files follow their structures, and every internal link resolves.
2026-10-18 14:49:25 +02:00

2.2 KiB

type, title, description, tags, status, generated, verified, sources
type title description tags status generated verified sources
Decision Build layer order Manifests are copied and installed before any source, so a source edit cannot invalidate the dependency install.
decision
docker
caching
stable
by at
opencode/deepseek-v4.1-flash 2026-10-18T12:41:52Z
by at
human:noel 2026-10-18T12:41:52Z
id resource title
docker-cache https://docs.docker.com/build/cache/ 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.