Documentation

Everything this template writes down

The documents live in the repository, next to the code they describe, so a change and its explanation travel in the same commit. Each one is summarised here — the button opens the full text when you want the detail.

Architecture

How the whole thing fits together

Start here. It covers the part that surprises people: application code runs twice, once in Node during the build and once in the browser.

Architecture Overview

The rendering pipeline, the layers and their enforced boundaries, how data flows, and what the build emits.

  • Application code runs twice — once in Node during the build to produce each route as its own HTML file, and once in the browser to hydrate it.
  • Four layers, and imports may only point one way through them: core, then the leaf layers, then services, then views and components.
  • The build emits more than pages: the sitemap, robots file and manifest are produced from what was actually rendered, not from what was declared.

Guides

One document per thing that bites

Each guide exists because the mistake it prevents is invisible in development and expensive in production.

SEO

How metadata reaches the prerendered HTML: titles, robots directives, the sitemap, share images and locales.

  • A route entry carrying a title, a description and a schema array is the whole interface; the canonical URL, the Open Graph tags and the sitemap entry follow from it.
  • Titles run through one template, robots directives fall back to a site-wide default, and the sitemap is generated from the emitted files rather than the route table.
  • It also explains why switching locale in the browser is a UX feature rather than an indexing one: a crawler indexes the URL, and one URL cannot rank as two languages.

Structured Data

The @id graph, the two rules that keep it valid, and how to add an entity without breaking them.

  • Two rules hold the graph together: one @id per real-world entity, declared exactly once, and the site-wide entities on the home route only.
  • Adding a page entity is walked through end to end, including when a site should declare a Person and when it should declare an Organization.
  • The knowledge-panel section is the part most sites skip: registry identifiers and reciprocal profile links are what let a consumer reconcile the entity rather than merely read it.

Deployment

Cloudflare Pages as the default target, and the equivalent configuration for Netlify, Vercel, CloudFront and GitHub Pages.

  • Cloudflare Pages is the default, either through the Git integration or a GitHub Actions job — one route or the other, never both.
  • Netlify, Vercel, S3 with CloudFront and GitHub Pages each get their own equivalent of the headers, redirects and 404 document.
  • Caching and environment variables close it out, since both are the parts that differ most between hosts.

Performance

The Core Web Vitals decisions this template starts from, and the reason behind each one.

  • One section per metric — Largest Contentful Paint, Cumulative Layout Shift and Interaction to Next Paint — with the decision each one drove.
  • Prerendered markup and self-hosted preloaded fonts are the two largest wins, and both are far harder to retrofit than to start with.
  • Caching, the service worker, honouring a reduced-motion preference, and how to measure any of it are covered at the end.

Local Development

The commands, how to add a route or a service, and what to check when something does not build.

  • Setup is three commands, and the dev server deliberately does not prerender — which is why some problems only appear in a preview build.
  • Adding a route and adding an API call each get a worked example, including why a view never calls fetch itself.
  • The troubleshooting section starts with the import that resolves in development and fails only in a production build.

Reference

Conventions and history

What the rules are, what shipped when, and what a change is expected to carry before it is reviewed.

Agent Guide

Conventions, the architecture rules ESLint enforces, the documentation standard, and the fork checklist.

  • The module map and the naming rules, marking which of them are ESLint rules rather than conventions anyone has to remember.
  • The documentation standard: which JSDoc tags to use, which take no argument, and which must never appear at all.
  • A section on the failure that only shows up in CI, and a fork checklist in the order the files actually have to be changed.

Release Notes

What shipped in each version, and the changes-log entries the release was assembled from.

  • Version 1.0.0 is the first working release: prerendered routes, the structured-data graph, generated sitemap and robots, and the Cloudflare Pages deployment.
  • Each release records its features, architecture changes, fixes and known issues, plus how to upgrade from the version before it.
  • The changes-log entries the notes were assembled from sit alongside them, dated, so a change can be traced to the day it landed.

Contributing

How to propose a change, and what a pull request is expected to carry before review.

  • Discuss the change with the maintainers before making it — through an issue, email, or any other route.
  • The pull request process covers build dependencies, keeping the README in step with the interface, and the SemVer bump the change implies.
  • A pull request merges on two sign-offs, and the code of conduct applies to every interaction with the project.

Generated

Two outputs the build produces

The API reference comes from TypeDoc and the developer book from HonKit. Neither is part of this site, so the commands that produce them are printed rather than linked.

  • npm run build:docs
  • npm run build:docs:book