Docs/Deployment/Manifest mode

Manifest mode

One generic build that loads its tours from manifest.json at runtime, with live preview and the @audioguidekit/schema package

By default the player compiles your content in. Tours, themes, interface texts and app.json are read from src/data/ when you build, so every content change needs a new build.

Manifest mode turns that around. You build the player once, with no content in it. When it starts, it fetches a single manifest.json. Publishing new content then means uploading a new file, and one build can serve any number of different apps.

Standard build (default)Manifest mode
Content comes fromsrc/data/, bundled into the build/data/manifest.json, fetched at startup
A content change needsA new buildUploading a new manifest.json
Selected byNothingVITE_DATA_SOURCE=manifest at build time
Installed-app name and iconsBuilt in from app.jsonServed by your host
AnalyticsOff unless you set an endpointOn, sending to /e

Nothing changes for you unless you set VITE_DATA_SOURCE=manifest. Most self-hosted tours are fine with the standard build.

Building

Build the player without content

bun run build:manifest

This is the same as VITE_DATA_SOURCE=manifest vite build.

Build a manifest from your tour files

bun run manifest

This reads your files in src/data (tours, themes, interface texts, app.json) and writes dist/data/manifest.json.

Deploy

Serve dist/ with the manifest at /data/manifest.json.

bun run manifest takes these options:

OptionDefaultMeaning
--data <dir>src/dataWhere your tour files are
--out <file>dist/data/manifest.jsonWhere to write the manifest
--include-hiddenoffInclude tours whose id starts with _ (test tours, left out otherwise)

It checks what it writes and stops with an error on any problem. bun run build (validate, then the standard build) is unchanged.

A manifest build contains no tour data and no app identity. It never reads app.json, generates no web app manifest, and does not copy public/data/tour into the output.

Build settings

VariableDefaultMeaning
VITE_DATA_SOURCEcompiledmanifest turns on manifest mode
VITE_MANIFEST_URL/data/manifest.jsonWhere to fetch the manifest. Another domain needs CORS headers
VITE_ANALYTICS_ENDPOINT/e in manifest mode, none otherwiseWhere analytics events go. See Analytics
VITE_PREVIEW_ORIGINSnoneComma-separated origins allowed to send live-preview manifests (see below)

What happens at startup

  1. The player shows a loading screen and fetches the manifest.
  2. It checks schemaVersion. If this build does not know that version, visitors see a message that the guide needs a newer version of the app. The player never guesses.
  3. It loads the content and starts the app. It does not run the full schema check: that is the publisher's job (see validateManifest below). It only refuses what it cannot run.
  4. It sets the tab title, home screen title, description and theme-color from manifest.app.

If the fetch fails, an error screen with Try again appears, unless the visitor has opened the app before.

Offline

The service worker fetches the manifest from the network first (with a 4 second timeout) and falls back to the copy from the last successful visit. So an app that has been opened once opens again without a signal, and a new publish shows up on the next online visit.

Only a response that is valid JSON with a supported schemaVersion is stored. A Wi-Fi login page or a broken publish cannot replace the last good copy.

Installed-app name and icons

The web app manifest and icons belong to one app, so a generic build cannot contain them. In manifest mode, index.html links to /manifest.webmanifest, /favicon.svg, /apple-touch-icon.png and /icons/icon-*.png, and your host must serve them, built from manifest.app.

Serve /manifest.webmanifest with Content-Type: application/manifest+json:

{
  "name": "<app.name>",
  "short_name": "<app.shortName, or app.name>",
  "description": "<app.description>",
  "theme_color": "<app.themeColor>",
  "background_color": "<app.backgroundColor>",
  "display": "<app.display, or standalone>",
  "orientation": "<app.orientation, or portrait>",
  "scope": "/",
  "start_url": "/",
  "icons": [{ "src": "/icons/icon-192x192.png", "sizes": "192x192", "type": "image/png" }]
}

The build keeps neutral AudioGuideKit icons in dist/ as a fallback for a plain static host. The service worker does not cache the icons, so your own icons replace them as soon as you serve them. See App icons for the sizes.

The manifest format

The manifest is your src/data folder as one JSON document:

{
  "schemaVersion": 1,
  "app": { "name": "City walks" },
  "themes": [],
  "ui": { "en": {} },
  "tours": [
    {
      "id": "barcelona",
      "metadata": { "id": "barcelona", "themeId": "default-light" },
      "languages": {
        "en": { "id": "barcelona", "language": "en", "title": "Barcelona", "stops": [] }
      }
    }
  ]
}
KeyWhat it holdsIn a standard build
schemaVersionThe manifest format version (currently 1)
appApp settings and installed-app identity (optional)app.json
themesCustom themes (optional)themes/*.json
uiInterface texts per language, merged over the built-in ones (optional)ui/<lang>.json
tours[].metadataShared tour settings, id includedmetadata.json
tours[].languagesOne entry per languageen.json, de.json, …
tours[].routeRoute GeoJSON (optional), replaces mapRoute.geoJSONroute.geojson

Media is always a URL, never embedded in the manifest.

Beyond the schema, a valid manifest follows these rules:

  • Tour ids and theme ids are unique.
  • A tour's id, its metadata.id and each language file's id match.
  • A language file's language matches its key.
  • totalStops equals the number of audio stops.
  • Every tour has at least one language.
  • Every theme reference (app.themeId, a tour's themeId, a theme's extends) names a built-in theme (default-light, default-dark) or a theme in the manifest. A custom theme cannot reuse a built-in id, and extends chains must not loop.
  • Every id in app.tourOrder is a tour.

Versions

A player refuses a manifest whose schemaVersion differs from its own. The version only goes up for breaking changes (a field removed or renamed, a changed meaning, a new required field). Adding an optional field does not change it.

Live preview

An editor can show the player in an <iframe> and send it whole manifests to preview changes without publishing:

iframe.contentWindow.postMessage({ type: 'agk:manifest', manifest }, playerOrigin);

The player only accepts messages from allowed origins. You set them in one of two ways:

  • At runtime, with a tag in index.html (as the first thing inside <head>). Add it on the preview host only:

    <meta name="agk-preview-origins" content="https://app.example.com,http://localhost:5173">
  • At build time, with VITE_PREVIEW_ORIGINS (same format). It is used when there is no tag with a valid origin.

Entries must be exact origins; * and null are ignored. With no origins at all, live preview is off. A page with the tag does not register the service worker.

The player applies a preview manifest without reloading the page. The open stop and scroll position reset, but the URL and the frame stay. It answers the sender:

MessageWhen
{ type: 'agk:ready' }At startup, once it listens
{ type: 'agk:manifest-applied' }The manifest was applied
{ type: 'agk:manifest-error', message }The manifest was refused (for example an unknown schemaVersion); the screen stays as it was

The @audioguidekit/schema package

packages/schema in the player repo is the contract between the player and anything that writes manifests, such as an editor or a CMS export.

import { validateManifest, SCHEMA_VERSION, type Manifest } from '@audioguidekit/schema';
import { FIELD_CATALOG, STOP_TYPES } from '@audioguidekit/schema/fields';
 
const result = validateManifest(manifest); // { valid, errors: string[] }

It contains:

  • Types for the manifest, tours, language files, app.json, every stop type, themes and interface texts.
  • JSON Schemas for a language file, metadata.json, app.json and the manifest.
  • validateManifest, which runs the schema and the extra rules above.
  • Field descriptions (FIELD_CATALOG): label, group, control, default, options and help text for every field the schemas accept, so an editor can be generated from them.

Install it with npm install @audioguidekit/schema. Everything about it, including building an editor from the field descriptions, is on the Schema package page.