RSTRust-First Site ToolkitA Rust-first static site generator with typed collections, explicit routes, and a format-agnostic asset pipeline.

Blog

Build Reports Make Incremental Work Visible

The build report API exposes which routes and assets were emitted, skipped, restored, or removed so incremental behavior is observable instead of mysterious.

2026-03-30rustincremental-buildssite-generator

Caching is only trustworthy when you can see what happened

Incremental builds are great when they work and maddening when they feel opaque.

That is why the framework now returns a BuildReport from Site::render_to(...).

The report answers questions such as:

  • which routes were emitted?

  • which ones were skipped?

  • why was a route rebuilt?

  • which public assets were transformed versus restored from cache?

  • which requested asset operations had to degrade safely?

  • which stale outputs were removed?

The public API surface

The main API pieces are:

  • Site::render_to(...)

  • BuildReport

  • RouteBuildRecord

  • RouteBuildStatus

  • BuildReason

  • AssetBuildRecord

  • AssetBuildStatus

  • BuildWarning

  • AssetWarningRecord

That gives the incremental-build system an observable public result instead of only terminal text.

Route results and asset results are tracked separately

The build report has separate records for:

  • route outputs

  • generated public assets

  • non-fatal build warnings

  • removed outputs

That distinction matters because a build can skip a route render and still need to restore missing files under dist/assets/.

If the report only tracked "routes built or not", that nuance would disappear.

Warnings matter for a different reason: sometimes a build should keep going, but still tell you that one requested result had to degrade safely. The current adaptive-HDR asset path is the first example of that.

Invalidation reasons are explicit

When a route is emitted, the report also carries a BuildReason.

That makes cache behavior explainable:

  • new route

  • output missing

  • program changed

  • handler changed

  • output path changed

  • dependency changed

  • route manifest changed

This is especially useful when a route rebuild was correct, but not obvious at first glance.

Warnings are about degraded outcomes, not noisy internals

The warning surface is intentionally consequence-oriented.

If the asset pipeline cannot safely derive every adaptive-HDR auxiliary structure, the report does not dump raw metadata trivia into the public API. Instead it tells you the user-visible outcome: for example, that an HDR AVIF output was produced but synthesized gain-map derivation was skipped.

This is not only for the human CLI

The report is also useful to:

  • tests that want to assert incremental behavior

  • custom CLIs that want a more structured summary

  • deployment or preview tooling that wants to react only to actual work

  • CI checks that want to fail or notify on degraded-but-non-fatal outputs

That is why the data is returned as a Rust type instead of being only printed as terminal text.

Make the build graph observable

The broader point is that the incremental system should not feel magical.

A build engine that records dependencies but cannot explain its decisions is much harder to trust. The build report is part of making those internal decisions visible at the API boundary.

Where to go next