weft
ir 2.6.0 · warp 1.8.0
generatedwalked out of the package's public entry

@weftjs/core/server

The front door’s own parts, exported so a deployment that needs its own entry point can build one. Discovery, compilation, plan generation, the build and the server.

128exports
128with a doc comment on the declaration

Read out of packages/weft/src/server.ts, the package’s public entry, so this page is the surface itself rather than a description of it.

addressedByDigest function

export function addressedByDigest(path: string): boolean { … }

Whether a path is under a root whose URLs name their own contents.

Raised in this fileE_MODULE_UNREADABLE·E_NO_ASSET·E_NO_PAGE_CSS

packages/weft/src/assets.ts

adoptScript function

export function adoptScript(
  slot: string,
  fragment: CompiledFragment,
  values: Values,
  options: AdoptOptions = {},
): string | null { … }

The payload that binds a slot's template to the markup this render produced, or null for a slot nothing on the client could act on. See spec/client/adoption.md.

Raised in this fileE_CONSISTENCY_MISMATCH·E_DUPLICATE_LAYOUT_HOLE·E_ETAG_STREAMS·E_LAYOUT_HOLE_UNFILLED·E_NO_BODY_SLOT·E_NO_DEFAULT_ROUTE·E_NO_NESTING_SLOT·E_NO_PAGE·E_NO_SLOTS·E_NO_SUCH_FRAGMENT·E_NO_SUCH_LAYOUT·E_REGION_EXECUTOR

packages/weft/src/routes.ts

appHandler function

export async function appHandler(app: App): Promise<Handler> { … }

Make it answerable. Everything interesting already happened in createApp.

Raised in this fileE_ASSETS_NOT_BUILT·E_INTENT_UNSIGNED·E_METHOD·E_NO_ADDRESS·E_NO_PACKAGE·E_NO_ROUTE·E_NO_SUCH_RENDERABLE·E_NO_SUCH_SLOT·E_RENDER_FAILED·E_REQUEST_FAILED

packages/weft/src/serve.ts

bootPrelude function

export function bootPrelude(app: App): string { … }

What the client needs before it can do anything, and the only things it cannot derive. Exported because the boot module has two ways out of a deployment and they must not disagree. See spec/kernel/lifecycle.md.

Raised in this fileE_ASSETS_NOT_BUILT·E_INTENT_UNSIGNED·E_METHOD·E_NO_ADDRESS·E_NO_PACKAGE·E_NO_ROUTE·E_NO_SUCH_RENDERABLE·E_NO_SUCH_SLOT·E_RENDER_FAILED·E_REQUEST_FAILED

packages/weft/src/serve.ts

browserModule function

export function browserModule(
  source: string,
  tree: ModuleTree,
  mountedAt: string,
  options: { comments?: 'keep' | 'strip' } = {},
): string { … }

A client module on its way to the browser: types stripped, and every specifier — bare or relative — rewritten to the URL it is served at, which always ends in .js. That is the whole of it, and it is the alternative to a bundler. See spec/kernel/static.md.

Raised in this fileE_MODULE_UNREADABLE·E_NO_ASSET·E_NO_PAGE_CSS

packages/weft/src/assets.ts

build function

export async function build(root: string, overrides: WeftConfig = {}): Promise<BuildReport> { … }

Compile, generate, bundle, prerender, and write the manifest. The whole of weft build.

Raised in this fileE_MISSING_TEMPLATE·E_NO_BUILD·E_STALE_BUILD

Specified inspec/plan/plan.md

packages/weft/src/build.ts

buildAssets function

export async function buildAssets(input: AssetInput): Promise<AssetTable> { … }

Bundle the stylesheets, walk the modules, and rev every URL by its own contents.

Raised in this fileE_MODULE_UNREADABLE·E_NO_ASSET·E_NO_PAGE_CSS

packages/weft/src/assets.ts

byteReport function

export async function byteReport(app: App): Promise<ByteReport> { … }

What a reader downloads: the modules walked, and each one compressed as it would ship.

Raised in this fileE_NO_SUCH_ROUTE

packages/weft/src/devtools/report.ts

cacheControl function

export function cacheControl(immutable: boolean): string { … }

The same decision, for a caller holding the fact rather than the asset. Nothing may assume immutability from a path: public/ is also served at the name its author wrote.

Raised in this fileE_MODULE_UNREADABLE·E_NO_ASSET·E_NO_PAGE_CSS

Specified inspec/kernel/lifecycle.md

packages/weft/src/assets.ts

cacheControlFor function

export function cacheControlFor(asset: Asset): string { … }

A year and immutable for a digest-bearing URL, revalidate-always for a stable one.

Raised in this fileE_MODULE_UNREADABLE·E_NO_ASSET·E_NO_PAGE_CSS

packages/weft/src/assets.ts

chainFor function

export function chainFor(pattern: string, nested: readonly DiscoveredNested[]): DiscoveredNested[] { … }

The nested layouts that wrap a route, outermost first.

Matched segment by segment rather than by string prefix, because /blog is not a prefix of /blogroll in any sense a router would recognise — and a layout that wrapped the wrong subtree would do it silently, on a page that renders.

Raised in this fileE_BAD_SEGMENT·E_DUPLICATE_ROUTE·E_NESTED_LAYOUT_DATA·E_NO_APP_DIR·E_ORPHAN_CSS·E_SCOPED_NO_TEMPLATE·E_WILDCARD_NOT_LAST

packages/weft/src/convention.ts

checkJsBudgets function

export function checkJsBudgets(
  routes: readonly GeneratedRoute[],
  measured: JsMeasurement,
  baseline?: number,
): JsVerdict[] { … }

Every declared ceiling this measurement breaks, and every growth cap it exceeds.

Returned rather than thrown: the build prints all of them. A gate that reports the first failure makes a reader fix one number, rebuild, and find the next.

Raised in this fileE_JS_BUDGET·E_JS_GROWTH

packages/weft/src/js-budget.ts

compileApp function

export async function compileApp(
  discovered: Discovered,
  options: { outDir: string; types?: boolean },
): Promise<CompiledApp> { … }

Compile everything the convention found, in dependency order, with the framework's own files staged.

Raised in this fileE_NO_FRAGMENT·E_NO_LIST_HOLE·E_NOT_COMPILED

packages/weft/src/compile.ts

composedIn function

export function composedIn(app: CompiledApp, fragment: CompiledFragment): CompiledFragment[] { … }

Which named fragments a fragment renders, read from the templates it was sealed with — a page composing <Card/> needs card.css, and matching template versions answers that without a second dependency graph.

Raised in this fileE_NO_FRAGMENT·E_NO_LIST_HOLE·E_NOT_COMPILED

packages/weft/src/compile.ts

createApp function

export async function createApp(root: string, options: CreateOptions = {}): Promise<App> { … }

A folder into an application: discover, compile, generate, bind, and wire the channel.

Raised in this fileE_ASSETS_NOT_BUILT·E_INTENT_UNSIGNED·E_METHOD·E_NO_ADDRESS·E_NO_PACKAGE·E_NO_ROUTE·E_NO_SUCH_RENDERABLE·E_NO_SUCH_SLOT·E_RENDER_FAILED·E_REQUEST_FAILED

packages/weft/src/serve.ts

defineConfig function

export function defineConfig(config: WeftConfig): WeftConfig { … }

An identity function that exists for the types, so a config file is checked as it is written.

Raised in this fileE_BLOCKED_PORT·E_CONFIG_NO_DEFAULT·E_NO_CAPABILITY_CHECK·E_NO_RATE_LIMIT·E_NO_SUCH_REGION·E_NO_VERIFIER·E_TAGS_PROCESS_SCOPED

packages/weft/src/config.ts

describeJsVerdict function

export function describeJsVerdict(verdict: JsVerdict): string { … }

A refused budget, as the sentence the build prints.

Two codes rather than one, because the two failures need different answers: a ceiling says the page is too big and a growth cap says it got bigger, and only the second is a diff somebody just made. Both name the route and the declaration, and neither claims to know which slot is responsible — there is no bundler here, so the client is the application's and not a slot's share of it, and the message says so rather than implying an attribution it cannot make.

Raised in this fileE_JS_BUDGET·E_JS_GROWTH

packages/weft/src/js-budget.ts

dev function

export async function dev(
  root: string,
  overrides: WeftConfig = {},
  onReload?: (event: ReloadEvent) => void,
): Promise<DevServer> { … }

The dev server, and the one thing it cannot do in place.

A .tsx or .css change is rebuilt where it stands. A .ts change is not: an imported module cannot be un-imported, so the child asks to be replaced rather than serving a stale closure.

packages/weft/src/dev.ts

devtoolsFor function

export function devtoolsFor(app: App): DevtoolsHandler | null { … }

Devtools for this application, or nothing.

Returning null rather than a handler that declines is the whole of the "no cost" claim: with devtools off there is no closure to call and nothing to match against.

Raised in this fileE_DEVTOOLS_NOT_DEV·E_NO_SUCH_PAGE

packages/weft/src/devtools.ts

discover function

export async function discover(root: string, srcDir = 'app'): Promise<Discovered> { … }

Read the convention once. The single source of the route table, and the only one.

Raised in this fileE_BAD_SEGMENT·E_DUPLICATE_ROUTE·E_NESTED_LAYOUT_DATA·E_NO_APP_DIR·E_ORPHAN_CSS·E_SCOPED_NO_TEMPLATE·E_WILDCARD_NOT_LAST

