weft
ir 2.6.0 · warp 1.8.0
generatedread out of the source that implements it

weft.config.ts

Every option a deployment may state, with the type it accepts and the default it gets by leaving it out.

A weft application needs no configuration file. Without one it gets an in-process store, a cookie session, no flag axes and inline as its 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.

The file default-exports defineConfig({…}), an identity function that exists for the types so the object is checked as it is written. weft.config.ts, weft.config.js and weft.config.mjs are all looked for, in that order, and the first one found wins. A file that exports something else is E_CONFIG_NO_DEFAULT.

Every default below is read out of the loader that applies it rather than typed beside it, so a number that changes in the framework changes on this page in the same commit.

weft.config.ts — a deployment that binds something
import { bySession, defineConfig, redisLeases } from '@weftjs/core'
import { memoryStore, workerPool } from '@weftjs/adapters'

export default defineConfig({
  port: 3000,

  // Where the store lives. Wrapped, so a nonce is spent across every instance.
  store: redisLeases(memoryStore(), { url: process.env.REDIS_URL }),

  // Executors beyond `inline` and `client`. A slot naming one not bound here fails the build.
  executors: { 'pool:heavy': workerPool({ size: 4 }) },

  // Flag axes. Only a declared axis can be read, so a typo is a build error.
  flags: { 'new-cart': ['off', 'on'] },

  // What a call is counted against. The framework does the counting.
  limits: { counted: bySession },

  // How long a shared cache may serve a prerendered document, and its grace period after.
  documents: { shared: 3600, stale: 86400 },

  // More than one process runs this, so an invalidation has to reach the others.
  instances: 4,

  // Absolute URLs the build cannot derive: the sitemap's entries and every canonical link.
  site: { origin: 'https://example.com' },
})

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.

OptionTypeDefault
srcDirstring'app'
outDirstring'.weft'
portnumber3000
hoststring'localhost'
cssstring[][]
nav{ href: string; label: string }[]—
documents{ shared?: number; stale?: number }—
storeStorePort—
flagsRecord<string, string[]>{}
session{ cookie?: string }—
executorsRecord<string, KernelExecutor>{}
telemetryTelemetryPort—
regionsreadonly RegionBinding[][]
registryRegistry—
configConfigPort—
deploymentDeploymentPort—
dbDbPort—
limitsLimitPort | { counted: CountedAgainst }—
channel{ path?: string; hold?: boolean }—
instancesnumber1
site{ origin?: string }—
fanoutFanoutPort—
journalStaleJournal—
authorityAuthorityConfig—
navigation{ scroll?: 'top' | 'preserve' }—
maxConcurrencynumber6
typesbooleantrue
profilebooleanfalse
devtoolsbooleanfalse

Read from packages/weft/src/config.ts · WeftConfig

srcDiroptional

Type
string
Default
'app'

Defaults to app.

srcDir: 'src'

outDiroptional

Type
string
Default
'.weft'

Where weft build writes. Defaults to .weft.

outDir: 'dist'

portoptional

Type
number
Default
3000

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.

hostoptional

Type
string
Default
'localhost'

What the server binds to. Defaults to localhost, which is not reachable from another host.

cssoptional

Type
string[]
Default
[]

Extra stylesheets, in order, after the framework's own. Paths are relative to the project.

css: ['./styles/theme.css', './styles/print.css']

documentsoptional

Type
{ shared?: number; stale?: number }
Default
—

How long a shared cache may serve a prerendered document before asking again, in seconds, and stale the grace period after that. Defaults to 0, and to an hour of any non-zero shared.

Stated rather than assumed, because only the deployment knows whether a deploy purges the caches in front of it. See spec/kernel/static.md.

// A deploy purges the CDN in front of this app, so a prerendered page may be
// answered from the edge for an hour, then served stale for a day while it refreshes.
documents: { shared: 3600, stale: 86400 }
FieldTypeDefault
shared?number0
stale?numberderived

storeoptional

Type
StorePort
Default
—

Where the store lives. Defaults to an in-process one, which is a single-process deployment.

import { memoryStore, tieredStore, kvStore } from '@weftjs/adapters'

// Two tiers: this process first, then the namespace every instance shares.
store: tieredStore([memoryStore({ max: 500 }), kvStore(env.CACHE)])

flagsoptional

Type
Record<string, string[]>
Default
{}

Flag axes. Only a declared axis can be read, so a typo is a build error rather than a branch.

// Only a declared axis can be read, so `ctx.flag('checkout')` is a build error.
flags: { 'new-cart': ['off', 'on'], theme: ['light', 'dark'] }

sessionoptional

Type
{ cookie?: string }
Default
—

What the session cookie is called. Defaults to sid. The name and nothing else — the rest is SessionPort's. Here because two applications behind one host cannot both be sid.

// Two applications behind one host cannot both be `sid`.
session: { cookie: 'shop_sid' }
FieldTypeDefault
cookie?string'sid'

executorsoptional

