Site / foldkit-site

Declaring nodes, trees, and targets

Site.route(router, case, options?) declares one location. Options include title (function of the route value), section, landing (the section's nav params), shortcut (keys for Dom.streamFromKeyBindings, like '/' or ['G', 'H']), history, access, and surface.

To annotate a node step by step or share reusable bundles of annotations across nodes, use the Site.node builder:

ts
import { Site } from 'foldkit-site'

const Person = Site.node(personRouter, AppRoute.Person)
  .title(({ personId }) => `Person ${personId} | Routing`)
  .section('People')
  .node

The builder uses methods so TypeScript infers the route type at each stage, and .pipe(...) (or pipe(builder, bundle)) composes reusable annotation bundles without type annotations. Reading .node freezes the value at any step.

  • Mounting (Site.mount and Site.make): Site.mount(node, children?) attaches child nodes or subtrees, and Site.make(...roots) freezes the tree. Duplicate route tags or mounting the same node twice throw at Site.make so chain inspection stays unambiguous.
  • Targets (Site.target and Site.href): Site.target(node, params) returns { node, route, url }, and Site.href(target) (or Site.href(node, params)) returns its URL string built by the node's own router.
  • Parsing and reversing (Site.parse, Site.hrefOf, Site.routeAt): Site.parse(site, NotFound) builds your app's URL parser in depth-first tree order (parents first; place catch-all /:slug routes after specific literal routes). Site.hrefOf(site, route) formats any route in the tree and refuses unknown routes at compile time. Site.routeAt(site, url) returns Option.some(route) when the tree owns the URL or Option.none() when it belongs to another document that needs a full page load.
  • Inspecting the tree: Site.nodeOf, Site.chainOf, Site.parentOf, Site.ancestorsOf, Site.depthOf, and Site.nodesOf resolve routes to nodes and root-first ancestor chains.

To enumerate every concrete URL in the site for static builds or sitemaps, pair parameterized nodes with Site.paths and pass them to Site.targets:

ts
const list = Site.paths(People, Effect.succeed([{ params: { searchText: Option.none() } }]))
const people = Site.paths(
  Person,
  Effect.succeed([{ params: { personId: 3 }, modified: '2026-10-01' }]),
)
const listed = Site.targets(AppSite, [list, people])
// Effect resolving to [..., { node: Person, route, url: '/people/3', modified: '2026-10-01' }]

Missing Site.paths for a parameterized node, duplicate paths for one node, or paths for a node outside the tree are refused at compile time. Pass Effect.succeed([]) to emit zero URLs for a parameterized node.