packages/weft/src/convention.ts

fileFor function

export function fileFor(pattern: string): string { … }

Where a route's document is written, so a CDN can serve the directory as it stands.

Raised in this fileE_MISSING_DOCUMENT

packages/weft/src/static.ts

formatReport function

export function formatReport(report: BuildReport): string { … }

The build report: a line per route, then the L0 section — which pages became files, and why not.

Raised in this fileE_MISSING_TEMPLATE·E_NO_BUILD·E_STALE_BUILD

packages/weft/src/build.ts

fragmentReport function

export function fragmentReport(app: App): FragmentReport[] { … }

Every compiled fragment, read out of the table the renderer itself uses.

Raised in this fileE_NO_SUCH_ROUTE

packages/weft/src/devtools/report.ts

frameworkStyles function

export async function frameworkStyles(): Promise<string> { … }

The framework's own stylesheet, which an application's is appended after.

Raised in this fileE_NO_FRAGMENT·E_NO_LIST_HOLE·E_NOT_COMPILED

packages/weft/src/compile.ts

generateRoutes function

export async function generateRoutes(options: GenerateOptions): Promise<Generated> { … }

The convention into plans. The two hundred lines of wiring per application that became one file.

Raised in this fileE_CONSISTENCY_MISMATCH·E_DUPLICATE_LAYOUT_HOLE·E_ETAG_STREAMS·E_LAYOUT_HOLE_UNFILLED·E_NO_BODY_SLOT·E_NO_DEFAULT_ROUTE·E_NO_NESTING_SLOT·E_NO_PAGE·E_NO_SLOTS·E_NO_SUCH_FRAGMENT·E_NO_SUCH_LAYOUT·E_REGION_EXECUTOR

packages/weft/src/routes.ts

isDirectory function

export async function isDirectory(path: string): Promise<boolean> { … }

Whether the path is a directory. False for anything that cannot be read, including absent.

Raised in this fileE_MODULE_UNREADABLE·E_NO_ASSET·E_NO_PAGE_CSS

packages/weft/src/assets.ts

isScopedSheet function

export function isScopedSheet(file: string): boolean { … }

Is this the scoped half of a component's styling, rather than the global one?

packages/weft/src/scoped.ts

listHole function

export function listHole(fragment: CompiledFragment): string { … }

The binding name of a fragment's list hole, taken from the IR rather than written down, so a rename in the .tsx cannot leave a loader filling a hole that no longer exists.

Raised in this fileE_NO_FRAGMENT·E_NO_LIST_HOLE·E_NOT_COMPILED

packages/weft/src/compile.ts

loadBuild function

export async function loadBuild(discovered: Discovered, config: ResolvedConfig): Promise<CompiledApp> { … }

The build, loaded back. weft start runs no compiler — it reads the sealed templates the build wrote and validates each on the way in, so what is served is byte-for-byte what was measured.

Raised in this fileE_MISSING_TEMPLATE·E_NO_BUILD·E_STALE_BUILD

packages/weft/src/build.ts

loadConfig function

export async function loadConfig(root: string, overrides: WeftConfig = {}): Promise<ResolvedConfig> { … }

Load weft.config.ts, apply overrides, and fill in the defaults. An absent file is fine.

Raised in this fileE_BLOCKED_PORT·E_CONFIG_NO_DEFAULT·E_NO_CAPABILITY_CHECK·E_NO_RATE_LIMIT·E_NO_SUCH_REGION·E_NO_VERIFIER·E_TAGS_PROCESS_SCOPED

packages/weft/src/config.ts

loadDocuments function

export async function loadDocuments(config: ResolvedConfig): Promise<Map<string, ServedDocument>> { … }

The build's documents, loaded back. No manifest is not an error — a static directory is a tier rather than a requirement. A manifest naming a file that is not there is.

Raised in this fileE_MISSING_DOCUMENT

packages/weft/src/static.ts

loadIntents function

export async function loadIntents(root: string, files: readonly string[]): Promise<IntentManifest> { … }

