Caching

Hyperbook's build cache stores downloaded runtimes on the machine running the CLI. HTTP caches store the files readers request from your host or a CDN. The development server also keeps its file listings (vdirectory.*.json, vfiles.json) in the project directory, so a restart picks up where the last session left off; it deletes them whenever a file changes.

Cache runtime downloads between builds

The CLI and VS Code share an asset cache. Builds reuse downloaded runtimes instead of fetching them again. You can set HYPERBOOK_ASSET_CACHE to choose its directory; the default is:

System	Directory
Linux	`$XDG_CACHE_HOME/hyperbook/assets`, or `~/.cache/hyperbook/assets`
macOS	`~/Library/Caches/hyperbook/assets`
Windows	`%LOCALAPPDATA%\hyperbook\assets`

CI runners usually start with an empty filesystem. Restore the asset cache before building and save it afterwards. For example, add these steps after checkout and Node.js setup in your GitHub Pages workflow:

- name: Cache Hyperbook runtimes
  uses: actions/cache@v4
  with:
    path: .cache/hyperbook-assets
    key: ${{ runner.os }}-hyperbook-assets-${{ hashFiles('package-lock.json', 'pnpm-lock.yaml', 'hyperbook.json') }}-${{ github.sha }}
    restore-keys: |
      ${{ runner.os }}-hyperbook-assets-
 
- name: Build
  env:
    HYPERBOOK_ASSET_CACHE: .cache/hyperbook-assets
  run: npx hyperbook build

The cache key saves newly needed runtimes when the book changes, and restore-keys allows later builds to reuse earlier downloads. Hyperbook checks cached files against its runtime manifest and downloads missing or changed bundles. Keep the normal online build so a cache miss can recover. See GitHub's caching documentation.

On GitLab, cache .cache/hyperbook-assets and set the same HYPERBOOK_ASSET_CACHE variable in your Pages job. Do not publish this directory; publish only .hyperbook/out.

CDN-enabled elements need no local runtime download. PyIDE uses a CDN by default. For an offline book, set elements.pyide.cdn to false, run npx hyperbook assets fetch while online, and then build with npx hyperbook build --offline. The --offline flag controls the build's downloads; it does not make a book with CDN URLs usable offline.

Serve the runtimes from your own host

A host that serves many books — Hyperbook Cloud, or a server of your own — can serve the element runtimes itself, one copy for all books, instead of copying them into every build or sending readers to the public CDNs. Set HYPERBOOK_SHARED_ASSETS_BASE to a root-relative address (it starts with / and ends with /) under which the directive-<element>/ directories of a local build are reachable, like in __hyperbook_assets/:

HYPERBOOK_SHARED_ASSETS_BASE=/assets/1.2.0/ hyperbook build

Elements whose cdn is not set or set to true load their runtimes from there; false and custom URLs keep their meaning. To serve only some elements yourself, list the others in HYPERBOOK_CDN_ELEMENTS (comma- separated): they keep their public CDN, also when the built-in default would keep their runtime local. Put the Hyperbook version in the address and serve the files with Cache-Control: public, max-age=31536000, immutable, so readers fetch a runtime once and reuse it for every book. Hyperbook Cloud does this automatically, at /_hyperbook/assets/<version>/; its admin chooses per element under Settings → Element runtimes.

Cache files for readers

If your host lets you configure response headers, use the following policies as a starting point for public books:

Files	`Cache-Control`	Effect
HTML and files replaced at the same URL	`no-cache`	Check for updates before reusing the cached response.
Files with a content hash or immutable release version in their URL	`public, max-age=31536000, immutable`	Reuse the file for a year; publish changes at a new URL.

Enable ETag or Last-Modified on your server so unchanged files can be revalidated without downloading their contents. For files at stable URLs, a short lifetime such as public, max-age=3600 is also possible if a delay of up to one hour after updates is acceptable. These settings follow the HTTP caching standard.

Hyperbook's locally exported runtimes use stable paths under __hyperbook_assets/directive-*/. Do not give that entire directory an immutable lifetime: upgrading Hyperbook can replace files at the same URL. Apply the same rule to files copied from your public directory. Set headers on your hosting service or web server; adding them to hyperbook.json does not configure HTTP caching.

Openpatch's versioned runtime releases on cdn.openpatch.org already send Cache-Control: public, max-age=31536000, immutable. Pyodide's versioned jsDelivr distribution is also cached by browsers; see the Pyodide deployment documentation. Your book's hosting settings do not change headers sent by these CDNs.