Platform contract
@wervt/nuxt takes care of all of this, @wervt/nitro for a Nitro app without Nuxt,
and wervt build for a static site. Read on if you build the bundle another way or want to know what happens
underneath. The server side of it is in
@wervt/core, the browser side in
@wervt/client.
The bundle
wervt deploy runs the app's build script (with WERVT_APP set to the app's name), then packs:
| From | In the bundle | What |
|---|---|---|
.output/server | server/ | The server, entry server/index.mjs. Required. |
.output/public | public/ | Static files, served by the runtime without starting the server. |
drizzle/ | drizzle/ | Migrations. Only apps with this folder get a database. |
.output/wervt-bundle.json | wervt-bundle.json | The bundle manifest, below. Optional. |
wervt deploy --out dist packs another folder than .output.
The entry
server/index.mjs is an ES module that either exports a fetch handler or starts one itself:
export default { fetch: (request) => app.fetch(request) }
// or: Deno.serve((request) => app.fetch(request))
If it does both, Deno.serve wins. The server runs in an isolate of
Supabase Edge Runtime (Deno), so bundle everything
into the module, and keep in mind:
- Node built-ins only with the
node:prefix (node:crypto, notcrypto). A barecryptostops the isolate from booting. Buffer,setImmediateandclearImmediateare no globals. Inject them fromnode:bufferandnode:timerswhen a dependency uses them (postgres.js does).- The isolate has no file system: reading files next to the module fails, even inside
server/. Import what you need, or put it intopublic/.
Requests for files that exist in public/ never reach the server. Everything else does, /
included.
At runtime the server can't read public/ from disk, but it can fetch its own files:
@wervt/nuxt: a server-side fetch of a path inpublic/($fetch('/fonts/inter.ttf'),event.fetch, whatnuxt-og-imagedoes for fonts and images) gets the file from the runtime, like a browser would. The list of files is taken at build time, so a file written at runtime isn't one. A route under the same path answers when the file can't be had.nuxt-og-imagefetches images and fonts by URL with plainfetch(its Node fetch fails in the isolate); a URL on the app's own domain that is a file inpublic/comes from the runtime too.- Any other server:
publicFileResponse(request, files)from@wervt/coredoes the same for aRequest, given the paths inpublic/. Without it, fetch${WERVT_RUNTIME_URL}/_wervt/public-file?path=/fonts/inter.ttfwithappHeaders()from@wervt/core.
Files come from the active release, and an app only gets its own. Fetching the app's public URL works too, but goes out through the internet, and a private app's login stops it.
The bundle manifest
wervt-bundle.json tells the platform what the code can't:
{
"version": 2,
"framework": "nitro",
"database": true,
"public": {
"immutable": ["/assets/"],
"noCache": ["/version.json"],
"rules": [{ "path": "/images/**", "cacheControl": "public, max-age=86400" }]
},
"tasks": {
"tasks": [{ "name": "cleanup", "description": "Delete old rows" }],
"schedules": [{ "cron": "0 3 * * *", "tasks": ["cleanup"] }],
"timezone": "Europe/Berlin"
},
"shapes": ["/api/shapes/todos"],
"preview": { "title": "Todos", "image": "/og.png" },
"brand": { "name": "Todos", "logo": "/logo.svg", "color": "#2f5bff" },
"crossApp": ["/api/intake/"],
"services": {
"faces": { "build": { "context": "face-service" }, "port": 8000, "health": "/healthz", "memory": 2147483648, "cpus": 2, "idle": 600 }
}
}
| Field | What |
|---|---|
framework | What built it, shown in the dashboard. |
database | Whether the app gets a database. Default: whether the bundle has drizzle/; true without it gives an empty schema. |
public | The cache-control of files in public/: path prefixes cached for a year (immutable, hashed build assets), paths checked every time (noCache), and rules for anything else. Without any of them, Nuxt's /_nuxt/ rules apply. |
tasks | The tasks the platform may run and their schedules. Only tasks listed here run. |
shapes | Shape routes without parameters, requested once after the deploy as a check. |
preview | A private app's link preview: title, description, image, icon, themeColor. |
brand | The login's look for this app: name, logo, icon, color, securedByWervt: false, signIn (e.g. ["twitch", "email"]), lang ("de" or "en"). |
services | The app's service containers, memory in bytes and idle in seconds. wervt deploy adds each build context's SHA-256 as build.hash once it uploaded it. |
crossApp | Path prefixes that take changing requests from pages of other apps on the base domain. Everywhere else the runtime answers them with 403, see Server routes. |
Files in public/ are served by the platform, so the server's own headers never reach them;
public is how they get a cache-control. The first of these that fits a file wins:
- A prerendered page (
/aboutanswered withabout/index.html) is alwaysno-cache. noCache: exact paths.immutable: path prefixes,public, max-age=31536000, immutable.rules, in order: an exact path (/favicon.svg),*for one segment (/icons/*) or a final/**for everything below (/images/**).cacheControltakes plain directives such aspublic, max-age=86400, stale-while-revalidate=604800. At most 50 rules.
A file nothing fits gets no cache-control, so the CDN and browsers pick how long to keep it.
@wervt/nuxt writes rules from the app's routeRules that set a cache-control header,
keeping /_nuxt/ immutable whatever they say, as Nitro does.
A deploy with an invalid manifest fails and names the field.
Bundles without a manifest (Nuxt builds before it) keep these files in server/, which the
manifest's fields replace:
| File | What |
|---|---|
wervt-tasks.json | { tasks: [{ name, description? }], schedules: [{ cron, tasks }], timezone? }. Only tasks listed here can run. |
wervt-shapes.json | Shape routes the deploy checks after the release started. |
wervt-preview.json | Title, description and image of a private app's link preview. |
wervt-brand.json | The login's branding for the app. |
Nitro
A Nitro 3 app without Nuxt gets everything above from @wervt/nitro:
import { defineConfig } from 'nitro'
import { wervt } from '@wervt/nitro'
export default defineConfig({
preset: 'deno-server',
modules: [wervt({ timezone: 'Europe/Berlin' })],
scheduledTasks: { '0 3 * * *': ['notes:cleanup'] },
})
Add rolldown to devDependencies too: Nitro doesn't install its builder during a CI build.
It builds for the runtime, serves the app's tasks/ to the control plane (which runs
scheduledTasks), writes the bundle manifest, and in nitro dev creates the app's role and
schema in the local stack, runs drizzle/ migrations and sets DATABASE_URL and ELECTRIC_URL.
Routes use @wervt/core with the request, e.g. getUser(event.req) or
proxyShape(event.req, { table: 'todos' }); useDb() comes from @wervt/core/db.
wervt dev
nuxt dev and nitro dev set up the app's local database themselves. Any other dev server runs
through wervt dev, which does the same around your command:
{
"scripts": { "dev": "wervt dev -- tsx watch src/index.ts" }
}
It creates the app's role and schema in the local stack, runs
drizzle/ migrations, again whenever they change, and passes DATABASE_URL, WERVT_DB_SCHEMA,
ELECTRIC_URL and ELECTRIC_SECRET to the command. Values from the app's .env win. Without
drizzle/, it sets up a database only with "wervt": { "database": true }, and restarts the
command when drizzle/ appears. Pass --storage for the app's local bucket too.
There are no seed tasks here: those run through Nitro's task route. Seed from your own script.
To start over, wervt dev --reset drops the local database. With a command, it then starts as
usual. It only works against a local host.
Migrations without Drizzle
drizzle/ is just a folder of SQL. Apps that don't use Drizzle write the same layout by hand, a
folder per migration, named by its timestamp, with a migration.sql:
drizzle/
20260105120000_init/migration.sql
20260212093000_add_notes/migration.sql
They run in order, once each, on deploy and in wervt dev. Don't edit one that has run.
wervt build
Builds the bundle for apps without a framework adapter. Set it as the app's build script, so
wervt deploy runs it:
{
"scripts": { "build": "vite build && wervt build --static dist" },
"wervt": { "immutable": ["/assets/"], "preview": { "title": "My site" } }
}
- A static site:
--static dist(or"static": "dist") deploys a built site, e.g. Vite'sdist/./aboutanswers withabout/index.htmlorabout.html, unknown pages withindex.htmlfor SPAs (--fallback=turns that off and answers404.html). Set"immutable": ["/assets/"]for Vite's hashed assets. - A fetch handler: without
--static,server.ts(orsrc/server.ts,src/index.ts,"entry") withexport default { fetch }is bundled into one module with the Deno rules above applied, andpublic/copied next to it.createTaskHandler(tasks)from@wervt/coreserves the task routes there.
The wervt field takes the manifest's fields (database, immutable, noCache, tasks,
schedules, timezone, shapes, preview, brand, services).
What the server gets
Environment
| Variable | What |
|---|---|
WERVT_APP | The app's name. |
WERVT_APP_URL | Where the app is, its custom domain if it has one. |
WERVT_AUTH_URL | The login. |
WERVT_RUNTIME_URL, WERVT_TOKEN | How to reach the runtime's services as this app (below). |
DATABASE_URL | The app's own Postgres role through PgBouncer in transaction mode. Only with a database. |
WERVT_S3_URL, WERVT_S3_BUCKET, WERVT_S3_* | The app's bucket and its key. |
WERVT_IMAGE_KEY | Signs the app's image URLs (below). Only with the image service. |
WERVT_SERVICES | The names of the active release's service containers, comma-separated. |
WERVT_APP_SECRET, NUXT_APP_SECRET | A stable secret per app (sessions, signed cookies), unless set with wervt env. |
Plus everything set with wervt env. The platform's own variables win over those.
Request headers
The runtime checks the login (and a private app's allow list) before a request reaches the server, and strips these headers from every request a client sends, so the server can trust them:
| Header | What |
|---|---|
x-wervt-user | The signed-in user, URI-encoded JSON: { id, email, name?, image?, accounts?, role, emailVerified? }. Missing when nobody is signed in. getUser(request) reads it. |
x-wervt-user-proof | Proves the user to the runtime's services, for invites on their behalf. |
x-wervt-agent-token | { id, by } when a script or headless browser came with an agent token. |
x-wervt-task: 1 | The request is a task run or a boot check from the platform. |
role is owner, member, admin, invited, allowed or public.
Routes the server answers
| Route | What |
|---|---|
GET /_wervt/tasks | Only with x-wervt-task: [{ name, description? }], for the dashboard. Optional. |
POST /_wervt/tasks/<name> | Only with x-wervt-task: runs a task with { payload }, answers { result }, or { error } with an error status. |
GET /_wervt/boot | Only with x-wervt-task, after a deploy. Optional: only a 5xx counts as a failed boot. |
GET /_wervt/user | { user } for pages that weren't rendered on the server. Optional. |
createTaskHandler(tasks) from @wervt/core answers both task routes. Task names may contain :;
the platform runs wervt:account-merged with { from, into } after merging two accounts of one
person, if the app lists it.
Services the server calls
The runtime's services answer only on WERVT_RUNTIME_URL, with x-wervt-app: <WERVT_APP> and
x-wervt-token: <WERVT_TOKEN>:
| Service | What | In @wervt/core |
|---|---|---|
GET /_wervt/electric/v1/shape | Electric shapes, pinned to the app's schema | proxyShape() |
POST /_wervt/mail | { to, subject, html, text, replyTo? } | sendMail() |
/_wervt/access | Invites of an invite-only app, with the user's headers | appAccess() |
POST /_wervt/identity-token | { audience } → { token }, the app's workload identity | workloadIdentity() |
GET /_wervt/image/… | An image URL as imageUrl() signs it, for the server itself | fetchImage() |
* /_wervt/services/<name>/… | A service container of the active release, started if needed; errors of the platform carry x-wervt-proxy-error | useService() |
Logs
Everything the server writes to stdout and stderr ends up in wervt logs. JSON lines with level
and msg are searchable by their fields; plain text works too.
What the runtime answers itself
Browsers can use these on every app, the server never sees them:
| Route | What |
|---|---|
/_wervt/login, /_wervt/logout | Sign in or out, then back to ?redirect=. |
/_wervt/account | The account page in the app's look, then back to ?redirect=. |
POST /_wervt/view | Page views and events ({ path, name?, label? }), see track() in @wervt/client. |
GET /_wervt/image/<signature>/<options>/<key>.<format> | A resized image of a file in the app's bucket, see below. imageUrl() in @wervt/core. |
/_wervt/session | Hands the login over to a custom domain. |
/_wervt/brand/* | The login's branding. |
Visitors who aren't signed in only see a private app's link preview on /; other paths redirect
them to the login.