Load app/intents/** into a closed set, refusing two intents that would share an id.

Raised in this fileE_INTENT_ID_COLLISION·E_INTENT_NAME_TAKEN

packages/weft/src/intents.ts

measureClientJs function

export async function measureClientJs(assets: AssetTable, appClient?: string): Promise<JsMeasurement> { … }

What a page downloads, measured over the graph the browser will actually walk.

The walk itself is moduleGraph in assets.ts, because the document preloads exactly this set and a second copy of the traversal here is how the figure and the page came to disagree once already. Each module is compressed on its own, because that is how each one arrives — a bundler's figure would be smaller than the truth and this framework has no bundler to be smaller with.

Raised in this fileE_JS_BUDGET·E_JS_GROWTH

Specified inspec/FINDINGS.md·spec/kernel/budgets.md·spec/kernel/static.md

packages/weft/src/js-budget.ts

moduleFileName function

export function moduleFileName(served: string, tree: ModuleTree): string { … }

The file behind a served module URL, which is the inverse of servedModuleName.

Raised in this fileE_MODULE_UNREADABLE·E_NO_ASSET·E_NO_PAGE_CSS

packages/weft/src/assets.ts

moduleFiles function

export async function moduleFiles(assets: AssetTable, prelude = ''): Promise<Map<string, string>> { … }

Every module file the deployment can be asked for, at the URL it answers on: every direct child of every mounted tree, deliberately not the reachable import graph. prelude is prepended to the boot module for the same reason the server prepends it there. See spec/kernel/static.md.

Raised in this fileE_MODULE_UNREADABLE·E_NO_ASSET·E_NO_PAGE_CSS

packages/weft/src/assets.ts

moduleGraph function

export async function moduleGraph(assets: AssetTable, appClient?: string): Promise<string[]> { … }

Every module a page will fetch, in the order the browser will discover them. Walked rather than declared, and import() is deliberately not followed.

One implementation, two callers — the byte budget measures this set and the document preloads it. See spec/kernel/static.md.

Raised in this fileE_MODULE_UNREADABLE·E_NO_ASSET·E_NO_PAGE_CSS

packages/weft/src/assets.ts

moduleIdOf function

export function moduleIdOf(root: string, file: string): string { … }

A module's identity, relative to the project — so an id does not depend on the checkout path.

Raised in this fileE_INTENT_ID_COLLISION·E_INTENT_NAME_TAKEN

packages/weft/src/intents.ts

modulePreloads function

export function modulePreloads(graph: readonly string[], boot: string): string { … }

The graph as <link rel="modulepreload">, for the head of a document — the whole fix for the waterfall, and it needs no 103. The boot module is left out: it is already a <script src> in the same head.

Raised in this fileE_MODULE_UNREADABLE·E_NO_ASSET·E_NO_PAGE_CSS

packages/weft/src/assets.ts

navOf function

export function navOf(discovered: Discovered): { href: string; label: string }[] { … }

Every route a nav can link to: one with a param has no single URL to point at.

Raised in this fileE_CONSISTENCY_MISMATCH·E_DUPLICATE_LAYOUT_HOLE·E_ETAG_STREAMS·E_LAYOUT_HOLE_UNFILLED·E_NO_BODY_SLOT·E_NO_DEFAULT_ROUTE·E_NO_NESTING_SLOT·E_NO_PAGE·E_NO_SLOTS·E_NO_SUCH_FRAGMENT·E_NO_SUCH_LAYOUT·E_REGION_EXECUTOR

packages/weft/src/routes.ts

paramsOf function

export function paramsOf(pattern: string): string[] { … }

The params a pattern cannot be resolved without. A trailing * is one of them.

Raised in this fileE_NO_SUCH_ROUTE

packages/weft/src/devtools/report.ts

patternOf function

export function patternOf(relativePath: string): string { … }

A file path becomes a route pattern. index is the directory itself, [name] is a param, and [...] or [...rest] is the wildcard — which the router requires to be last, so a file that puts it anywhere else is a build error here rather than a router error later.

Raised in this fileE_BAD_SEGMENT·E_DUPLICATE_ROUTE·E_NESTED_LAYOUT_DATA·E_NO_APP_DIR·E_ORPHAN_CSS·E_SCOPED_NO_TEMPLATE·E_WILDCARD_NOT_LAST

packages/weft/src/convention.ts

prerender function

export async function prerender(app: App): Promise<Prerendered> { … }

Render every structurally static page twice and keep the ones whose bytes matched.

Raised in this fileE_MISSING_DOCUMENT

packages/weft/src/static.ts

revAssets function

export async function revAssets(dir: string, revved: boolean): Promise<RevvedAssets> { … }

Walk it, hash each file, and mount every one under its own digest.

Raised in this fileE_MODULE_UNREADABLE·E_NO_ASSET·E_NO_PAGE_CSS

packages/weft/src/assets.ts

rewriteUrls function

export function rewriteUrls(css: string, fromDir: string, byPath: ReadonlyMap<string, string>): string { … }

Every url() in a stylesheet that names a file in app/assets/, pointed at its revved URL. Resolved against the sheet's own directory; anything not relative is left exactly as written, and a relative one that resolves to nothing is E_NO_ASSET. See spec/kernel/static.md.

Raised in this fileE_MODULE_UNREADABLE·E_NO_ASSET·E_NO_PAGE_CSS

packages/weft/src/assets.ts

routeReport function

export function routeReport(app: App): RouteReport[] { … }

Every route, from the running application rather than from a second derivation.

Raised in this fileE_NO_SUCH_ROUTE

packages/weft/src/devtools/report.ts

scaffold function

export async function scaffold(options: ScaffoldOptions): Promise<Scaffolded> { … }

Write a new application. No step here is one you cannot read afterwards.

Raised in this fileE_BAD_NAME·E_NO_TEMPLATE·E_NOT_EMPTY

packages/weft/src/scaffold.ts

scopeAttribute function

export function scopeAttribute(stem: string): string { … }

A stem's scope attribute, e.g. data-w-4f3a91c2.

Derived from the path rather than from the contents, and that is the point: editing the template or the sheet must not change the attribute, or every scoped page's bundle would churn on every edit. Two files with the same stem — card.tsx and card.scoped.css — derive the same id independently, which is why nothing has to carry a pairing between them.

packages/weft/src/scoped.ts

scopeCss function

export function scopeCss(css: string, attribute: string): string { … }

Narrow every selector in a stylesheet to one scope attribute.

The transform is the one the field agreed on: the attribute joins the **last** compound selector, before any pseudo-element. .row .cell becomes .row .cell[data-w-x] — the descendant may be anywhere, the thing being styled may not. .row:hover becomes .row[data-w-x]:hover, because an attribute is part of the compound and a pseudo-class is a filter on it.

This is a tokeniser and not a CSS parser, and it is written that way on purpose: a parser would have to keep up with every at-rule CSS grows, and the only thing this needs to be right about is where a selector list ends. So it tracks strings, comments, brackets and brace depth, treats anything before a { at depth zero as a selector list, and recurses into the at-rules that contain selectors while leaving alone the ones that do not — @keyframes percentages are not selectors, and @font-face has none.

packages/weft/src/scoped.ts

scopedSheets function

export function scopedSheets(discovered: Discovered): string[] { … }

Every .scoped.css the convention found, wherever in the tree. One place that knows all six kinds of sheet.

Raised in this fileE_NO_FRAGMENT·E_NO_LIST_HOLE·E_NOT_COMPILED

packages/weft/src/compile.ts

scopeStem function

export function scopeStem(file: string): string { … }

app/fragments/card.tsx and app/fragments/card.scoped.css both stem to app/fragments/card.

packages/weft/src/scoped.ts

serveApp function

export async function serveApp(app: App): Promise<Serving> { … }

Put it on a port.

Raised in this fileE_ASSETS_NOT_BUILT·E_INTENT_UNSIGNED·E_METHOD·E_NO_ADDRESS·E_NO_PACKAGE·E_NO_ROUTE·E_NO_SUCH_RENDERABLE·E_NO_SUCH_SLOT·E_RENDER_FAILED·E_REQUEST_FAILED

packages/weft/src/serve.ts

servedModuleName function

export function servedModuleName(fileName: string, tree: ModuleTree): string { … }

The URL a client module is served at, which always ends in .js. A static host reads .ts as an MPEG transport stream and the browser then refuses the module — see spec/kernel/static.md.

Raised in this fileE_MODULE_UNREADABLE·E_NO_ASSET·E_NO_PAGE_CSS

packages/weft/src/assets.ts

serveHandler function

export async function serveHandler(handler: Handler): Promise<Serving> { … }

Put a handler on a TCP port.

Raised in this fileE_ASSETS_NOT_BUILT·E_INTENT_UNSIGNED·E_METHOD·E_NO_ADDRESS·E_NO_PACKAGE·E_NO_ROUTE·E_NO_SUCH_RENDERABLE·E_NO_SUCH_SLOT·E_RENDER_FAILED·E_REQUEST_FAILED

packages/weft/src/serve.ts

sitemapFor function

export function sitemapFor(objects: readonly SiteObject[], origin: string): string { … }

Every document this build answers, as a sitemap.

The route table is the framework's, and so is the set of URLs a build actually wrote — which is why a hand-maintained sitemap in public/ is a list that is wrong the first time somebody adds a page. This is generated from the objects that were published, so it cannot name a URL that does not exist or miss one that does.

Documents only. An asset is not a page and listing revved bundles would be telling a crawler to index the contents of a cache.

It needs an origin because a sitemap's entries are absolute by specification, and an origin is the one thing a build genuinely cannot know: the same output is served from a preview URL, a staging host and a domain. So it is site.origin in the config, and without it no sitemap is written rather than one full of guesses.

packages/weft/src/site.ts

siteObjects function

export async function siteObjects(dir: string): Promise<SiteObject[]> { … }

Every object a build publishes, by the URL it answers.

packages/weft/src/site.ts

slotHoles function

export function slotHoles(fragment: CompiledFragment): string[] { … }

Slot boundaries a fragment leaves for somebody else to fill, in document order.

Raised in this fileE_NO_FRAGMENT·E_NO_LIST_HOLE·E_NOT_COMPILED

packages/weft/src/compile.ts

slugOf function

export function slugOf(pattern: string): string { … }

A route pattern as a filename component, so a per-route bundle has a readable name.

Raised in this fileE_MODULE_UNREADABLE·E_NO_ASSET·E_NO_PAGE_CSS

packages/weft/src/assets.ts

stageAssets function

export async function stageAssets(root: string, outDir: string): Promise<Record<string, string>> { … }

Stage them, and answer with where each one went. Beside assets/ rather than inside it: that directory is published, and these are working copies of framework source — a scratch directory that is also the deployment shipped .tsx files and a tsconfig.json at the site root once.

Raised in this fileE_NO_FRAGMENT·E_NO_LIST_HOLE·E_NOT_COMPILED

packages/weft/src/compile.ts

startHandler function

export async function startHandler(root: string, overrides: WeftConfig = {}): Promise<Handler> { … }

weft start, up to the point where something listens.

The whole of the start path is here — load the config, discover the tree, load the sealed templates the build wrote, bind the ports — and none of the socket is. The CLI puts the result on a TCP port; a platform that owns the socket calls the handler directly. No compiler runs either way, which is the property weft start exists to have: a deployment serves the templates that were reviewed, not templates it produced again from source that may have moved underneath it.

It is deliberately a whole-application boot rather than a per-request one. Reading ninety sealed templates and three hundred prerendered documents is work with a fixed answer, so a host that reuses a process pays for it once and every request after that is served from memory.

packages/weft/src/start.ts

staticVerdict function

export function staticVerdict(input: StaticInput): StaticVerdict { … }

The structural half. Each refusal names the page's own vocabulary rather than the mechanism.

Raised in this fileE_MISSING_DOCUMENT

packages/weft/src/static.ts

typeOf function

export function typeOf(path: string): string { … }

A content type from an extension. Unknown extensions are octet-stream rather than guessed.

Raised in this fileE_MODULE_UNREADABLE·E_NO_ASSET·E_NO_PAGE_CSS

packages/weft/src/assets.ts

weftAssets function

export function weftAssets(table: () => AssetTable): AssetPort { … }

What a route needs before it has been rendered, which is the whole of what 103 is for. Asked while the envelope is still open, so answering costs a map lookup rather than a render, and only what is *critical* goes in. See spec/kernel/lifecycle.md.

Raised in this fileE_MODULE_UNREADABLE·E_NO_ASSET·E_NO_PAGE_CSS

Specified inspec/kernel/ports.md

packages/weft/src/assets.ts

whyPage function

export async function whyPage(
  app: App,
  pattern: string,
  query: URLSearchParams,
  headers: Headers,
  ports: Ports,
): Promise<WhyPage> { … }

weft why, for a route, against this request.

The DAG, the waves, the critical path and the budget diagnostics are @weftjs/plan's why — the same function and the same input the CLI has, so the page cannot say something the command would not. What the page adds is the half the CLI has no request for: the cache key each slot resolves to *now*, and the one line from resolveKey saying which read put identity in it.

A pattern with params has no key until somebody says what they are. Rather than resolve against an empty string and print a key that describes no page anyone will ever request, the params are named and the keys section is refused.

Raised in this fileE_NO_SUCH_ROUTE

packages/weft/src/devtools/report.ts

writeSite function

export async function writeSite(
  dir: string,
  out: string,
  options: { origin?: string } = {},
): Promise<SiteReport> { … }

The build, laid out as a directory a static host can serve.

The counterpart to weft upload for every host that takes a folder rather than a key space — a CDN's origin, an object store synced from disk, a platform's build output. What comes out needs no rules applied to it: the documents are at the paths they answer and every URL they reference resolves beside them.

packages/weft/src/site.ts

ConventionError class

export class ConventionError extends Error {
  code: string

  constructor(code: string, message: string) {
    super(`${code} — ${message}`)
    this.name = 'ConventionError'
    this.code = code
  }
}

A file-tree refusal: a duplicate route, a wildcard that is not last, an orphan stylesheet.

Raised in this fileE_BAD_SEGMENT·E_DUPLICATE_ROUTE·E_NESTED_LAYOUT_DATA·E_NO_APP_DIR·E_ORPHAN_CSS·E_SCOPED_NO_TEMPLATE·E_WILDCARD_NOT_LAST

packages/weft/src/convention.ts

DevtoolsError class

export class DevtoolsError extends Error {
  code: string

  constructor(code: string, message: string) {
    super(`${code} — ${message}`)
    this.name = 'DevtoolsError'
    this.code = code
  }
}

What devtools knows, derived from the App object and from nothing else.

Everything here is already in memory by the time a request is served: the generated plan, the compiled fragments, the intent manifest and the asset table. Nothing in this file compiles, renders, walks the file tree for routes or re-infers an effect set, because a devtools page that computed its own answer would be a second answer — and the day the two disagreed, the one you were looking at would be the wrong one.

The same argument decides where the numbers come from. Bytes are read off assets that exist, key reasons come from resolveKey, and the DAG comes from @weftjs/plan's why. A number nobody measured is not printed.

Raised in this fileE_NO_SUCH_ROUTE

packages/weft/src/devtools/report.ts

GenerateError class

export class GenerateError extends Error {
  code: string

  constructor(code: string, message: string) {
    super(`${code} — ${message}`)
    this.name = 'GenerateError'
    this.code = code
  }
}

A generation refusal, naming the file rather than the mechanism.

Raised in this fileE_CONSISTENCY_MISMATCH·E_DUPLICATE_LAYOUT_HOLE·E_ETAG_STREAMS·E_LAYOUT_HOLE_UNFILLED·E_NO_BODY_SLOT·E_NO_DEFAULT_ROUTE·E_NO_NESTING_SLOT·E_NO_PAGE·E_NO_SLOTS·E_NO_SUCH_FRAGMENT·E_NO_SUCH_LAYOUT·E_REGION_EXECUTOR

packages/weft/src/routes.ts

AdoptOptions interface

export interface AdoptOptions {
  /** Extra value names beyond the ones a client-owned derived expression is seen to read. */
  expose?: readonly string[]
  /** Refreshable over the channel, which is what tells the client to connect on load. */
  live?: boolean
  /** What the client queries to find the region. Defaults to the slot's own wrapper. */
  selector?: string
  /**
   * `refresh(everyMs, { when })` from the plan: the design's stated fallback for push invalidation
   * across a tier boundary. See `spec/kernel/composition.md`.
   */
  refresh?: { everyMs: number; when?: readonly string[] }
}

