Vura

Vura is an MIT full-stack meta-framework built on What Framework and CelsianJS — static pages, cached SSR, typed API routes, websocket hot routes, and background tasks in one project, self-hostable anywhere.

License: MIT, forever

Vura is MIT-licensed and will stay MIT-licensed — no relicensing, ever, and no framework feature will ever be moved behind the managed platform. Websockets, cache revalidation, ordinary tasks, and cron run in the self-hosted Node output. This commitment is written down in GOVERNANCE.md and enforced by tests/self-host-audit/ in CI on every commit.

Deployment targets have different capabilities: see the support matrix. Standalone task state and waits are in-process, not restart-durable. The shipped durable broker and step suspend/resume currently require the managed platform; standalone durable execution remains a portability gap.

Install

pnpm add @celsian/vura-core @celsian/vura-cli @celsian/vura-adapter-vura

The CLI exposes vura as the installed command. The package was historically named then/thenjs; then is a shell reserved word and was never a safe script name. Only vura ships as a bin — use it in all scripts.

Requirements

• Node.js 20 or 22 (engines.node is constrained to >=20 <23)
• pnpm 10.11.0 (the version pinned by packageManager)

Recommended activation on fresh machines:

corepack enable
corepack prepare [email protected] --activate
pnpm install --frozen-lockfile

Quick start

pnpm create vura@latest my-app
cd my-app
pnpm dev
pnpm build

create-vura treats dependency installation as part of a successful scaffold. If install fails, the command exits non-zero after writing the files so registry or namespace-access problems cannot be missed. Pass --no-install explicitly to inspect or test the starter shape without installing:

npx create-vura my-app --no-install

Example scripts:

{
  "scripts": {
    "dev": "vura dev",
    "build": "vura build"
  }
}

The generated project includes managed deployment support. After linking a project and building it, vura deploy uploads a preview and vura deploy --prod targets production. Self-hosting remains available through the Node, Cloudflare, and Lambda build outputs.

The managed service is in private beta; signup requires an access code. Installing the adapter does not grant service access.

API endpoints and tasks default to scale-to-zero Function compute at 1 GiB; selectable Function profiles are 1, 4, 6, 8, and 12 GiB. Dedicated is the persistent path for WebSockets, process-local state, and latency-sensitive always-warm endpoints. Dedicated capacity uses provider-neutral profiles from nano through 4xlarge, or explicit memory and CPU values where supported.

Deploy today

Node / VPS / Fly / Railway

The default build emits a standalone Node server at dist/server/entry.js and static assets under dist/static.

pnpm install --frozen-lockfile
pnpm build
PORT=3000 NODE_ENV=production node dist/server/entry.js

Set runtime environment variables in your host dashboard, then health-check your deployed URL. The generated server serves API routes, server/hybrid pages, and static/client pages from one process.

Cloudflare Workers

Use the Cloudflare adapter when you want Worker artifacts instead of the Node server:

pnpm add @celsian/vura-adapter-cloudflare
# configure vura.config.js with the adapter
pnpm build
cd dist/cloudflare
wrangler deploy

Cloudflare route handlers intentionally receive the same conservative req/reply shim as other generated targets, plus Cloudflare-only escape hatches on req.__cf_env and req.__cf_ctx. Keep this runtime surface narrow until a concrete adapter use case needs a first-class API; widening the shim would become public API surface that must work across Worker, Node, and managed Vura Platform deployments.

AWS Lambda / SAM

Use the Lambda adapter for API Gateway/Lambda packaging:

pnpm add @celsian/vura-adapter-lambda
# configure vura.config.js with the adapter
pnpm build
sam deploy --guided --template-file dist/template.yaml

Page modes and build output

vura build now emits deployable build-time output for every non-server page mode:

• static pages prerender to dist/static/<route>/index.html with no framework JavaScript added.
• client pages prerender a loading shell and emit a browser module under dist/static/_then/pages/*.js; the HTML references that module.
• hybrid pages prerender HTML and emit a matching browser module under dist/static/_then/pages/*.js for hydration/island code.
• server pages remain runtime-rendered by dist/server/entry.js.

The generated Node server serves API routes and server-mode runtime pages, then falls back to dist/static for static, client, and prerendered hybrid pages. Cloudflare and Lambda support these page modes, but do not execute src/middleware.ts or server actions; enforce authorization inside handlers and loaders on those targets. See the target limitations.

Packages

• @celsian/vura-contract — dependency-free legacy/v1 manifest validation and capability evaluation (contract and rollout guide); introduced in 0.8.2 and used by Node build/server-entry readers from 0.8.3.
• @celsian/vura-core — manifest scanning, build pipeline, generated production server, and runtime helpers.
• @celsian/vura-cli — vura command-line interface (historically named then/thenjs; only vura ships as a bin).
• @celsian/vura-adapter-lambda — AWS Lambda/API Gateway deployment artifacts.
• @celsian/vura-adapter-cloudflare — Cloudflare Workers deployment artifacts.
• @celsian/vura-adapter-vura — managed Vura preview and production deployment.
• @celsian/vura-vite-plugin — Vite integration.
• @celsian/vura-compiler — pure JavaScript compiler fallback.

Release checks

Before publishing, run:

corepack enable
corepack prepare [email protected] --activate
pnpm install --frozen-lockfile
pnpm release:check

To bypass a mismatched local Corepack/global pnpm toolchain, run the same gate with Node 22 and the pinned pnpm directly:

npx -p node@22 -p [email protected] pnpm install --frozen-lockfile
npx -p node@22 -p [email protected] pnpm release:check

pnpm release:check runs the full local gate: private-package assertions, hygiene lint, build, tests, production audit, packed publish smoke, tracked tarball-size limits, npm publish dry-run, whitespace checks, and a clean git tree assertion.

Do not publish from an unverified or dirty release tree. Run pnpm release:check first, then follow RELEASING.md. Before any upload, real publishing requires explicit account-level read-write access to every planned package, including unscoped create-vura. Missing or read-only access stops the batch; resolve the specific package access rather than granting broad namespace control. This preflight does not prove granular-token or package 2FA permissions. First publication of a new package requires a separately reviewed bootstrap; there is no skip-preflight flag.