Runtime

A Foldkit app lives in two files. src/main.ts holds the pure definitions: Model, Messages, update, init, and view. src/entry.ts imports them, creates a runtime with makeProgram, and calls Runtime.run. entry.ts is the only place runtime side effects happen, which keeps main.ts importable from tests.

makeProgram creates a Foldkit runtime. It handles both standalone components and full applications with routing. The difference is whether you provide a routing config.

Without a routing config, the program doesn't manage the URL bar. This is the default for most programs.

import { Runtime } from 'foldkit'

import { Model, init, update, view } from './main'

const program = Runtime.makeProgram({
  Model,
  init,
  update,
  view,
  container: document.getElementById('root'),
})

Runtime.run(program)

With a routing config, the program manages the URL bar. The init function receives the current URL so it can set the initial route.

import { Runtime } from 'foldkit'

import { ChangedUrl, ClickedLink, Model, init, update, view } from './main'

const program = Runtime.makeProgram({
  Model,
  init,
  update,
  view,
  container: document.getElementById('root'),
  routing: {
    onUrlRequest: request => ClickedLink({ request }),
    onUrlChange: url => ChangedUrl({ url }),
  },
})

Runtime.run(program)

The routing config has two handlers: onUrlRequest is called when a link is clicked (giving you a chance to handle internal vs external links), and onUrlChange is called when the URL changes (so you can update your model with the new route). See the Routing & Navigation guide for a full walkthrough.

Your view function returns a Document: an object with title, body, and optional canonical / ogUrl fields. The runtime sets document.title from your title on every render, and syncs the canonical and og:url meta tags so platform share menus copy the right link as you navigate. Both meta fields default to the current URL when omitted.

Most apps can start with just these runtime options. The next page covers Resources: long-lived browser singletons like AudioContext or CanvasRenderingContext2D that are shared across Commands.