Type
Record<string, KernelExecutor>
Default
{}

Executors beyond inline and client. A slot naming one that is not bound here fails the build with the slot named, rather than refusing at request time.

import { workerPool, svcExecutor } from '@weftjs/adapters'

executors: {
  'pool:heavy': workerPool({ size: 4 }),
  'svc:search': svcExecutor({ url: 'https://search.internal' }),
}

telemetryoptional

Type
TelemetryPort
Default
—

Where spans and counters go. Unbound, they are computed and dropped — the kernel measures a render whether or not anybody is listening, because a number that exists only when telemetry is bound is a number that changes the thing it measures.

import { collectingTelemetry } from '@weftjs/adapters'

telemetry: collectingTelemetry()

regionsoptional

Type
readonly RegionBinding[]
Default
[]

Where each region a route composes actually is: a route says search, and this says what search is right now. A roll is a write here rather than a rebuild of every page that composes it. Unbound for a region a route declares, E_NO_SUCH_REGION at startup.

See spec/kernel/composition.md.

// A route says `region: { remote: true }` and calls the slot `search`.
// This says what `search` is right now.
regions: [
  { name: 'search', url: 'https://search.internal', rev: '2026-08-01' },
  { name: 'promo', url: 'https://promo.internal', rev: '2026-08-14' },
]

registryoptional

Type
Registry
Default
—

A registry that answers regions from somewhere live — a KV namespace, a control plane. Asked first when bound; regions above answers a name it does not resolve.

import { manifestRegistry } from '@weftjs/adapters'

// Asked first; `regions` above answers a name it does not resolve.
registry: manifestRegistry({ url: process.env.REGION_MANIFEST_URL })

configoptional

Type
ConfigPort
Default
—

Where settings come from. Defaults to WEFT_-prefixed environment variables. One of three ports whose defaults are real rather than stubs — see spec/kernel/ports.md.

import { envConfig, staticConfig } from '@weftjs/adapters'

// The default. `staticConfig({ … })` is the one to bind in a test.
config: envConfig({ prefix: 'WEFT_' })

deploymentoptional

Type
DeploymentPort
Default
—

What this build calls itself, and where it is running. Read by the trace, by weft verify and by every region answering a probe, so the default reads the host's own idea of a revision.

import { hostDeployment } from '@weftjs/adapters'

deployment: hostDeployment()

dboptional

Type
DbPort
Default
—

Where a loader's data comes from, named rather than anonymous. The default bounds access by a deadline and counts it, so a loader that hangs degrades a slot rather than never ending.

import { boundedDb } from '@weftjs/adapters'

// A loader that hangs is a slot that degrades, not a request that never ends.
db: boundedDb({ deadlineMs: 800 })

limitsoptional

Type
LimitPort | { counted: CountedAgainst }
Default
—

What a call is counted against, and — only if you want to own it — how the counting is done.

{ counted } and the framework counts in a fixed window against the bound store; counted is the part it will not guess at. A whole LimitPort replaces the counting. Unbound, an intent declaring a limit is E_NO_RATE_LIMIT at startup. See spec/kernel/authority.md.

import { bySession, byAddress } from '@weftjs/core'

// The framework counts, in a fixed window, against the store this deployment bound.
limits: { counted: bySession }

// Or own the counting outright, with a gateway or a Redis script:
// limits: myGatewayLimiter

channeloptional

Type
{ path?: string; hold?: boolean }
Default
—

The channel's mount point, and whether this deployment can hold a downstream open.

hold: false describes a serverless function, and said here the client takes turns from the first request rather than discovering it on a failed intent. See spec/kernel/transport.md.

// A serverless function terminates no upgrade and outlives no request.
channel: { path: '/_weft/channel', hold: false }
FieldTypeDefault
path?string'/_weft/channel'
hold?booleantrue

instancesoptional

Type
number
Default
1

How many instances of this deployment run at once. One unless it says otherwise.

Declared because an instance cannot see its siblings, and declaring it is what lets the build check the guarantees that depend on it — a process-scoped store holds N private caches on N instances. See spec/kernel/transport.md.

// Four processes, so `fanout` below is what makes an invalidation reach the other three.
instances: 4

siteoptional

Type
{ origin?: string }
Default
—

Where this application is served from, for the things that are absolute by specification — a sitemap's entries and a canonical link. Unset, neither is written: an absence rather than a guess, since the same output is served from a preview URL, a staging host and a domain.

// What `weft site` writes into the sitemap, and every page's <link rel="canonical">.
site: { origin: 'https://example.com' }
FieldTypeDefault
origin?string—

fanoutoptional

Type
FanoutPort
Default
—

How an invalidation reaches the instances this one is not. Needed exactly when instances is more than one, and inert when it is one.

import { memoryFanout } from '@weftjs/adapters'

// Needed exactly when `instances` is more than one, and inert when it is one.
fanout: memoryFanout({ url: process.env.REDIS_URL })

