Skip to content

Add an incremental build example - #3

Open
OzzyCzech wants to merge 2 commits into
mainfrom
feat/cache-example
Open

Add an incremental build example#3
OzzyCzech wants to merge 2 commits into
mainfrom
feat/cache-example

Conversation

@OzzyCzech

Copy link
Copy Markdown
Member

Documents @sphido/cache@1.0.0 the way this repo documents things — as something you can run.

cache/

A fifth example using all three functions: changed() skips pages whose output is up to date, removed() reports sources that disappeared, writeCache() records the state after the build. It prints what it did, so the point is visible:

$ node index.js
3 page(s) built, 0 skipped — run it again and nothing is built

$ node index.js
0 page(s) built, 3 skipped — run it again and nothing is built

Two details the example demonstrates rather than explains:

  • the build hashes itself into the version key, so changing the layout rebuilds every page — the cache watches content, not templates
  • page.output is set before changed(), which is what makes rm -rf public regenerate the site

content/about.md doubles as the mtime vs hash demo (touch it and the default strategy notices; hash does not), and content/blog/hello-world.md invites you to delete it and watch removed() report it.

Verified by hand

step result
first run 3 built, 0 skipped
second run 0 built, 3 skipped
edit one page 1 built, 2 skipped
delete a source gone: content/blog/hello-world.md …, 0 built
rm -rf public 2 built

Also

  • cache added to the CI matrix, so it is built on Node 22 and 24 like the others
  • a section in the root readme
  • cache/.gitignore covers .sphido/ next to public/

Depends on #2 only in spirit — that one unbreaks main, this one is additive.

A fifth example built on @sphido/cache: changed() skips pages whose
output is up to date, removed() reports sources that disappeared, and
writeCache() records the state after the build.

The build hashes itself into the version key, so editing the layout
rebuilds everything, and page.output is set before changed() so a deleted
public/ regenerates the site instead of trusting a cache that is right
about sources and wrong about results.

Verified by hand: 3 built on the first run, 0 built and 3 skipped on the
second, 1 built after editing one page, removed() reporting a deleted
source, and a full rebuild after rm -rf public.
@OzzyCzech

Copy link
Copy Markdown
Member Author

CI note: cache on Node 22 and cache on Node 24 pass — this example is fine.

The red jobs (basic, extenders, json, rss) fail on npm install, not on anything here: this branch is off main, which still asks for @sphido/markdown@^1.0.0. #2 fixes that. Merge #2 first and these clear on the next run.

The 1.x range is unpublishable — npm blocks the 24 versions unpublished
from that name in 2024, so the package ships as 2.0.0.
@OzzyCzech

Copy link
Copy Markdown
Member Author

Carried #2's one-line bump into this branch (9554164), so the PR no longer depends on main being fixed first — every example now asks for @sphido/markdown@^2.0.0 and CI should be green across the matrix.

Both merge orders are safe: if #2 goes in first, this branch's copy of that change becomes a no-op.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant