Caching

Der Build-Cache von Hyperbook speichert heruntergeladene Laufzeitumgebungen auf dem Rechner der CLI. HTTP-Caches speichern Dateien, die Leser von deinem Host oder einem CDN abrufen. Der Entwicklungsserver legt außerdem seine Dateilisten (vdirectory.*.json, vfiles.json) im Projektverzeichnis ab, damit ein Neustart dort weitermacht, wo die letzte Sitzung aufgehört hat; beim Ändern einer Datei löscht er sie wieder.

Downloads zwischen Builds aufbewahren

CLI und VS Code teilen sich einen Asset-Cache. Builds verwenden bereits heruntergeladene Laufzeitumgebungen erneut. Mit HYPERBOOK_ASSET_CACHE kannst du das Verzeichnis festlegen. Standardmäßig wird dieser Pfad verwendet:

CI-Runner starten normalerweise mit einem leeren Dateisystem. Stelle den Asset-Cache vor dem Build wieder her und speichere ihn danach. Füge zum Beispiel diese Schritte nach Checkout und Node.js-Einrichtung in deinen GitHub-Pages-Workflow ein:

- 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

Der Cache-Schlüssel speichert neu benötigte Laufzeitumgebungen, wenn sich das Buch ändert. Mit restore-keys verwenden spätere Builds frühere Downloads erneut. Hyperbook prüft die Dateien anhand seines Laufzeitmanifests und lädt fehlende oder geänderte Pakete herunter. Verwende den normalen Online-Build, damit ein fehlender Cache automatisch ergänzt wird. Siehe die GitHub-Dokumentation zum Caching.

Bei GitLab kannst du .cache/hyperbook-assets zwischenspeichern und dieselbe Variable HYPERBOOK_ASSET_CACHE im Pages-Job setzen. Veröffentliche dieses Verzeichnis nicht, sondern nur .hyperbook/out.

Elemente mit aktiviertem CDN benötigen keinen lokalen Download. PyIDE verwendet standardmäßig ein CDN. Setze für ein Offline-Buch elements.pyide.cdn auf false, führe mit Internetverbindung npx hyperbook assets fetch aus und baue anschließend mit npx hyperbook build --offline. --offline steuert die Downloads beim Build. Ein Buch mit CDN-URLs wird dadurch nicht offline nutzbar.

Laufzeitumgebungen vom eigenen Host ausliefern

Ein Host, der viele Bücher ausliefert — Hyperbook Cloud oder ein eigener Server — kann die Laufzeitumgebungen der Elemente selbst ausliefern, in einer Kopie für alle Bücher, statt sie in jeden Build zu kopieren oder die Leser zu öffentlichen CDNs zu schicken. Setze HYPERBOOK_SHARED_ASSETS_BASE auf eine relativ zur Wurzel angegebene Adresse (beginnt mit / und endet auf /), unter der die directive-<element>/-Verzeichnisse eines lokalen Builds erreichbar sind, wie in __hyperbook_assets/:

HYPERBOOK_SHARED_ASSETS_BASE=/assets/1.2.0/ hyperbook build

Elemente, deren cdn nicht gesetzt oder true ist, laden ihre Laufzeitumgebung von dort; false und eigene URLs behalten ihre Bedeutung. Um nur einige Elemente selbst auszuliefern, liste die übrigen in HYPERBOOK_CDN_ELEMENTS auf (durch Kommas getrennt): sie behalten ihr öffentliches CDN — auch dann, wenn die eingebaute Voreinstellung ihre Laufzeitumgebung lokal einbinden würde. Nimm die Hyperbook-Version in die Adresse auf und liefere die Dateien mit Cache-Control: public, max-age=31536000, immutable aus, damit Leser eine Laufzeitumgebung nur einmal laden und sie für jedes Buch wiederverwenden. Hyperbook Cloud macht das automatisch, unter /_hyperbook/assets/<version>/; ihre Admin-Wahl trifft pro Element unter Einstellungen → Element-Runtimes.

Dateien im Browser zwischenspeichern

Wenn dein Host eigene Antwort-Header erlaubt, kannst du für öffentliche Bücher mit diesen Einstellungen beginnen:

Aktiviere auf deinem Server ETag oder Last-Modified, damit unveränderte Dateien ohne erneuten Download ihrer Inhalte geprüft werden können. Für stabile URLs ist auch eine kurze Dauer wie public, max-age=3600 möglich, wenn bis zu eine Stunde Verzögerung nach Änderungen akzeptabel ist. Diese Einstellungen folgen dem HTTP-Caching-Standard.

Die lokal exportierten Laufzeitumgebungen verwenden stabile Pfade unter __hyperbook_assets/directive-*/. Gib nicht dem gesamten Verzeichnis eine unveränderliche Cache-Dauer: Ein Hyperbook-Update kann Dateien unter derselben URL ersetzen. Das gilt auch für Dateien aus deinem public-Verzeichnis. Setze die Header beim Hosting-Dienst oder Webserver. Ein Eintrag in hyperbook.json konfiguriert kein HTTP-Caching.

Die versionierten Laufzeit-Releases auf cdn.openpatch.org senden bereits Cache-Control: public, max-age=31536000, immutable. Auch die versionierte Pyodide-Distribution auf jsDelivr wird im Browser zwischengespeichert; siehe die Pyodide-Dokumentation. Die Hosting-Einstellungen deines Buchs ändern die Header dieser CDNs nicht.