Reference

The full detail behind Build a themed wiki — not the path through, the place you come back to when you want everything about one part of it. If you haven't built one yet, start there; every section below assumes the build-along's shape (src/app.tsx, src/publish-hooks.ts) and links back to the step that introduced it.

The manifest, in full

{
  "id": "chronicle",
  "name": "Chronicle",
  "kind": "app",
  "version": "0.1.0",
  "icon": "book-open",
  "route": "chronicle",
  "category": "site",
  "publish": "custom",
  "customization": [ /* serialized from defineApp's customization: [THEME_PARAM, WIKI_HEADING_FONT_PARAM, WIKI_BODY_FONT_PARAM] — see Themes and fonts */ ],
  "needs": [],
  "capabilities": { "readsWorld": true, "writesWorld": false, "sharing": true },
  "entryModule": "@/app"
}

Edit these with the CLI rather than by hand: vvd set name "The Chronicle", and vvd info reads the whole manifest back.

Two lives, one rule

A wiki renders in two places, and the same React component does both: live, inside the app, reading the world in real time and taking edits when context.canEdit; published, at a public address, reading one frozen edition with no sockets, no auth, no database.

Where your wiki shows up

When installed, a wiki does not get its own tile in the launcher — every site-category app collapses into the one Wiki tile, because they're all templates for the same thing. Find yours by opening the wiki and switching the template in the design rail.

All site-category apps in a world also share one shared-state room, app-state:<world>:wiki — not one named after your app. Switch from the built-in Default template to yours and the page keeps its title and its featured entries; your field names live in that shared namespace on purpose.

Reading the world

useWorldQuery("documents", { type?: string }) is live — the component re-renders when the world's catalog changes on any client. Each row:

useWorldMeta() gives you the world header — the natural default for your site's title:

const meta = useWorldMeta()
const title = page.title.trim() || (meta ? meta.name : "Chronicle")

It carries id, name, slug, description, avatarMediaId, and optionally creator (a display-ready { name, avatarUrl }) and genres. Returns null under a host with no world identity — guard it.

Images

A media id is not a URL, and you must never build one. The bytes might be public, private, world-owned, another world's, or platform stock — and on a published page they've been rewritten entirely. Only the host knows.

const media = useHostCapability("media")

const [url, setUrl] = useState<string | null>(null)
useEffect(() => {
  if (!mediaId) { setUrl(null); return }
  let on = true
  setUrl(media.placeholder(mediaId))
  media.resolve(mediaId).then((u) => { if (on && u) setUrl(u) })
  return () => { on = false }
}, [mediaId, media])

• placeholder(id) is synchronous and render-safe — paint it immediately.
• resolve(id) is the truth, async — overwrite with it when it lands.

On a published page placeholder already returns the final URL, so nothing flashes a fallback — call both in that order regardless.

Customization vs. page state

Themes and fonts

useAppCustomization() — live only:

resolveCustomizationChoice(param, values) is a pure function you can also call on the published side, where there's no hook to call.

A theme is a palette plus two hints — background / primary / secondary are always present, foreground / line / font aren't, so a template-side reader gives every one of them its own fallback:

function themeFromPreset(p: { id: string; name: string; values: Record<string, string> }): ThemeSpec {
  if (p.id === WIKI_TEMPLATE_DEFAULT_ID) return TEMPLATE_DEFAULT
  const v = p.values
  return {
    name: p.name,
    bg: v.background || "#f4eedd",
    ink: v.foreground || "#1c1b18",
    card: v.secondary || v.background || "#fffdf4",
    line: v.line || "rgba(127,127,127,0.3)",
    accent: v.primary || "#8a5a2b",
    serif: v.font === "serif",
  }
}

"world" — the reader's own look, derived live:

import { useHostTheme, WIKI_WORLD_THEME_ID } from "@vvd/sdk"

const hostTheme = useHostTheme()   // { mode: "light" | "dark", tokens: Record<string, string> }

const meta = useWorldMeta()
const tokens = meta?.theme ?? {}   // "--background", "--foreground", …

WIKI_THEME_PARAM sets allowCustom: true with five editable tokens (Background, Accent, Secondary, Text, Border) — the platform's picker lets an owner roll their own and save it to a reusable library. If your themeFromPreset reads a key the custom editor doesn't offer, that key comes back undefined — which is exactly why every read above has a fallback.

Fonts — WIKI_HEADING_FONT_PARAM and WIKI_BODY_FONT_PARAM share one list of thirteen options; each is { id, name, family, source: "google" | "system" }. Loading a Google font is your job, deduped by id:

function ensureWikiFont(name: string, source?: string) {
  if (source !== "google" || typeof document === "undefined") return
  const id = "wiki-font-" + name.replace(/ /g, "-").toLowerCase()
  if (document.getElementById(id)) return
  const link = document.createElement("link")
  link.id = id
  link.rel = "stylesheet"
  link.href = "https://fonts.googleapis.com/css2?family=" + name.replace(/ /g, "+") + ":wght@400;500;600;700&display=swap"
  document.head.appendChild(link)
}

The typeof document === "undefined" guard matters: a published page renders in a sandboxed frame, and this should be a no-op there, never a crash.

Section order

const DEFAULT_SECTIONS = ["featured", "entries", "extras"]
const order = page.sectionOrder.length > 0 ? page.sectionOrder : DEFAULT_SECTIONS

An empty stored list means "the default order" — so a fourth section added later lands in the right place for everyone who never touched the order. The first reorder has to seed the list before it can move within it:

moveSection: (key, dir) => {
  const cur = page.sectionOrder.length > 0 ? [...page.sectionOrder] : [...DEFAULT_SECTIONS]
  const from = cur.indexOf(key)
  const to = from + dir
  if (from < 0 || to < 0 || to >= cur.length) return
  if (page.sectionOrder.length > 0) {
    actions.list("sectionOrder").move(from, to)
  } else {
    cur.splice(to, 0, cur.splice(from, 1)[0])
    actions.list("sectionOrder").push(...cur)
  }
}

The URL model

A world has one address. Published sites hang off it:

The middle row's ambiguity is resolved by looking: the platform asks whether a mount named a exists and falls back to treating it as an entry slug — an entry called atlas and a mount called atlas collide, and the mount wins. Path mounts exist in the data model; the in-app control for choosing one isn't exposed yet, so today a wiki is either the root instance or it isn't.

These first segments belong to the platform and never reach a published site:

api  _next  c  t  auth  login  worlds  site  sandbox  onboarding  cli
favicon.ico  robots.txt  sitemap.xml

There's also /u/<token>, used by the unlisted audience.

basePrefix — handed to renderBaked — is the link prefix for this mount ("" at a subdomain root, /site/<slug> under a path). You need it only for a non-document href; for documents, nav.hrefFor has already applied it.

A search box costs you nothing

The rows you already have carry name and aliases, so filtering in memory gives you a real search with no capability, no index and no request:

const entries = useMemo(() => {
  const q = query.trim().toLowerCase()
  if (!q) return cards
  return cards.filter(
    (d) => (d.name || "").toLowerCase().includes(q) || (d.aliases || []).some((a) => a.toLowerCase().includes(q)),
  )
}, [cards, query])

Search the aliases too — a character called "Sera Vale" who everyone calls "the Grey" should be findable as either.

Publishing — the full ctx

The last three are optional and additive — call them defensively (ctx.appState ? ctx.appState() : Promise.resolve(undefined)) so an older platform doesn't break your publish.

What you return — every key optional, bake only what your editions need:

return {
  index: docs,        // the frozen catalog — serve-time entry resolution reads it
  refs,                // documentId → { id, name, slug, type, avatarMediaId, entityTypeId }
  routes,              // documentId → "/<slug>" — the platform prefixes the mount
  mediaUrls,           // mediaId → final public URL
  entityTypes,
  documents,           // documentId → projected content
  extra: { worldName: world.name, page: appState ?? null },  // yours; nothing else reads it
}

Fetch contents in batches — both ways of getting this wrong are painful: one at a time turns a 200-card world into a multi-minute publish, and firing them all at once floods the host:

const BATCH = 24
for (let i = 0; i < docs.length; i += BATCH) {
  const slice = docs.slice(i, i + BATCH)
  const contents = await Promise.all(slice.map((d) => ctx.documentContent(d.id).catch(() => null)))
  slice.forEach((d, j) => { if (contents[j] != null) documents[d.id] = contents[j] })
}

Note the .catch(() => null) — one unreadable document should cost you that document, not the whole publish.

The published host

Anything not on the left resolves to nothing rather than throwing: useHostTheme() returns the platform default, HostEmbed still renders (embeds is there), media.pick is undefined. Props your renderBaked gets:

Versions and audiences

Every publish appends an immutable version; nothing is overwritten or deleted. You can point serving back at an earlier one. Four audiences, enforced at serve time:

The four verbs

vvd publish ships the wiki template. The Publish button ships the site. You can do either without the other. Ship it covers the first three; they behave identically for a tool, an app and a wiki.

Publish errors

Custom domains

Where to next