Public sites
A public site (defineSite({ public: true })) is served at the root of its own host, and at /sites/<name> on the app’s host as any site is, in the app’s chrome, for the people who run it.
- Its hosts.
<name>.localhoston the app’s port (a browser sends*.localhostto this machine, and the loopback login lets it through), and the domainstartApp’sdomainsgives it ({ www: "sanoma.example" }; thesanomabin readsSANOMA_DOMAINS, which a host resource’sdomainssets). A domain naming a site that is missing or not public is warned about and served nowhere.app.sitesgives each public site served, by name, athttp://<name>.localhost:<port>; the Sites page links to the site’s domain, else, on a page of this machine, to<name>.localhost(the server, which cannot know that address, says Public until the browser does). - One build, two routings. On the site’s host the router mounts the site at
/: a page’s<Link to="/sites/www/blog">is/blogthere and/sites/www/blogon the app’s host, and a path outside the site,/workflowsamong them, is the site’s not-found page, a 404. A GET or HEAD there for a path under/sites/<name>, the site’s page as the app’s host spells it (a link copied from there), answers 308 to its path at the root, the query kept. The document there is bare: charset, viewport, a body with no margin, in a layer ahead of the site’s stylesheet so any rule of the site’s overrides it, the browser’s light scheme (a site whose colours follow the visitor’s light or dark, withlight-dark(), says so in its stylesheet, as above:[data-site="www"] { color-scheme: light dark; }, not:root, which inside the app would override the app’s own), and<html data-site="<name>">, which a site’s stylesheet may scope its own host’s rules to (A site’s own stylesheet); no app stylesheet, theme, icon, chrome or config, which the app’s host loads in chunks of their own. The site’s layout sets its own icon and stylesheet in itshead, and each page its title; the kit’s look comes with that stylesheet (The kit on a site). - Not found and errors. A page not found there, a path no page has or a loader’s
notFound()(Content), answers 404, titled “Page not found” unless a route of the site gives a title: a title in the layout’sheadstays on every page, a page not found too, so give each page its own. Where the site draws nonotFoundComponentorerrorComponent, the page is a plain one of the app’s (a heading and a line, no app styles), and an error’s message stays out of it. - Its front door. A request to the site’s host never reaches the staff login, and its cookie and
x-sanoma-actorheader are ignored there. The site’s login (defineSite({ public: true, login: "<connector>" }), a connector’s login half) answers/auth/<connector>/*and verifies a visitor, who acts asvisitor:<connector>:<subject>in the groupvisitors(with the email and the GitHub login the login verified, asctx.startedBy.emailandctx.startedBy.github, when it verified them); anyone else, and everyone on a site with no login, acts asanonymous. A request withAuthorization: Bearer sca_…, an API tokenSanomaClient.tokens.mintmade, acts astoken:<id>in the groups the token was minted with, with no email; a token that is unknown or revoked is a 401. OnlycallFn(a site’sapi) andgetActor(useActor(), which says nobody foranonymous) answer there: any other server function is not there (a change’s 404, a read’s not-found), nor any other/auth/route (404), and a method but GET, HEAD and POST is a 405. Every request there carriesx-sanoma-client-ip(CLIENT_IP_HEADER), set from the socket, a client’s own copy overwritten. What a visitor may call is the policy’s, by apermit(above). - Its login.
startAppmakes each public site’s login half once it listens, before it resolves, with the client’s pool (LoginContext.database), a key of its own to sign its cookies with (derived fromSANOMA_SIGNING_KEYforlogin <connector>, so a login like Better Auth needs no secret set), its stored secrets, the site’s origins (http://<name>.localhost:*, andhttps://<domain>with a domain) and, when the config names alogin.sender, the sender (Better Auth’s visitor login then also signs in by an email code, at/auth/better-auth/email-otp/send-verification-otpand/auth/better-auth/sign-in/email-otp, sent as alogin-coderun), andstartApp’ssocial, the company’s GitHub App client, whichsanomapasses on a host (Better Auth’s visitor login then lets a visitor sign up and in with GitHub beside the email code, or link it once signed in, through the same callback URL: its README); a request that comes first waits for it. A public site whosesite.tshas a problem (its login may be one not read), or whose login fails to start, is served on no host, a 503, and the app’s log says why; the app itself starts, so the connector’s page, orSANOMA_SIGNING_KEYin the environment, can give what the login lacks. - Search engines. The site’s host answers
/robots.txtand/sitemap.xmlitself, ahead of its pages (a site cannot replace them). robots.txt lets every crawler read everything and names the sitemap; on any host but the site’s domain (<name>.localhost) every response saysX-Robots-Tag: noindex, which a crawler sees because robots.txt lets it read the page. The sitemap lists the site’s pages at its origin: each route file’s path with no parameter (describeConfig’sSiteEntry.pages, read from the route ids without running them), and, for a path with one parameter whose file reads one kind’s entry by it,content.<kind>.get(params.slug)(orslug, destructured), a page per entry of that kind (/blog/$sluggives/blog/<slug>for each post): the content as the app’s snapshot read it (again once a file undercontent/changes; the Worker’s, as built), drafts left out. A page whose file reads its entry some other way (through a component’s helper) is left out: when the file reads content by something else than its parameter,sanoma checkwarns, naming it. A page whose route saysstaticData: { sitemap: false }, written out as that literal, is left out with all its entries: one whoseheadtells crawlersnoindex, say. An index route’ssitemap, when it gives one, decides over its layout’s (truekeeps the page in); a pathless or group layout’s says nothing. A page under{-$locale}on a site with languages is listed once per language (the default unprefixed), withxhtml:linkalternates to itself in each language it is in andx-default: a content page is in a language when its entry has a translation into it or a<slug>.md, ascontent.<kind>.get(slug, { locale })reads it. The Sites page links each public site’s sitemap beside its address. - Absolute URLs. A canonical link,
og:urlandog:imagemust be absolute.siteOrigin(), fromsanoma/site, is the origin a page’s URLs take: on a public site’s host, its domain when it has one (https://<domain>), else the host the request came to; on the app’s host, the app’s.siteUrl(path)is a page’s URL from its path as the route tree spells it, at that origin, without/sites/<name>on the site’s host and without a trailing slash but on/, as the router answers it and the sitemap lists it (an index route’smatch.pathname,/sites/www/blog/, gives/blog). Both work in a route’shead, its loader and a component, on the server and in the browser (<html data-origin>):
// sites/www/routes/blog.$slug.tsximport og from "../assets/og.png";
export const Route = createFileRoute("/sites/www/blog/$slug")({ loader: …, head: ({ match, loaderData }) => ({ meta: [ { title: loaderData?.data.title }, { property: "og:url", content: siteUrl(match.pathname) }, // https://sanoma.example/blog/<slug> { property: "og:image", content: new URL(og, siteOrigin()).href }, ], links: [{ rel: "canonical", href: siteUrl(match.pathname) }], // JSON-LD, as TanStack's head allows: a script of type application/ld+json. scripts: [{ type: "application/ld+json", children: JSON.stringify({ "@context": "https://schema.org", "@type": "Article" }) }], }),});- Not on a public host: the app’s chrome and what it provides, so a site there brings its own toasts and has no
useDensity()(it throws);RunFormand the will-ask preview, which read the config and link to the app’s pages. - Later: a
RunFormon a public page; rate limits;Cache-Controlheaders on anonymous content pages, so a CDN in front can cache them (the cheap step toward prerendering), then prerendering on the other hosts, where an edge cache serves the files (on Cloudflare,buildAppBundleprerenders already; a content-only page’s render reaches neither the database nor the worker, and Start’s prerender cannot render with the request context a page needs); the public host’s own pending view; an anonymous id per session (every anonymous visitor is one principal now).
These pages describe sanoma 0.11.24.