wervt
Dashboard
API

Platform contract

What wervt expects from an app's bundle and what it gives the app, independent of the framework.

@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:

FromIn the bundleWhat
.output/serverserver/The server, entry server/index.mjs. Required.
.output/publicpublic/Static files, served by the runtime without starting the server.
drizzle/drizzle/Migrations. Only apps with this folder get a database.
.output/wervt-bundle.jsonwervt-bundle.jsonThe 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:

server/index.mjs
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, not crypto). A bare crypto stops the isolate from booting.
  • Buffer, setImmediate and clearImmediate are no globals. Inject them from node:buffer and node:timers when 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 into public/.

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 in public/ ($fetch('/fonts/inter.ttf'), event.fetch, what nuxt-og-image does 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-image fetches images and fonts by URL with plain fetch (its Node fetch fails in the isolate); a URL on the app's own domain that is a file in public/ comes from the runtime too.
  • Any other server: publicFileResponse(request, files) from @wervt/core does the same for a Request, given the paths in public/. Without it, fetch ${WERVT_RUNTIME_URL}/_wervt/public-file?path=/fonts/inter.ttf with appHeaders() 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:

wervt-bundle.json
{
  "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 }
  }
}
FieldWhat
frameworkWhat built it, shown in the dashboard.
databaseWhether the app gets a database. Default: whether the bundle has drizzle/; true without it gives an empty schema.
publicThe 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.
tasksThe tasks the platform may run and their schedules. Only tasks listed here run.
shapesShape routes without parameters, requested once after the deploy as a check.
previewA private app's link preview: title, description, image, icon, themeColor.
brandThe login's look for this app: name, logo, icon, color, securedByWervt: false, signIn (e.g. ["twitch", "email"]), lang ("de" or "en").
servicesThe 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.
crossAppPath 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:

  1. A prerendered page (/about answered with about/index.html) is always no-cache.
  2. noCache: exact paths.
  3. immutable: path prefixes, public, max-age=31536000, immutable.
  4. rules, in order: an exact path (/favicon.svg), * for one segment (/icons/*) or a final /** for everything below (/images/**). cacheControl takes plain directives such as public, 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:

FileWhat
wervt-tasks.json{ tasks: [{ name, description? }], schedules: [{ cron, tasks }], timezone? }. Only tasks listed here can run.
wervt-shapes.jsonShape routes the deploy checks after the release started.
wervt-preview.jsonTitle, description and image of a private app's link preview.
wervt-brand.jsonThe login's branding for the app.

Nitro

A Nitro 3 app without Nuxt gets everything above from @wervt/nitro:

nitro.config.ts
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:

package.json
{
  "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:

package.json
{
  "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's dist/. /about answers with about/index.html or about.html, unknown pages with index.html for SPAs (--fallback= turns that off and answers 404.html). Set "immutable": ["/assets/"] for Vite's hashed assets.
  • A fetch handler: without --static, server.ts (or src/server.ts, src/index.ts, "entry") with export default { fetch } is bundled into one module with the Deno rules above applied, and public/ copied next to it. createTaskHandler(tasks) from @wervt/core serves 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

VariableWhat
WERVT_APPThe app's name.
WERVT_APP_URLWhere the app is, its custom domain if it has one.
WERVT_AUTH_URLThe login.
WERVT_RUNTIME_URL, WERVT_TOKENHow to reach the runtime's services as this app (below).
DATABASE_URLThe 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_KEYSigns the app's image URLs (below). Only with the image service.
WERVT_SERVICESThe names of the active release's service containers, comma-separated.
WERVT_APP_SECRET, NUXT_APP_SECRETA 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:

HeaderWhat
x-wervt-userThe 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-proofProves 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: 1The 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

RouteWhat
GET /_wervt/tasksOnly 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/bootOnly 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>:

ServiceWhatIn @wervt/core
GET /_wervt/electric/v1/shapeElectric shapes, pinned to the app's schemaproxyShape()
POST /_wervt/mail{ to, subject, html, text, replyTo? }sendMail()
/_wervt/accessInvites of an invite-only app, with the user's headersappAccess()
POST /_wervt/identity-token{ audience } → { token }, the app's workload identityworkloadIdentity()
GET /_wervt/image/…An image URL as imageUrl() signs it, for the server itselffetchImage()
* /_wervt/services/<name>/…A service container of the active release, started if needed; errors of the platform carry x-wervt-proxy-erroruseService()

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:

RouteWhat
/_wervt/login, /_wervt/logoutSign in or out, then back to ?redirect=.
/_wervt/accountThe account page in the app's look, then back to ?redirect=.
POST /_wervt/viewPage 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/sessionHands 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.

Copyright © 2026