The adopt payload, derived rather than written, from what the compiler put in the template.

Raised in this fileE_CONSISTENCY_MISMATCH·E_DUPLICATE_LAYOUT_HOLE·E_ETAG_STREAMS·E_LAYOUT_HOLE_UNFILLED·E_NO_BODY_SLOT·E_NO_DEFAULT_ROUTE·E_NO_NESTING_SLOT·E_NO_PAGE·E_NO_SLOTS·E_NO_SUCH_FRAGMENT·E_NO_SUCH_LAYOUT·E_REGION_EXECUTOR

packages/weft/src/routes.ts

App interface

export interface App {
  config: ResolvedConfig
  discovered: Discovered
  compiled: CompiledApp
  intents: IntentManifest
  /**
   * Fragments a client may ask for by opaque id, from `app/renderables/`. Empty means the registry
   * answers none, so a client naming one is `E_NO_SUCH_RENDERABLE`.
   */
  catalogue: Catalogue
  routes: GeneratedRoute[]
  store: StorePort
  hub: ChannelHub
  /**
   * What each open channel is: which page, and whose session. A channel has no request, so the
   * client says where it is when it opens one.
   */
  at: Map<string, Connection>
  assets: AssetTable
  /**
   * L0. Documents the build resolved and proved invariant, by the path each one answers. Populated
   * by `weft start` and empty everywhere else.
   */
  documents: Map<string, ServedDocument>
  diagnostics: string[]
  /**
   * What this deployment resolved about its own regions,
  …

A built application: its routes, its ports, its hub, and everything a page can ask about itself.

Raised in this fileE_ASSETS_NOT_BUILT·E_INTENT_UNSIGNED·E_METHOD·E_NO_ADDRESS·E_NO_PACKAGE·E_NO_ROUTE·E_NO_SUCH_RENDERABLE·E_NO_SUCH_SLOT·E_RENDER_FAILED·E_REQUEST_FAILED

Specified inspec/plan/plan.md

packages/weft/src/serve.ts

Asset interface

export interface Asset {
  body: string | Uint8Array
  type: string
  immutable: boolean
}

Every URL the browser fetches, revved. A production URL carries a digest of what it contains and is immutable for a year; weft dev serves the same bytes at a stable name.

The table, the three roots and the three cache policies are spec/kernel/static.md.

Raised in this fileE_MODULE_UNREADABLE·E_NO_ASSET·E_NO_PAGE_CSS

packages/weft/src/assets.ts

AssetInput interface

export interface AssetInput {
  /**
   * One bundle per route, in cascade order: framework, application, layout, then every fragment the
   * page renders. Content-addressed, so two pages whose CSS is identical share a cache entry.
   */
  pageCss: Map<string, string>
  /** `public/`, copied: every file at the path it was written at, and nothing else. */
  publicDir: string
  /** `app/assets/`, processed: every file under a digest, and reachable no other way. */
  assetsDir?: string
  runtime: ModuleTree
  warp: ModuleTree
  client: ModuleTree
  /** `app/client.ts` and anything beside it: the application's own browser code. */
  app?: ModuleTree
  /** `app/assets/`, already walked — the caller needs it first, to rewrite `url()` before concatenating. */
  assets?: RevvedAssets
  /** `false` in dev: stable names, never stored. */
  revved: boolean
}

What the asset build needs: what each route links, and where the framework's own files are.

Raised in this fileE_MODULE_UNREADABLE·E_NO_ASSET·E_NO_PAGE_CSS

packages/weft/src/assets.ts

AssetRow interface

export interface AssetRow {
  href: string
  bytes: number
  immutable: boolean
  type: string
}

One asset the browser will fetch, its size, and what it will be told about caching it.

Raised in this fileE_NO_SUCH_ROUTE

packages/weft/src/devtools/report.ts

AssetTable interface

export interface AssetTable {
  /** Everything served verbatim, by path. */
  files: Map<string, Asset>
  /** Module trees, by the prefix they are mounted at. */
  trees: Map<string, ModuleTree>
  /** The one stylesheet a page links. */
  pageCss(pattern: string): string
  /** The client entry a layout loads. */
  boot: string
  /** `app/client.ts`, when the application has one. Imported by the boot after adoption. */
  app?: string
  /**
   * A file from `public/`, by the path an author wrote. Unknown paths throw: a missing asset
   * should fail the render that referenced it, not become a 404 nobody sees until production.
   */
  asset(path: string): string
  /** Original path to revved href, for a build artifact a CDN can be pointed at. */
  manifest: Record<string, string>
  /** True when URLs carry a digest, which is the only state in which they can be cached. */
  revved: boolean
}

Every URL the browser will fetch, and the digest that makes it immutable.

Built after the generator has said which stylesheets each page links, because an href carries a hash of the bundle's contents — so there is one late binding here rather than an unrevved URL.

Raised in this fileE_MODULE_UNREADABLE·E_NO_ASSET·E_NO_PAGE_CSS

packages/weft/src/assets.ts

BuildReport interface

