Sites
A folder under sites/ with a routes/ directory is a site: TanStack Router file routes the app serves under /sites/<name>, in its shell (see sanoma/app’s Sites). A route file imports createFileRoute from @tanstack/react-router; the repo installs nothing for it but sanoma.
sanoma app(andsanomawhenSANOMA_APP_HOSTis another machine’s) builds the app with the repo’s sites before anything starts (building the app with 1 site (hello)), into.sanoma/app/build/<key>, and serve that build. The key covers the app’s version and every file undersites/andcontent/, so a start with nothing changed reuses the build (app build up to date). With no site, they serve the build the app ships and write nothing under.sanoma/butapi.ts. A build that fails stops the command before the worker starts..sanoma/api.tsis the generated SDK:sanoma check(first, before tsc), andsanoma,sanoma serveandsanoma appat start, write it from the config when its text changed, with sites or without; whilesanomaserves the sites from its dev server, it writes it again (wrote .sanoma/api.ts) whensanoma.config.tsor any TypeScript file in the repo outsidesites/,.sanoma/andnode_modules/changes. It typesapifromsanoma/site:api.<workflow>(the workflow’s name in camelCase,WorkflowFnof its input),api.<vendor>.<resource>.<op>for each operation a person may call directly (a vendor’s read,OpFnof its input) andapi.data.<collection>(CollectionApiof the collection’s record), each with its title and descriptions as JSDoc, so whoever writes a site sees what each call is andtsc -p sites/tsconfig.jsonrefuses a call that does not fit. The sites’ tsconfig is the only one that reads it: the repo’s roottsconfig.json(Node, no DOM) must not include it. A workflow whose api name another workflow, a vendor ordatahas is left out of it, andsanoma checkreports it. Never edit it.sanoma check, when there is a site, writes the sites’ generated files, then, beside tsc, oxlint and the config, builds the app with the sites (reused when nothing changed) and runstsc -p sites/tsconfig.json, which types everyLinkagainst every page of the app and the sites. Each of these is a problem: a type error at itsfile:line:col; two pages claiming one path (More than one page claims /sites/hello/: …); a site importing server code (sites/hello/routes/index.tsx:4:28: Import denied in client environment: "sanoma/workflows"); a folder whose name is not one URL segment (sites/<name>: a site's folder name is a URL segment (lowercase letters, digits and dashes)), which the app does not mount; and undercontent/, front matter that is not a YAML mapping, at its line (content/posts/bad.md:2:1: front matter: Tabs are not allowed as indentation), or a folder or file whose name is not a URL segment, which the sites do not see.- On a public site,
sanoma checkreports each start (api.signup(…),.start(…), aRunForm) and each direct call (api.data.<collection>.<op>,api.<vendor>.<resource>.<op>) that nopermitinpolicies/could let a visitor make, whatever itswhenandunless(one foranonymous; on a site with alogin, foranonymousorvisitors), at itsfile:line:colwith the line to add:sites/www/routes/index.tsx:8:9: a visitor's call to workflow "signup" is refused: no permit in policies/ names anonymous for workflow:signup. Add: permit (principal == Sanoma::Principal::"anonymous", action == Sanoma::Action::"workflow:signup", resource);. Nothing is held to the policies while they have a problem. Whatever they say, a public site’s call of a built-in workflow, or read of a workflow’s runs but.result, is reported too: the app refuses it to every visitor. - A site’s
public/folder holds files served as they are, such as a prebuilt script a page loads by its URL:sites/<name>/public/<path>is at/sites/<name>/<path>on the app (an app’s site’s at/sites/<app>/<name>/<path>), and at/<path>on a public site’s own host,<name>.localhostand its domain. The build copies them into its files without bundling or renaming them,sanomaserves them from disk as they are saved, and neither the lint, tsc nor Tailwind reads them. A file is as reachable as the site’s pages: on the app’s host to the people its login lets in, and on a public site’s host to every visitor, signed in or not, since a site’s login decides what a visitor’s calls may read, not who loads its pages. The build refuses a file whose name has no extension, one at a page’s path, one at a path a site’s own host keeps for the app (robots.txt,sitemap.xml,assets/,auth/,sites/,_serverFn/,__sanoma/), and one over 25 MiB, the most Cloudflare serves as one of a Worker’s assets; it leaves out a dotfile or a dot-folder (.DS_Store,.well-known/) and a link. A file is answered before a page whose path has a parameter, such asdocs/$slug. content/holds the Markdown a site reads throughcontentfromsanoma/site(sanoma/app’s Content):content/<kind>/<slug>.md, front matter and a body, found by convention assites/is..sanoma/content.tstypes it from the files’ front matter, written with the sites’ generated files and, on the dev server, again when a file undercontent/changes. A file withdraft: trueshows on the dev server and never in a build.
A company repo’s sites/<name>/routes/ are TanStack Router file routes the app serves under /sites/<name>/, inside its shell, and an app’s apps/<app>/sites/<name>/routes/ under /sites/<app>/<name>/ (the site <app>/<name>, its route ids /sites/<app>/<name>/…; a public one answers at <name>.<app>.localhost). The package ships its source for that, and a Node-only entry, sanoma/app/build, which the sanoma bin calls:
import { buildApp } from "sanoma/app/build";import { startApp } from "sanoma/app";
const { distDir, built } = await buildApp(repo, { log: console.log });const app = await startApp(config, { distDir });buildApp(repo) builds the app’s routes and every site as one TanStack Start build with the repo as Vite’s root, and writes only under the repo: .sanoma/app/routeTree.gen.ts, Vite’s cache in .sanoma/app/vite/, and the build in .sanoma/app/build/<key>/ (client/ and server/server.js), where the key covers the app’s version and source directory and every file under sites/ and content/. All of .sanoma/app/ is ignored by its own .gitignore (*), which Tailwind’s scan of the repo honours too, so a build never reads its own output, whatever the repo’s .gitignore says. A build with the same key is reused (built: false), and a new one is built beside it and moved into place, so an app serving the old one keeps it. The server bundle holds everything but the runtime (sanoma/workflows, sanoma/internal/bridge, DBOS, pg, zod), which it imports by file URL, resolved from the sanoma package’s own package.json (manifestFile), so the worker and the app share one copy.
- A site is client code: a site importing the runtime, a connector, DBOS,
pgor a*.server.*file fails the build with “Import denied”. - A site imports React, TanStack’s packages and this app as the app does, from the app’s own install: the company repo depends only on
sanoma. - A folder is a site when it has
routes/and its name is one URL segment (/^[a-z][a-z0-9-]*$/);sitesOf(repo)lists the sites and the refused folders, which the build logs and leaves out. Two pages claiming one path fail the build, naming the path and both files. writeSiteFiles(repo), whichbuildAppcalls first, writessites/__virtual.ts(the listing the route generator reads; committed, never edited),sites/tsconfig.jsonwhen missing,.sanoma/app/tsconfig.jsonevery time: the app’s compiler options (tsconfig.site.json, shipped) with its React, TanStack and route tree, sotsc -p sites/tsconfig.jsonchecks a site’s links against every page; and.sanoma/content.ts, the types ofcontent.appViteConfig({ repo })is the build’s Vite config;appViteConfig()is this package’s own (itsvite.config.ts), the same pipeline with no sites.appSources()gives the app’ssrcandtsconfig.site.jsonby real path.
startApp(config, { dev: { repo } }) serves the app and the repo’s sites from Vite’s dev server instead of a build, behind the same /healthz and login: appDevServer(repo, http) from sanoma/app/build is the build’s Vite config (appViteConfig({ repo }), so the route generator’s options are the build’s) in middleware mode, with hot updates over the app’s own HTTP server, and Start’s server entry imported for each request and handed the same context. On the server, Vite compiles the app’s source and sanoma (whose sanoma/site and sanoma/ui are that source), and leaves the runtime to Node, the copy startApp‘s context holds. An edit to a site or to the app’s source shows without a reload, a Tailwind class in a new file under sites/ is in the app’s stylesheet and each site’s own, and a new site folder is live once it has a route file; a change to sites/__virtual.ts itself needs a restart. It writes the sites’ generated files and Vite’s cache under .sanoma/app/, and no build. It listens on this machine only: the hot updates’ websocket does not pass the login, so startApp refuses dev with any other host. dev.onFileChange, when given, is called with each file the dev server’s watcher sees added, changed or removed (sanoma writes .sanoma/api.ts again on a change to what the config is read from).
A company repo is an ES module package ("type": "module", as sanoma init writes it): Vite names the server entry server.mjs otherwise.
These pages describe sanoma 0.11.24.