Skip to content

std/app ​

From the spec

This page is spec/std/app.md, the specification the compiler and the backends are written from. It is rebuilt from the spec with every deploy (how).

The app framework served over HTTP (spec/app.md says what an app is; the server runtime serves it, server.md). weft run on a project with routes/ and no "main" serves it (PORT, default 3000; HOST, default 0.0.0.0); a program can do the same itself:

weft
import { app } from "std/app"
let server = try await app.serve("./routes", { port: 8080 })   // fails with a NetworkError when it can't listen

What a request reaches ​

In order, the first that answers:

  1. /_weft/<version>/…: the client's files (below), cache-control: public, max-age=31536000, immutable; another version is a 404 (an old page asks a newer server). /_weft/t/<version>/styles.css: a user tree's stylesheet.
  2. /_weft/server/<file>/<name>: a server function's call (server.md); /_weft/live and /_weft/live/…: std/live's connections and tickets (live.md).
  3. A file of static/ (GET, HEAD), with an ETag and cache-control: public, max-age=0.
  4. For GET and HEAD, the user trees the request is served from (below).
  5. The router app.weft exports, when one of its routes matches (a path the router and the files both define is an error when the app starts).
  6. A server.weft endpoint whose folder matches: a raw handler for the method (GET(req)), else a typed method (get(args), server.md), else a 405.
  7. GET /sitemap.xml and GET /robots.txt, unless static/ has them: the sitemap (sitemaps.org) lists every page without path parameters whose robots doesn't say noindex, at its canonical URL (from page({…}) and the literal attributes of a <Head> it always draws) or at the site's address and its path; robots.txt allows everything and names the sitemap. The site's address is weft.toml's site (site = "https://example.com"), else the request's host (and x-forwarded-proto, else http).
  8. A page, rendered on the server: GET/HEAD only (else a 405); no page is a 404. A page whose render panicked shows its error.weft with a 500 (a page can't fail with an error: spec/app.md, The tree).

A function the app gives for a request (the trees function, sandbox, a router's handlers) may fail with any error (! json, as std/http's handlers): the request is answered with a 500 and the error printed (std/auth's AuthError with its status, http.md).

Pages ​

  • A page renders as weft render --html does (ssr.md) at the schema's env, in the request's async context (its server functions run in process and see request()), and is written as a whole document: the page's HTML in <div id="weft">, the head its page({…}) says, the stylesheet, and, when something on it needs the client, the snapshot and the client's boot. cache-control: no-cache.
  • The head. What page({…}) says, under what the page's <Head>s say from its data (platform.md, The document's head). <title> is title, else label, else the path; description is <meta name="description">, canonical <link rel="canonical">, robots <meta name="robots"> ("noindex" also keeps the page out of the sitemap). A page with a description, image or canonical gets Open Graph and Twitter cards (og:type, og:title, og:description, og:image, og:url; twitter:card summary_large_image with an image, else summary). page({…})'s values are literals (language.md, Declarations); a navigation on the client updates every one of these tags.
  • The theme. The stylesheet starts with the @font-face rules of the fonts the client runtime ships that the theme names (dist/weft-client/fonts.css: Geist, the registry theme's sans; served under the runtime's version, /_weft/<runtime version>/rt/fonts/), then the project's theme (theme.weft evaluated over the schema's, theme.md; styles.md, Theme; weft_js::css::theme_css, as src/styles.ts's themeCss): its colours as :root variables, the dark ones under data-mk-color-scheme="dark" (and under prefers-color-scheme: dark while the attribute isn't set), and the page's background, text colour, font and line height, with form controls taking the page's font (Tailwind's preflight). A script in the head sets data-mk-color-scheme on <html> from the browser's colour scheme before the first paint and follows its changes, so the theme's dark colours and dark: classes apply. The env pages render at stays the schema's (env.colorScheme is "light" on the web for now).
  • One page renders at a time per process; the others wait their turn while other requests run. What a render made (its instances, tree and the services' tables) is freed after it (server.md, Decided here).

The client ​

  • At start the app is compiled to JS (weft-js) with the runtime at /_weft/<rt>/rt/ (<rt>: a hash of the runtime's files alone, so every build of one runtime shares it: a hot swap's modules run on the runtime the page loaded) and the app's modules at /_weft/<version>/app/: index.js (the core), app.js (the app entry), boot.js and live.js (std/live's client, loaded by the pages that import it), from dist/weft-client/ (pnpm build:client; or $WEFT_CLIENT). The version is a hash of what was built (the app's modules, its stylesheet and the runtime), so a new build is a new version. Only the modules the app's entry ($app.js) reaches are served; server modules (lib/server/**, server.weft) compile to their server functions' calls only. Without the runtime, pages are served without JS (and the server says so).
  • boot(app, { version, env, dev }) takes the server's page over (ssr.md, Taking over), with the env and formatting (en, UTC) the server rendered at. A <Link> to one of the app's pages navigates in the page (history.pushState; back and forward follow); one to anything else (an endpoint, another site, a user tree) loads from the server. Server functions and typed endpoints go over fetch to the page's server. In development it reloads when the server restarts; under weft dev (editor in the boot options: the protocol's path and the dev token) it loads editor.js instead, which swaps new builds in keeping state and hosts the editor's overlay (spec/editor-protocol.md). A dev build (weft dev) carries source locations, and weft dev's overlay is compiled beside the app's modules (app/$editor/); GET /_weft/dev/version says which build is served.

User trees ​

app.serve(trees, options) takes the trees to serve, first one first (spec/app.md, User trees): a TreeRef (a folder path, or a Tree a std/sandbox store keeps: in memory, a folder or an S3 bucket), a list of them (null entries skipped), or async req => […], a function of the request giving the list.

  • "./routes" (the project's routes/ folder) is the app's own routes; another folder is a user tree kept there as manifest.json (its sources beside it, sandbox.md, Trees), read and compiled again when the manifest's text changes. An S3 tree is checked against its bucket at most once per revalidate (s3.md) and loaded by version before the request goes on.
  • For a GET or HEAD, each tree in turn: a page route of the tree matching the path serves that page; a deleted route at or above the path is a 404; anything else goes to the next tree. After the list, the app's own routes (steps 5–7 above) in every case.
  • A user page renders in its tree's own runtime (sandbox.md), with params and what options.sandbox(req) gives for the request, std/sandbox's RunOptions record: its caps prop (json), the labels it may use of the app (imports: a file using anything else falls back, so the path may fall through to the app's routes; sandbox.md, Imports) and its limits. Without sandbox, a page gets nothing of the app. Its first paint is the page (what its top level and the turns ready after it show), with the app's stylesheet and the tree's. User pages ship no JS yet.
  • options: port (PORT, 3000), host, maxBody, timeout, sandbox. It gives the Server (http.md) once it listens, or fails with a NetworkError.
  • A user tree that can't be loaded, or a user page that fails or panics in its runtime (std/sandbox's RunError), answers 500 and is printed; the app's routes aren't tried.

Decided here ​

  1. The order above (assets, server functions, static, user trees, router, endpoints, pages).
  2. The client's runtime is a prebuilt bundle beside the compiled app, served unbundled as ES modules under a content version; HTML is never cached, assets always.
  3. User pages are rendered on the server only (no client JS yet) and get the app's data as a caps: json prop and the labels their request's imports gives; functions as capabilities are std/sandbox's run.
  4. A user tree's routed file sits under routes/ in its project (so prop params is typed from the route) and its other files under components/ or lib/, found by their ids.

Weft is in development. The reference is the spec as it stands today.