export interface BuildReport {
  outDir: string
  templates: number
  /** What a page downloads, and every declared ceiling it broke. One number for the application:
   * there is no bundler and therefore no per-route JavaScript. */
  client: { raw: number; brotli: number; modules: number; baseline?: number }
  routes: { pattern: string; slots: number; markupBytes: number; styles: string[]; live: string[] }[]
  intents: { id: string; name: string; module: string }[]
  /** The catalogue: what a client on this deployment may ask to have rendered, and by what. */
  renderables: {
    id: string
    name: string
    by: string
    module: string
    capabilities: string[]
    signed: boolean
  }[]
  /** Every region a route composes, and where this deployment's registry says it is. */
  regions: { region: string; route: string; locus: string; where: string }[]
  assets: { href:
  …

What a deployment needs, written down: sealed templates, the generated plan, the intent manifest, every revved asset and a byte report. routes.json is reviewable because the plan is data rather than a function that runs. Nothing is minified — see spec/kernel/budgets.md.

Raised in this fileE_MISSING_TEMPLATE·E_NO_BUILD·E_STALE_BUILD

packages/weft/src/build.ts

ByteReport interface

export interface ByteReport {
  /** False in dev, where a URL carries no digest and therefore cannot be cached at all. */
  revved: boolean
  assets: AssetRow[]
  totalBytes: number
  trees: TreeRow[]
  boot: string
  app?: string
  routes: {
    pattern: string
    markupBytes: number
    stylesheet: string
    stylesheetBytes: number | null
  }[]
}

What a page downloads, walked and compressed the way it actually arrives.

Raised in this fileE_NO_SUCH_ROUTE

packages/weft/src/devtools/report.ts

CompiledApp interface

export interface CompiledApp {
  /**
   * By logical name: `layout`, `error`, `markup`, `route:/blog/:slug`, `slot:header`,
   * `fragment:card`, and `nested:/dashboard` for a layout scoped to a subtree of the route table.
   */
  fragments: Record<string, CompiledFragment>
  diagnostics: string[]
  /** Every sealed template, for a build artifact and for the channel's template lookup. */
  templates: TemplateIR[]
}

Every sealed template this application has, by the name the convention gave it.

Raised in this fileE_NO_FRAGMENT·E_NO_LIST_HOLE·E_NOT_COMPILED

packages/weft/src/compile.ts

CompiledFragment interface

export interface CompiledFragment {
  entry: TemplateIR
  templates: TemplateIR[]
  resolve: Resolver
  /** Project-relative, for a diagnostic that has to name a file. */
  file: string
  /**
   * The bytes on disk that produced this IR. Carried rather than left for the caller to read: a
   * caller reading the path itself could read a file that has since changed.
   */
  source: string
}

The application's own fragments, compiled by the real compiler, once. Nothing downstream holds a hand-written IR — a cache class, a read set or a hole is the one the compiler inferred.

Raised in this fileE_NO_FRAGMENT·E_NO_LIST_HOLE·E_NOT_COMPILED

packages/weft/src/compile.ts

Connection interface

export interface Connection {
  /** The path the client was on when it opened the channel, params and query included. */
  path: string
  /** The channel connection's own cookie header, verbatim. */
  cookie: string
  /**
   * The most recent invalidation this client says it has been told about. Only a turn sends it: the
   * journal is a record rather than a queue, so without a high-water mark one write becomes one
   * refresh per turn. See `spec/kernel/transport.md`.
   */
  since?: number
  /**
   * Routes this connection has been *told about*, by pattern. Held so a description can be scored —
   * see `spec/plan/profile.md`.
   */
  described?: Set<string>
}

One channel's server-side state: where it is, and what it was told it holds.

Raised in this fileE_ASSETS_NOT_BUILT·E_INTENT_UNSIGNED·E_METHOD·E_NO_ADDRESS·E_NO_PACKAGE·E_NO_ROUTE·E_NO_SUCH_RENDERABLE·E_NO_SUCH_SLOT·E_RENDER_FAILED·E_REQUEST_FAILED

packages/weft/src/serve.ts

CreateOptions interface

export interface CreateOptions extends WeftConfig {
  mode?: Mode
  /** Supplied by `weft start`, which reads sealed templates instead of running the compiler. */
  compiled?: CompiledApp
}

Config overrides, plus whether to compile or to load a build.

Raised in this fileE_ASSETS_NOT_BUILT·E_INTENT_UNSIGNED·E_METHOD·E_NO_ADDRESS·E_NO_PACKAGE·E_NO_ROUTE·E_NO_SUCH_RENDERABLE·E_NO_SUCH_SLOT·E_RENDER_FAILED·E_REQUEST_FAILED

packages/weft/src/serve.ts

DevServer interface

export interface DevServer {
  url: string
  /**
   * What this deployment bound that will not do what it says — an intent whose capability nothing
   * grants, a signature nothing can check, a replay window narrower than the deployment.
   *
   * Surfaced here because `weft dev` is where somebody can act on it. Every one of these is also a
   * named refusal at request time, and a 501 during a demo is a bad way to learn that a config file
   * is missing a line.
   */
  warnings: string[]
  close(): Promise<void>
}

weft dev: serve, and rebuild what changed.

Two kinds of change, because they are genuinely different and pretending otherwise makes one of them silently not work.

A .tsx or a .css is **data**: the framework reads it, compiles or concatenates it, and holds the result. Rebuilding it in place is exact, and it keeps what a restart would throw away — the store's entries, open channels, and a page that is mid-delta.

A .ts is **code**, and code that has been imported cannot be un-imported. ESM has no cache to invalidate: re-importing a loader returns the module from the first time, and its own imports are cached a level deeper still, so nothing short of a new process picks up an edited helper. So a .ts change asks for a restart, and weft dev runs a supervisor that gives it one.

The alternative — busting the cache with a query string on the entry module — reloads the file you edited and none of the files it imports, which is worse than not reloading at all: it works often enough to be trusted and fails silently the rest of the time.

packages/weft/src/dev.ts

Discovered interface

export interface Discovered {
  root: string
  srcDir: string
  /** Absent when the application has no layout of its own and gets the framework's. */
  layout?: string
  layoutCss?: string
  /** `app/layout.scoped.css`: the document's own rules, narrowed to the elements it declares. */
  layoutScopedCss?: string
  routes: DiscoveredRoute[]
  /** Alternate documents. A route names one, or gets `layout.tsx`. */
  layouts: DiscoveredNamed[]
  /** Layouts scoped to a subtree of `routes/`, outermost first. */
  nested: DiscoveredNested[]
  slots: DiscoveredNamed[]
  fragments: DiscoveredNamed[]
  intents: string[]
  /**
   * The catalogue: modules exporting fragments a client may ask to have rendered.
   *
   * A separate directory from `intents/` because they are separate questions with the same shape —
   * one writes and one renders — and because what is in this directory is *
  …

The whole file tree as the framework reads it. Nothing downstream may add to this.

Raised in this fileE_BAD_SEGMENT·E_DUPLICATE_ROUTE·E_NESTED_LAYOUT_DATA·E_NO_APP_DIR·E_ORPHAN_CSS·E_SCOPED_NO_TEMPLATE·E_WILDCARD_NOT_LAST

packages/weft/src/convention.ts

DiscoveredNamed interface

export interface DiscoveredNamed {
  name: string
  file: string
  data?: string
  css?: string
  /** The sibling `.scoped.css`, narrowed to the elements this fragment declares. */
  scopedCss?: string
}

A named fragment, layout or slot, with the files that travel with it.

Raised in this fileE_BAD_SEGMENT·E_DUPLICATE_ROUTE·E_NESTED_LAYOUT_DATA·E_NO_APP_DIR·E_ORPHAN_CSS·E_SCOPED_NO_TEMPLATE·E_WILDCARD_NOT_LAST

packages/weft/src/convention.ts

DiscoveredNested interface

export interface DiscoveredNested {
  /** The route-pattern prefix this layout wraps: `/dashboard`, or `/` at the top of `routes/`. */
  scope: string
  file: string
  css?: string
  /** The sibling `layout.scoped.css`, narrowed to the elements this layout declares. */
  scopedCss?: string
  /** Segments in the scope, so a chain sorts outermost-first without re-parsing the pattern. */
  depth: number
}

A layout that wraps a subtree of the route table rather than the whole application.

app/routes/dashboard/layout.tsx wraps every route at or under /dashboard, nested inside the application's own document. Directory-scoped rather than declared, for the reason every other placement in this file is: the file tree is the single source of the route table, and a chain assembled from a declaration somewhere else would be a second source that could disagree with it.

layout is therefore a reserved page name under routes/: a file called layout.tsx is a wrapper, never a route. There is no layout.data.ts — a nested layout's holes are filled by the route's own declaration, exactly as the root layout's are, and a declaration attached to the wrapper would be one that every route under it silently shared.

Raised in this fileE_BAD_SEGMENT·E_DUPLICATE_ROUTE·E_NESTED_LAYOUT_DATA·E_NO_APP_DIR·E_ORPHAN_CSS·E_SCOPED_NO_TEMPLATE·E_WILDCARD_NOT_LAST

packages/weft/src/convention.ts

DiscoveredRoute interface

export interface DiscoveredRoute {
  /** `/blog/:slug`, derived from the file path and from nothing else. */
  pattern: string
  /** The `.tsx` that renders the body slot. Absent when the declaration says what does. */
  file?: string
  /** The sibling `.data.ts`, if the route has one. */
  data?: string
  /** The sibling `.css`, if the page brought its own. */
  css?: string
  /** The sibling `.scoped.css`, narrowed to the elements this page's template declares. */
  scopedCss?: string
  /** How specific this route is, for a stable order in a generated table. */
  depth: number
}

The folder convention, read once.

A convention is only worth having if it is the single source of the route table, so nothing downstream of this file may add a route: weft build generates plans from what this found, and a page that is not here does not exist. The rules are the ones Nuxt, Remix and SvelteKit converged on, because a user arriving here should not have to learn a third vocabulary for the same idea.

app/layout.tsx the document. Its <slot> holes are what a route fills. app/routes/<dir>/layout.tsx a nested layout, wrapping every route at or under <dir> app/routes/index.tsx / app/routes/about.tsx /about app/routes/blog/[slug].tsx /blog/:slug app/routes/docs/[...].tsx /docs/* app/routes/x.data.ts x.tsx's declaration: head, cache, load, guard, slots app/routes/x.css x.tsx's own stylesheet, linked only by the pages that use it app/routes/x.scoped.css the same, narrowed to the elements x.tsx declares. See scoped.ts app/client.ts the application's own client code, loaded after adoption app/layouts/error.tsx the 404 and the 500. Absent means the framework's own

A route is a .tsx, or a .data.ts that says what renders its body — a page whose content is markup rather than a template needs no template file, and requiring an empty one would be ceremony rather than convention. app/layouts/<name>.tsx an alternate document, chosen with defineRoute({ layout }) app/slots/<name>.tsx fills the layout hole of that name on every route app/fragments/<name>.tsx reusable, referenced by name from a route's slots app/intents/**.ts intents. The manifest is generated from this directory app/renderables/**.ts fragments a client may ask for by opaque id. Same derivation app/styles.css appended after the framework's stylesheet

Raised in this fileE_BAD_SEGMENT·E_DUPLICATE_ROUTE·E_NESTED_LAYOUT_DATA·E_NO_APP_DIR·E_ORPHAN_CSS·E_SCOPED_NO_TEMPLATE·E_WILDCARD_NOT_LAST

packages/weft/src/convention.ts

FragmentReport interface

export interface FragmentReport {
  /** The logical name: `layout`, `route:/blog/:slug`, `fragment:card`. */
  name: string
  file: string
  /** `module#export`, stable across content changes — what a plan names. */
  id: string
  /** The content address. A template edit is a different sealed thing. */
  version: string
  class: CacheClass
  reads: string[]
  vary: string[]
  ttlRequired: boolean
  forms: WireForm[]
  explanation: string
  holes: Hole[]
  templates: string[]
  bytes: number
}

One compiled fragment: its holes, its reads, its escape decisions, its version.

Raised in this fileE_NO_SUCH_ROUTE

packages/weft/src/devtools/report.ts

Generated interface

export interface Generated {
  routes: GeneratedRoute[]
  facts: Record<string, SlotFacts>
  /** Which layout hole each route fills with what, for `weft build`'s report. */
  layoutSlots: string[]
}

Every route, the compiler's facts, and which holes the documents left.

Raised in this fileE_CONSISTENCY_MISMATCH·E_DUPLICATE_LAYOUT_HOLE·E_ETAG_STREAMS·E_LAYOUT_HOLE_UNFILLED·E_NO_BODY_SLOT·E_NO_DEFAULT_ROUTE·E_NO_NESTING_SLOT·E_NO_PAGE·E_NO_SLOTS·E_NO_SUCH_FRAGMENT·E_NO_SUCH_LAYOUT·E_REGION_EXECUTOR

packages/weft/src/routes.ts

GeneratedRoute interface

export interface GeneratedRoute {
  pattern: string
  plan: Plan
  entry: RouteEntry<RouteResolver>
  module: RouteModule
  /** Slots this route can refresh over the channel, by slot name. */
  live: Record<string, LiveSlot>
  /**
   * Every region of this route, live or not, by slot name. `live` gates a *refresh*; staging a
   * route needs every region regardless, because the reader is about to see the whole page.
   */
  regions: Record<string, LiveSlot>
  /**
   * Regions of this route that render on another deployment, by slot name. Carried on the route
   * because a region is composed on three paths, and all three have to reach the same deployment
   * with the same budget and contract. Derived by the plan layer's `regionSpecOf`.
   */
  remote: Record<string, RegionSpec>
  /**
   * The shell values this route offers its regions, resolved for a set of params — read fr
  …

The generated plan: a route file and its declaration become a Plan and a RouteBindings. Nothing here invents a fact — cache classes, read sets and escape decisions come from the compiler, placement from the declaration, and the plan is validated against the former.

Raised in this fileE_CONSISTENCY_MISMATCH·E_DUPLICATE_LAYOUT_HOLE·E_ETAG_STREAMS·E_LAYOUT_HOLE_UNFILLED·E_NO_BODY_SLOT·E_NO_DEFAULT_ROUTE·E_NO_NESTING_SLOT·E_NO_PAGE·E_NO_SLOTS·E_NO_SUCH_FRAGMENT·E_NO_SUCH_LAYOUT·E_REGION_EXECUTOR

packages/weft/src/routes.ts

GenerateOptions interface

export interface GenerateOptions {
  discovered: Discovered
  compiled: CompiledApp
  config: ResolvedConfig
  /** The one stylesheet a page links, resolved when the page renders — the href does not exist yet at generation time. */
  styleHref(pattern: string): string
  /** A fragment file's colocated stylesheets, in cascade order: global `.css`, then `.scoped.css`. */
  styleOf(file: string): readonly string[]
  /** Where a live slot's base render is recorded, so its first refresh can be a delta. */
  store: StorePort
  /** Every cache tag some intent writes. See `StaticInput.written`. */
  written?: ReadonlySet<string>
  /** What this deployment bound. A loader is handed the services half of it. */
  ports: Ports
  /** What a recording decided about delivery. Placement stays the convention's; a profile decides
   * only whether a region is worth arriving separately. */
  p
  …

What generation needs: the file tree, the compiled templates, the ports, and the late bindings.

Raised in this fileE_CONSISTENCY_MISMATCH·E_DUPLICATE_LAYOUT_HOLE·E_ETAG_STREAMS·E_LAYOUT_HOLE_UNFILLED·E_NO_BODY_SLOT·E_NO_DEFAULT_ROUTE·E_NO_NESTING_SLOT·E_NO_PAGE·E_NO_SLOTS·E_NO_SUCH_FRAGMENT·E_NO_SUCH_LAYOUT·E_REGION_EXECUTOR

packages/weft/src/routes.ts

Handler interface

export interface Handler {
  app: App
  /** A request, answered. Never throws: a failure below it becomes the error document. */
  handle(req: IncomingMessage, res: ServerResponse): void
  /** A channel open. Ends the socket when the path is not one, which is what a 404 is here. */
  upgrade(req: IncomingMessage, socket: Duplex, head: Buffer): void
  /** Stop the periodic work. Nothing is listening, so there is no socket to close. */
  close(): Promise<void>
}

An application that answers requests, with nothing yet listening. weft start puts it on a TCP port; a host that owns the socket takes the two callbacks. See spec/kernel/lifecycle.md.

Raised in this fileE_ASSETS_NOT_BUILT·E_INTENT_UNSIGNED·E_METHOD·E_NO_ADDRESS·E_NO_PACKAGE·E_NO_ROUTE·E_NO_SUCH_RENDERABLE·E_NO_SUCH_SLOT·E_RENDER_FAILED·E_REQUEST_FAILED

packages/weft/src/serve.ts

IntentManifest interface

export interface IntentManifest {
  entries: ManifestEntry[]
  registry: Registry
  /** Name to id, which is what a page ships so markup written by hand can name one. */
  names: Record<string, string>
  /** `POST /_weft/i/<id>` and `POST /_weft/i/<name>`, for the no-JavaScript path. */
  routes: IntentRoute[]
}

Every intent, by the opaque id the compiler derived, with what each one declares.

Raised in this fileE_INTENT_ID_COLLISION·E_INTENT_NAME_TAKEN

packages/weft/src/intents.ts

IrManifest interface

export interface IrManifest {
  irVersion: string
  fragments: Record<string, { entry: string; file: string; templates: string[] }>
  /** Version to the file that holds it. */
  templates: Record<string, string>
}

Every sealed template the build wrote, so a channel can answer a WARM tpl=.

Raised in this fileE_MISSING_TEMPLATE·E_NO_BUILD·E_STALE_BUILD

packages/weft/src/build.ts

JsMeasurement interface

export interface JsMeasurement {
  /** Modules a page loads, in the order the walk found them. */
  modules: { href: string; raw: number; brotli: number }[]
  raw: number
  /** Compressed, module by module and then summed — which is what a page without a bundler pays. */
  brotli: number
}

budget({ js, grow }), enforced — and the granularity it turned out to have.

The declaration is per slot, which is where the design put it, and the design was describing a framework with a bundler: chunks per route, a slot's island in one of them, a number per slot. This framework has no bundler. A page loads one boot module and whatever that module imports, the same set on every route, so **there is no per-slot JavaScript to measure** — the honest number is what a page downloads, and it is one number for the whole application.

That does not make the budget useless, it makes it a different claim: a slot declaring js: '8kb' is saying the page it is on should not ship more than that, and the build can tell it whether it does. What it cannot do is attribute the excess to the slot, so the failure names the route, the slot that declared the ceiling, and the measurement, and leaves the attribution to a reader who knows what their application imports.

grow is the other half and needs no bundler at all: a cap on regression against a recorded baseline. A ceiling alone produces permanent silence just under it; a growth cap notices the afternoon somebody added 900 bytes.

Raised in this fileE_JS_BUDGET·E_JS_GROWTH

packages/weft/src/js-budget.ts

JsVerdict interface

export interface JsVerdict {
  route: string
  /** The slot that declared the ceiling, or `document` for a route-level declaration. */
  declaredBy: string
  limit: number
  measured: number
  kind: 'ceiling' | 'growth'
  /** The recorded figure a growth cap is measured against. */
  baseline?: number
}

One budget the client did not meet, and everything needed to say whose it was.

declaredBy is the slot that wrote the ceiling, or document for a route-level declaration, and it is separate from route because a slot can be on several. baseline is present only for a growth cap: a ceiling is absolute and a growth cap is a comparison, so one of them has a second number in it and the other does not.

Raised in this fileE_JS_BUDGET·E_JS_GROWTH

packages/weft/src/js-budget.ts

LiveRow interface

export interface LiveRow {
  slot: string
  /** The key the framework records the base render under. Not a store entry an intent can name. */
  key: string
  tags: string[]
  file: string
}

One live region: what it holds and what may be done to it over the channel.

Raised in this fileE_NO_SUCH_ROUTE

packages/weft/src/devtools/report.ts

LiveSlot interface

export interface LiveSlot {
  fragment: CompiledFragment
  load: (ctx: RenderContext, params: Record<string, string>) => Promise<Values>
  key: string
  tags: string[]
}

A region the framework can render again later: its fragment, its loader, and its cache tags.

Raised in this fileE_CONSISTENCY_MISMATCH·E_DUPLICATE_LAYOUT_HOLE·E_ETAG_STREAMS·E_LAYOUT_HOLE_UNFILLED·E_NO_BODY_SLOT·E_NO_DEFAULT_ROUTE·E_NO_NESTING_SLOT·E_NO_PAGE·E_NO_SLOTS·E_NO_SUCH_FRAGMENT·E_NO_SUCH_LAYOUT·E_REGION_EXECUTOR

packages/weft/src/routes.ts

ManifestEntry interface

export interface ManifestEntry {
  /** The module id, relative to the project root and slash-separated, as the compiler states it. */
  module: string
  export: string
  /** Six hex characters, derived from the two fields above and from nothing else. */
  id: string
  /** The intent's own declared name, for a diagnostic and for a plain HTML form's action. */
  name: string
  writes: string[]
  /** Capabilities the caller must hold. The closed set the config's grants are checked against. */
  capabilities: string[]
  /** Reachable only with a token this deployment minted. See `spec/kernel/authority.md`. */
  signed: boolean
  /** How much traffic this mutation says it can take. What it is counted against is the port's. */
  limit?: IntentLimit
}

The intent manifest, generated from a directory.

manifestRegistry in @weftjs/adapters has always been able to consume one of these; nothing produced one. This is that producer, and the derivation is deliberately the same function the compiler used to write the id into a template's wiring — a manifest that spelled its own ids could disagree with the templates, and that disagreement looks exactly like an intent that silently does nothing.

Raised in this fileE_INTENT_ID_COLLISION·E_INTENT_NAME_TAKEN

packages/weft/src/intents.ts

ModuleTree interface

export interface ModuleTree {
  dir: string
  /** `.ts` means the source still has its types and they are stripped on the way out. */
  ext: '.js' | '.ts'
}

The client modules a page pulls in, walked from its boot module.

Raised in this fileE_MODULE_UNREADABLE·E_NO_ASSET·E_NO_PAGE_CSS

packages/weft/src/assets.ts

Prerendered interface

export interface Prerendered {
  documents: (StaticDocument & { body: Uint8Array })[]
  refused: { pattern: string; code: StaticRefusal; reason: string }[]
}

The documents that became files, and every page that did not with its reason.

Raised in this fileE_MISSING_DOCUMENT

packages/weft/src/static.ts

ReloadEvent interface

export interface ReloadEvent {
  file: string
  ms: number
  /** `restart` means the process is about to exit so a supervisor can replace it. */
  kind: 'rebuild' | 'restart'
  error?: Error
}

What changed, how long the rebuild took, and whether the process has to be replaced.

packages/weft/src/dev.ts

ResolvedConfig interface

export interface ResolvedConfig extends Required<Pick<WeftConfig, 'srcDir' | 'outDir' | 'port' | 'host'>> {
  root: string
  css: string[]
  nav?: { href: string; label: string }[]
  flags: Record<string, string[]>
  session: { cookie: string }
  executors: Record<string, KernelExecutor>
  channelPath: string
  /** False on a deployment with no process to hold a connection. See `WeftConfig.channel`. */
  channelHold: boolean
  /** How many instances run at once. See `WeftConfig.instances`. */
  instances: number
  /** Where this application is served from. See `WeftConfig.site`. */
  origin?: string
  /** Cross-instance invalidation. See `WeftConfig.fanout`. */
  fanout?: FanoutPort
  /** Where an invalidation waits for a turn. See `WeftConfig.journal`. */
  journal?: StaleJournal
  /** Where a route change lands when the framework answers a link. See `WeftConfig.navigation`
  …

The config with every default filled in, so nothing downstream has to know what a default is.

Raised in this fileE_BLOCKED_PORT·E_CONFIG_NO_DEFAULT·E_NO_CAPABILITY_CHECK·E_NO_RATE_LIMIT·E_NO_SUCH_REGION·E_NO_VERIFIER·E_TAGS_PROCESS_SCOPED

packages/weft/src/config.ts

RevvedAssets interface

export interface RevvedAssets {
  /** Every file, by the URL it is published at. */
  files: Map<string, Asset>
  /** Absolute path on disk to that URL, which is what a `url()` rewrite resolves through. */
  byPath: Map<string, string>
  /** The path an author writes to its URL, for `asset()`. */
  byName: Map<string, string>
  /** Original path to revved href, for the build manifest. */
  manifest: Record<string, string>
}

app/assets/, revved: nothing in it is reachable at the path it was written at, and every file is published once under a digest of its own contents. The two directories are spec/kernel/static.md; rewriteUrls is the other half of this.

Raised in this fileE_MODULE_UNREADABLE·E_NO_ASSET·E_NO_PAGE_CSS

packages/weft/src/assets.ts

RouteReport interface

export interface RouteReport {
  pattern: string
  plan: Plan
  slots: SlotRow[]
  live: LiveRow[]
  /** The stylesheets this page links, project-relative. */
  css: string[]
  stylesheet: string
  /** Null when the href is not in the asset table, which would be a bug worth seeing. */
  stylesheetBytes: number | null
  markupBytes: number
}

One route, as generated: its slots, its document, and whether it became a file.

Raised in this fileE_NO_SUCH_ROUTE

packages/weft/src/devtools/report.ts

Scaffolded interface

export interface Scaffolded {
  directory: string
  files: string[]
  message: string
}

What was written, and the message npm create weft prints.

Raised in this fileE_BAD_NAME·E_NO_TEMPLATE·E_NOT_EMPTY

packages/weft/src/scaffold.ts

ScaffoldOptions interface

export interface ScaffoldOptions {
  directory: string
  name?: string
  template?: Template
}

Where to write a new application, what to call it, and which template to use.

Raised in this fileE_BAD_NAME·E_NO_TEMPLATE·E_NOT_EMPTY

packages/weft/src/scaffold.ts

ServedDocument interface

export interface ServedDocument {
  body: Buffer
  headers: Record<string, string>
  etag: string
}

What weft start serves: the file, the headers the build captured, and its ETag.

Raised in this fileE_MISSING_DOCUMENT

packages/weft/src/static.ts

Serving interface

export interface Serving {
  url: string
  app: App
  close(): Promise<void>
}

A running application: the URL it answers on, and how to stop it.

Raised in this fileE_ASSETS_NOT_BUILT·E_INTENT_UNSIGNED·E_METHOD·E_NO_ADDRESS·E_NO_PACKAGE·E_NO_ROUTE·E_NO_SUCH_RENDERABLE·E_NO_SUCH_SLOT·E_RENDER_FAILED·E_REQUEST_FAILED

packages/weft/src/serve.ts

SiteObject interface

export interface SiteObject {
  /** The URL it answers. */
  href: string
  /** Where it is in the build. */
  file: string
  /**
   * Where it goes under a site root, for a host that serves a directory rather than a key space.
   *
   * Not derived from `href`: a document answers `/guide` and lives at `guide/index.html`, and the
   * mapping between the two is the build's rather than a rule about trailing slashes. The static
   * manifest already recorded it, so this is read rather than guessed.
   */
  path: string
  /** What it must be served with. For a document, exactly what the build proved it may carry. */
  headers: Record<string, string>
  /** A document is not: it answers a URL a reader typed, and the next build may answer it differently. */
  immutable: boolean
  /**
   * A page this build resolved, as opposed to a file it copied.
   *
   * Stated rather than infe
  …

What a deployment is, to anything that is not a weft server.

The build writes documents under static/ and revved files under assets/, and neither directory is the site: one holds the pages and the other holds everything they link, and the two manifests beside them describe the set rather than belong to it. Working that out is not something every application should have to do again, and getting it wrong is quiet — a missing overlay is a site that serves without its stylesheets, and an uploaded manifest.json is a listing of every page published at a URL nobody meant to publish.

So it is written down once, here, and it has two destinations that must not disagree: weft upload sends it to an object store, weft site writes it to a directory. Both ask this.

packages/weft/src/site.ts

SiteReport interface

export interface SiteReport {
  out: string
  documents: number
  assets: number
  bytes: number
  /** Whether a sitemap was written, and how many URLs it names. Absent when no origin was given. */
  sitemap?: { urls: number }
}

What weft site wrote: where it went, and how much of it there is.

packages/weft/src/site.ts

SlotRow interface

export interface SlotRow {
  /** Placement, as the generated plan states it. */
  spec: SlotSpec
  /** Reads, forms and identity, as the compiler inferred them. Absent for a slot with no fragment. */
  facts?: SlotFacts
  /** The `.tsx` it was compiled from, project-relative. */
  file?: string
}

One slot as the devtools table shows it: what renders it, how it arrives, what keys it.

Raised in this fileE_NO_SUCH_ROUTE

packages/weft/src/devtools/report.ts

StaticDocument interface

export interface StaticDocument {
  pattern: string
  /** The path it answers, which for a route with no parameters is the pattern. */
  path: string
  /** Relative to the static directory, so the directory can be uploaded as it is. */
  file: string
  bytes: number
  etag: string
  /** What the build's own render produced, minus the parts a file decides for itself. */
  headers: Record<string, string>
}

One document, resolved. The manifest is what a deployment reads; the body is the file.

Raised in this fileE_MISSING_DOCUMENT

packages/weft/src/static.ts

StaticInput interface

export interface StaticInput {
  pattern: string
  module: RouteModule
  /** The innermost layout: the one whose `body` hole the page goes in. */
  shell: CompiledFragment
  /**
   * Every layer of the document, outermost first, `shell` included: a nested layout's reads are the
   * document's exactly as the outer layout's are. Defaults to `[shell]`.
   */
  layers?: readonly CompiledFragment[]
  slots: {
    name: string
    /** Absent for a region rendered on another deployment, which is refused before it is read. */
    fragment?: CompiledFragment
    declaration: SlotDeclaration
    streams: boolean
  }[]
  /**
   * Every cache tag some intent in this application declares it writes. A file is the one place the
   * tag/writes agreement cannot reach, so a page whose tags appear here is refused rather than
   * frozen. See `spec/kernel/static.md`.
   */
  written?: ReadonlySet<string>
}

What the structural half of the verdict is derived from: the declaration and every layer.

Raised in this fileE_MISSING_DOCUMENT

packages/weft/src/static.ts

StaticManifest interface

export interface StaticManifest {
  documents: StaticDocument[]
  refused: { pattern: string; code: StaticRefusal; reason: string }[]
}

Every document written, with its ETag and the headers the build's own render produced.

Raised in this fileE_MISSING_DOCUMENT

packages/weft/src/static.ts

TreeRow interface

export interface TreeRow {
  prefix: string
  dir: string
  ext: string
  files: number
}

A module tree is served from source and transformed on the way out — types stripped, bare specifiers rewritten — so what the browser receives is not the file on disk. There is no measured byte count for it here and none is invented: the count of files is what is known.

Raised in this fileE_NO_SUCH_ROUTE

packages/weft/src/devtools/report.ts

WeftConfig interface

export interface WeftConfig {
  /** Defaults to `app`. */
  srcDir?: string
  /** Where `weft build` writes. Defaults to `.weft`. */
  outDir?: string
  /**
   * Defaults to 3000. A port on the WHATWG bad-port list is `E_BLOCKED_PORT` rather than a
   * deployment whose documents serve perfectly and whose channel silently never connects.
   */
  port?: number
  /** What the server binds to. Defaults to `localhost`, which is not reachable from another host. */
  host?: string
  /** Extra stylesheets, in order, after the framework's own. Paths are relative to the project. */
  css?: string[]
  /**
   * What the layout's nav links to. Without one it is derived from every route with no parameter,
   * which is right for a small application and editorial the moment there are forty pages.
   */
  nav?: { href: string; label: string }[]
  /**
   * How long a shared cache may serve
  …

The one file a deployment writes, and the only place it states what it binds.

This is KernelOptions with a front door. Everything is optional: an application with no config file gets an in-process store, a cookie session, no flag axes and inline as the only executor — which is a real deployment for one process and an honest starting point for any other, because the moment a port is bound here nothing else in the application changes.

Raised in this fileE_BLOCKED_PORT·E_CONFIG_NO_DEFAULT·E_NO_CAPABILITY_CHECK·E_NO_RATE_LIMIT·E_NO_SUCH_REGION·E_NO_VERIFIER·E_TAGS_PROCESS_SCOPED

packages/weft/src/config.ts

WhyPage interface

export interface WhyPage {
  pattern: string
  plan: Plan
  report: WhyReport
  /** Empty when the route needs params this request did not supply. */
  resolved: Record<string, ResolvedKey>
  /** A slot whose key could not be resolved, with the error that says why. */
  refused: { slot: string; message: string }[]
  /** Params the pattern has, and the ones this request left unanswered. */
  wants: string[]
  missing: string[]
  params: Record<string, string>
  /** The concrete path the keys were resolved against. */
  at: string
}

One route's whole story, for the page that answers "why is this page like this".

Raised in this fileE_NO_SUCH_ROUTE

packages/weft/src/devtools/report.ts

CountedAgainst type

export type CountedAgainst = CountingLimitOptions['counted']

The one decision the limits port exists to refuse to make. See WeftConfig.limits.

Raised in this fileE_BLOCKED_PORT·E_CONFIG_NO_DEFAULT·E_NO_CAPABILITY_CHECK·E_NO_RATE_LIMIT·E_NO_SUCH_REGION·E_NO_VERIFIER·E_TAGS_PROCESS_SCOPED

packages/weft/src/config.ts

DevtoolsHandler type

export type DevtoolsHandler = (req: IncomingMessage, res: ServerResponse) => Promise<boolean>

Handled or not, in the shape serveApp already uses for the channel.

Raised in this fileE_DEVTOOLS_NOT_DEV·E_NO_SUCH_PAGE

packages/weft/src/devtools.ts

Mode type

export type Mode = 'dev' | 'build' | 'start'

dev serves from source at stable URLs that must never cache. build compiles and revs. start serves the build's sealed templates and its revved URLs, and runs no compiler.

Raised in this fileE_ASSETS_NOT_BUILT·E_INTENT_UNSIGNED·E_METHOD·E_NO_ADDRESS·E_NO_PACKAGE·E_NO_ROUTE·E_NO_SUCH_RENDERABLE·E_NO_SUCH_SLOT·E_RENDER_FAILED·E_REQUEST_FAILED

packages/weft/src/serve.ts

StaticRefusal type

export type StaticRefusal =
  | 'L0_PARAMS'
  | 'L0_TOO_MANY'
  | 'L0_READS'
  | 'L0_ISOLATED'
  | 'L0_LIVE'
  | 'L0_REFRESH'
  | 'L0_WRITTEN'
  | 'L0_GUARD'
  | 'L0_BUDGET_FOR'
  | 'L0_OUT_OF_ORDER'
  | 'L0_VARIES'
  | 'L0_DECLARED'
  | 'L0_DEGRADED'
  | 'L0_STATUS'
  | 'L0_SET_COOKIE'
  | 'L0_REGION'
  | 'L0_FAILED'

L0: the tier where the kernel is not involved at all. Eligibility is decided twice — structurally, from what the compiler and the plan already know, and empirically, by rendering the route twice under requests that differ in everything a document may be indifferent to. See spec/kernel/static.md.

Raised in this fileE_MISSING_DOCUMENT

packages/weft/src/static.ts

StaticVerdict type

export type StaticVerdict =
  | {
      static: true
      /** One entry per enumerated combination, for a parameterised route. */ params?: Record<
        string,
        string
      >[]
    }
  | { static: false; code: StaticRefusal; reason: string }

Whether this page can be a file, and if not, the code and the read that refused it.

Raised in this fileE_MISSING_DOCUMENT

packages/weft/src/static.ts

Template type

export type Template = 'app' | 'minimal'

weft create, and what npm create weft runs.

The scaffold's job is not to save typing. It is to make the convention legible: every file it writes is one the framework will actually read, each one says what it is for, and the page it produces is a real page — it renders through the kernel, its CSS is linked the way a component's CSS is linked, and its buttons dispatch a real intent. A scaffold whose output is a placeholder teaches nothing about the framework it is scaffolding.

Raised in this fileE_BAD_NAME·E_NO_TEMPLATE·E_NOT_EMPTY

packages/weft/src/scaffold.ts

DEVTOOLS_PATH const

export const DEVTOOLS_PATH = '/_weft/devtools'

weft routes and weft why as pages, plus the byte report, pointed at your application.

This is one framework-owned URL prefix reading the App object this process is already holding. There is no second compile, no second fragment table, no prefixed patterns and no merged intent manifest — all of which is what mounting a demonstration application inside a real one would have cost, for the payoff of a URL prefix on somebody else's fixtures.

Three properties are deliberate.

It is **dev only, and says so rather than pretending**. devtools: true under weft start is refused by name: a deployment serving its own route table, every effect set and the reason behind every cache key is not a smaller version of a development convenience, it is a different thing. Under weft build nothing here is registered at all, because a build never calls serveApp.

It **costs the framework's measured paths nothing**. Nothing in this file is reachable from the kernel; serveApp holds one nullable handler, and when devtools is off that is a single null check on a path that was already doing a string compare per request. No template is compiled, no asset is added to the table, and no byte of this reaches a page.

It **refuses rather than approximates**. A route it does not have, a page it does not serve, and a key it cannot resolve because the pattern's params were not supplied are each an E_-coded refusal that names the fix, not a blank cell that looks like an answer.

Raised in this fileE_DEVTOOLS_NOT_DEV·E_NO_SUCH_PAGE

packages/weft/src/devtools.ts

IMMUTABLE_ROOTS const

export const IMMUTABLE_ROOTS = [ASSET_ROOT, STYLE_ROOT, MODULE_ROOT] as const

The three roots, exported for the one question that has to be asked about a URL nothing matched: a *miss* under one of them must be stored by nobody. See spec/kernel/static.md.

Raised in this fileE_MODULE_UNREADABLE·E_NO_ASSET·E_NO_PAGE_CSS

packages/weft/src/assets.ts

MISS const

export const MISS = 'no-store'

What a miss under one of those roots answers with. Never stored, so a 404 cannot outlive a rollback.

Raised in this fileE_MODULE_UNREADABLE·E_NO_ASSET·E_NO_PAGE_CSS

packages/weft/src/assets.ts

RESTART_CODE const

export const RESTART_CODE = 75

Exit code the supervisor reads as "start me again". Anything else is a real exit.

packages/weft/src/dev.ts

REWRITTEN_SPECIFIERS const

export const REWRITTEN_SPECIFIERS: Record<string, string> = {
  '@weftjs/client': 'runtime',
  '@weftjs/warp': 'warp',
}

The bare specifiers the front door rewrites, and the module tree each one resolves into. Exported, and the only statement of this anywhere — measureClientJs walks the same pair, and the two have drifted before. See spec/kernel/static.md.

Raised in this fileE_MODULE_UNREADABLE·E_NO_ASSET·E_NO_PAGE_CSS

packages/weft/src/assets.ts

STAGED_DIR const

export const STAGED_DIR = 'staged'

The framework's own .tsx files are copied into the project's out directory before they are compiled: a template id is stated relative to the compile root, so compiling them where they are installed would make a version depend on how deep node_modules happens to be.

Raised in this fileE_NO_FRAGMENT·E_NO_LIST_HOLE·E_NOT_COMPILED

packages/weft/src/compile.ts

STATIC_DIR const

export const STATIC_DIR = 'static'

Where the build writes documents, and where weft start looks for them.

Raised in this fileE_MISSING_DOCUMENT

packages/weft/src/static.ts