journaloptional

Type
StaleJournal
Default
—

Where an invalidation waits for a client that is not connected. Bind storeJournal(store) when this deployment serves turns and something writes; a process-scoped store is refused with E_TAGS_PROCESS_SCOPED. Unbound is no journal rather than a degraded one.

See spec/kernel/transport.md.

import { memoryStore } from '@weftjs/adapters'
import { storeJournal } from '@weftjs/kernel'

// Worth binding when this deployment serves turns and something writes.
journal: storeJournal(memoryStore())

authorityoptional

Type
AuthorityConfig
Default
—

Who may run an intent, and which intents need a token this deployment minted.

Unbound, an intent that declares a capability is E_NO_CAPABILITY_CHECK and one that declares signed is E_NO_VERIFIER — a declaration nothing enforces is worse than no declaration at all. See [spec/kernel/authority.md](../../../spec/kernel/authority.md).

authority: {
  grants: { editor: ['post:*'], admin: ['post:*', 'user:*'] },
  roles: (subject) => db.roles.of(subject),
}

maxConcurrencyoptional

Type
number
Default
6

Per-request ceiling on concurrent slot renders. Forty queries from one page will melt a database.

// Forty queries from one page will melt a database.
maxConcurrency: 4

typesoptional

Type
boolean
Default
true

Type information decides escape elision. Turning it off is correct and slower.

// Correct, and slower: every hole gets a runtime escape.
types: false

profileoptional

Type
boolean
Default
false

Record what every render costs into .weft/profile.json, and generate the next plan from it. Off by default: a recording is only worth having from traffic that resembles production. See spec/plan/profile.md.

// Writes .weft/profile.json as it serves. The next build reads it.
profile: process.env.WEFT_ENV === 'staging'

devtoolsoptional

Type
boolean
Default
false

weft routes and weft why as pages under /_weft/devtools, reading this process's own App object. weft dev only — left on, weft start refuses by name. See spec/plan/plan.md.

// `weft dev` only. `weft start` refuses by name rather than serving your route table.
devtools: true

What the authority option above takes. Bound, an intent may declare a capability or a signature; unbound, an intent that declares either is refused by name at startup rather than waved through.

FieldTypeRequired
grantsRecord<string, readonly Grant[]>optional
roles(subject: string) => Promise<readonly string[]> | readonly string[]optional
ambientreadonly Grant[]optional
anonymousstringoptional
signing{ kid: string; privateKey?: string | CryptoKey; publicKeys?: Record<string, string | CryptoKey>; ttlMs?: number }optional
audit(decision: { allowed: boolean; subject: string | null; required: readonly string[]; missing: readonly string[] }) => voidoptional

Read from packages/weft/src/authority.ts · AuthorityConfig

grantsoptional

Type
Record<string, readonly Grant[]>
Default
—

What each role holds. cart:* covers every capability under cart:; a bare * is refused.

grants: {
  // `cart:*` covers every capability under `cart:`. A bare `*` is refused.
  user: ['cart:read', 'cart:write'],
  admin: ['cart:*', 'order:*'],
}

rolesoptional

Type
(subject: string) => Promise<readonly string[]> | readonly string[]
Default
—

Which roles a subject has. Without one, a caller with a session is user, without is anonymous.

roles: async (subject) => (await db.user.find(subject))?.roles ?? []

ambientoptional

Type
readonly Grant[]
Default
—

Capabilities every caller holds, session or not. Where a deliberately public one goes.

// Where a deliberately public capability goes.
ambient: ['catalogue:read']

anonymousoptional

Type
string
Default
—

The role of a caller with no session. Defaults to anonymous.

anonymous: 'guest'

signingoptional

Type
{ kid: string; privateKey?: string | CryptoKey; publicKeys?: Record<string, string | CryptoKey>; ttlMs?: number }
Default
—

Ed25519 keys, for the intents that declare signed. Base64 of PKCS#8 / SPKI, or already-imported CryptoKeys. publicKeys is a bundle by key id, so rotation is a key added.

import { generateSigningKeys } from '@weftjs/core'

// `generateSigningKeys()` prints a pair for a deployment that has none yet.
signing: {
  kid: '2026-08',
  privateKey: process.env.INTENT_SIGNING_KEY,
  publicKeys: { '2026-08': process.env.INTENT_PUBLIC_KEY, '2026-02': OLD_PUBLIC_KEY },
  ttlMs: 60_000,
}
FieldTypeDefault
kidstringrequired
privateKey?string | CryptoKeyoptional
publicKeys?Record<string, string | CryptoKey>optional
ttlMs?numberoptional

auditoptional

Type
(decision: { allowed: boolean; subject: string | null; required: readonly string[]; missing: readonly string[] }) => void
Default
—

Every decision, allowed and denied. A log of denials only is one an escalation is silent in.

// A log of denials only is one an escalation is silent in.
audit: ({ allowed, subject, missing }) => log.info('authz', { allowed, subject, missing })