Prerendering

Nodality builds your page in the browser. That is fine for an app behind a login, and a problem for anything that needs to be indexed or to paint before JavaScript runs: the HTML a crawler receives is an empty <div id="mount">.

Prerendering runs your page once at build time, in a headless DOM, and writes the resulting markup back into the HTML file. The shipped page then contains real content, and Nodality still boots on top of it in the browser.

npx nodality prerender

What it does

It reads the HTML files in your upload directory, executes the page's own entry script against a jsdom document, and replaces the mount point's contents with the rendered markup – in place, in the same file.

Nothing about how you write the page changes. The same elements and nodes arrays produce the page at build time and hydrate it at runtime.

Install jsdom

jsdom is a peer dependency, needed only at build time. It is not bundled, because a browser-only consumer should not pay for it:

npm install --save-dev jsdom

If it is missing, the command fails with an explicit message rather than the default Cannot find package 'jsdom' stack trace.

Configuration

Flags are optional. Anything not passed falls back to nodality.config.json in the project root, then to the defaults.

{
  "origin": "https://relays.app",
  "uploadDir": "upload",
  "tolerateAsyncErrors": false
}

Key	Flag	Meaning
origin	--origin=	Absolute site origin, used for canonical URLs and the sitemap
uploadDir	--upload=	Directory holding the HTML to render. Default upload
–	--out=	Write elsewhere instead of in place
–	--tolerate-async	Do not fail the build when an async task is still pending
–	--verbose	Report each page as it renders
locales	--locales=	Render one copy per locale
defaultLocale	--default-locale=	Which locale is served at the root

npx nodality prerender --origin=https://example.com --tolerate-async
npx nodality prerender --verbose

Async content

A page that fetches data has not finished rendering when the synchronous pass ends. The prerender waits for pending work, and by default fails if something is still outstanding – a page that silently prerendered half its content would ship looking fine and be wrong only for crawlers, which is the hardest kind of bug to notice.

--tolerate-async downgrades that to a warning when you know the outstanding work is not part of the initial paint.

Other commands

npx nodality compile [src/file.js]   # emit Designer output as a companion file
npx nodality fanout                  # generate per-item pages from JSON
npx nodality stage [--upload=DIR]    # copy the installed ESM bundle into upload/
npx nodality help

stage is the one consumers reach for most after prerender: it copies dist/index.esm.js into your upload directory and stamps the installed version into _nodality-version.js, so a deploy cannot ship page code and library code from different releases. It writes only when the content actually changes, so it is safe to re-run.