Ramonda

Building a static site

A static build renders every page to an HTML file at build time. The whole loop is a few lines:

import { renderPage, renderDocument } from "@ramonda/core";
import { routePaths } from "@ramonda/router";

const { paths, needsData } = routePaths(routes);

for (const path of paths) {
  window.history.pushState(null, "", path);
  const page = await renderPage(<App />);
  write(path, renderDocument(page, { scripts: ["/assets/client.js"] }));
}

This site is built exactly like that.

routePaths — the pages it can list, and the ones it can't

A route table is a set of patterns, and only some are single pages. /guide is one page; /players/:id is one route but as many pages as there are players.

const { paths, needsData } = routePaths(routes, ["/players/1", "/players/2"]);

needsData is the list of patterns whose values live in your data — you supply the concrete paths (the second argument). A build that ignored needsData would silently ship a site missing everything dynamic, so it is worth failing on:

if (needsData.length && extra.length === 0) {
  throw new Error(`These routes need concrete paths: ${needsData.join(", ")}`);
}

("*" is left out — it matches what nothing else did, so it has no URL. A project from create-ramonda bakes it as 404.html, the file a static host serves for a path it has no file for — see one folder for a static host.)

Those two fields are a RoutePaths, which is the shape this answers in: paths ready to render, and needsData for the patterns it cannot enumerate.

renderDocument and DocumentOptions

Wraps a rendered page in a complete HTML document — doctype, charset, viewport, title, the page's own head, a root element, your stylesheets and scripts.

option
lang<html lang> when the page's Head set none, default "en"
scriptsmodule scripts at the end of <body> — your hydration entry
stylesstylesheet links
headExtraraw markup for anything it doesn't model (favicon, analytics). Not escaped
rootIdthe element the app mounts into, default "app"

Those options are DocumentOptions. It takes a RenderedPage — what renderPage hands back: the app's body, the title and head a Head hook set, and portals, which is what each named portal target collected, kept apart from head because they land somewhere else in the document.

It is deliberately small: the document shell is the one part every project wants slightly differently, so it does the parts that are always the same and leaves the rest to headExtra.

lang defaults to "en", and that is a default rather than a recommendation — a screen reader picks pronunciation from it and a search engine decides which audience the page is for. A page whose Head sets lang wins over it, and its dir is written beside it.

Your bundler needs two builds

A client bundle (which calls hydrateRoot) and a server bundle for the build loop. Node can't parse TC39 decorators, so the build script runs transpiled output — a dev server's on-the-fly transform won't do. (And if you use AsyncLoad, split both bundles — see lazy loading.)

Next