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 stale outputs were removed?

The public API surface

The main API pieces are:

  • Site::render_to(...)

  • BuildReport

  • RouteBuildRecord

  • RouteBuildStatus

  • BuildReason

  • AssetBuildRecord

  • AssetBuildStatus

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

  • 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.

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.

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

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