Appearance
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 listenWhat a request reaches
In order, the first that answers:
/_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./_weft/server/<file>/<name>: a server function's call (server.md);/_weft/liveand/_weft/live/…:std/live's connections and tickets (live.md).- A file of
static/(GET,HEAD), with an ETag andcache-control: public, max-age=0. - For
GETandHEAD, the user trees the request is served from (below). - The router
app.weftexports, when one of its routes matches (a path the router and the files both define is an error when the app starts). - A
server.weftendpoint whose folder matches: a raw handler for the method (GET(req)), else a typed method (get(args),server.md), else a 405. GET /sitemap.xmlandGET /robots.txt, unlessstatic/has them: the sitemap (sitemaps.org) lists every page without path parameters whoserobotsdoesn't saynoindex, at itscanonicalURL (frompage({…})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 isweft.toml'ssite(site = "https://example.com"), else the request'shost(andx-forwarded-proto, elsehttp).- A page, rendered on the server:
GET/HEADonly (else a 405); no page is a 404. A page whose render panicked shows itserror.weftwith 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 --htmldoes (ssr.md) at the schema's env, in the request's async context (its server functions run in process and seerequest()), and is written as a whole document: the page's HTML in<div id="weft">, the head itspage({…})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>istitle, elselabel, else the path;descriptionis<meta name="description">,canonical<link rel="canonical">,robots<meta name="robots">("noindex"also keeps the page out of the sitemap). A page with adescription,imageorcanonicalgets Open Graph and Twitter cards (og:type,og:title,og:description,og:image,og:url;twitter:cardsummary_large_imagewith an image, elsesummary).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-facerules 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.weftevaluated over the schema's,theme.md;styles.md, Theme;weft_js::css::theme_css, assrc/styles.ts'sthemeCss): its colours as:rootvariables, the dark ones underdata-mk-color-scheme="dark"(and underprefers-color-scheme: darkwhile 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 setsdata-mk-color-schemeon<html>from the browser's colour scheme before the first paint and follows its changes, so the theme's dark colours anddark:classes apply. The env pages render at stays the schema's (env.colorSchemeis"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.jsandlive.js(std/live's client, loaded by the pages that import it), fromdist/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 overfetchto the page's server. In development it reloads when the server restarts; underweft dev(editorin the boot options: the protocol's path and the dev token) it loadseditor.jsinstead, 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, andweft dev's overlay is compiled beside the app's modules (app/$editor/);GET /_weft/dev/versionsays 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'sroutes/folder) is the app's own routes; another folder is a user tree kept there asmanifest.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 perrevalidate(s3.md) and loaded by version before the request goes on.- For a
GETorHEAD, each tree in turn: a page route of the tree matching the path serves that page; adeletedroute 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), withparamsand whatoptions.sandbox(req)gives for the request,std/sandbox'sRunOptionsrecord: itscapsprop (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 itslimits. Withoutsandbox, 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 theServer(http.md) once it listens, or fails with aNetworkError.- A user tree that can't be loaded, or a user page that fails or panics in its runtime (
std/sandbox'sRunError), answers 500 and is printed; the app's routes aren't tried.
Decided here
- The order above (assets, server functions, static, user trees, router, endpoints, pages).
- 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.
- User pages are rendered on the server only (no client JS yet) and get the app's data as a
caps: jsonprop and the labels their request'simportsgives; functions as capabilities arestd/sandbox'srun. - A user tree's routed file sits under
routes/in its project (soprop paramsis typed from the route) and its other files undercomponents/orlib/, found by their ids.