Orveth — modular TypeScript backend framework ecosystem by VLODIA

Documentation  ·  GitHub

---

Overview

Orveth is an open-source modular TypeScript backend application platform by VLODIA. The HTTP runtime lives in @orveth/server (routing with path params and wildcards, middleware, RequestContext); optional packages add errors, config, logging, Zod validation, CORS, security headers, TLS, JWT, and Prisma integration helpers. Install one scoped package or the orveth umbrella when you want every module on one version line.

Phase 1 focuses on the backend foundation: predictable routing, context API, middleware ordering, errors, and small official middleware packages—not a CLI, hosted platform, or full auth product.

Early stage: APIs are published and tested, but the ecosystem is pre-1.0. Expect iteration; pin versions in production.

import { Orveth } from "orveth";
// equivalent: import { Orveth } from "@orveth/server";

Philosophy

• Framework-shaped, modular by design — one HTTP runtime (Orveth), many small packages around it.
• Explicit over magical — routing, middleware, and errors behave predictably.
• TypeScript-first — strict types on every public export; no any in published sources.
• Honest scope — not a full-stack UI framework, hosted platform, or ORM.

You bring your database client, auth model, and deployment target. Integrations stay optional.

Ecosystem

Package	Role
orveth	Umbrella package — re-exports @orveth/server and optional modules
@orveth/server	Core runtime — Orveth app, pattern routing, middleware, JSON I/O
@orveth/http	Status codes, response preparation, headers
@orveth/https	TLS file loading and HTTPS listeners
@orveth/errors	Typed errors and JSON normalization
@orveth/config	Environment-backed configuration parsing (strict coercions)
@orveth/logger	Structured logging interfaces
@orveth/validation	Validation result types and Validator interface
@orveth/validation-zod	Official Zod adapter — body validation into ctx.valid.body
@orveth/cors	CORS and preflight middleware
@orveth/security	Request ID and minimal security headers middleware
@orveth/jwt	HS256 JWT sign/verify (via jose)
@orveth/prisma	Prisma shutdown hooks and DB health routes
@orveth/core	Lifecycle and package metadata primitives

Installation

npm install @orveth/server @orveth/errors

Full ecosystem:

npm install orveth

See the installation guide for optional modules (https, jwt, prisma).

Minimal example

import { Orveth } from "orveth";

const app = new Orveth();

app.get("/", (ctx) => ctx.ok({ ok: true }));

await app.listen(3000);
// or: await app.listen({ port: 3000, hostname: "127.0.0.1" });

Prefer import { Orveth } from "@orveth/server" when you only need the HTTP runtime. Handlers may return ctx.ok(...) or await ctx.json(...) — both work.

TLS (HTTPS)

Optional @orveth/https — TLS stays out of the core runtime on purpose.

import { Orveth } from "orveth";
import { listenHttps, readTlsFilePair } from "@orveth/https";

const app = new Orveth();
const tls = await readTlsFilePair({
  certPath: process.env.TLS_CERT_PATH!,
  keyPath: process.env.TLS_KEY_PATH!,
});

await listenHttps(app, 443, tls);

JWT (optional)

import { Orveth, signJwt, verifyBearerJwt } from "orveth";

const secret = process.env.JWT_SECRET!;
const app = new Orveth();

app.post("/login", async (ctx) => {
  const token = await signJwt({ sub: "user-1" }, secret, { expiresIn: "1h" });
  return ctx.ok({ token });
});

app.get("/me", async (ctx) => {
  const claims = await verifyBearerJwt<{ sub: string }>(ctx.request.headers.authorization, secret);
  return ctx.ok({ sub: claims.sub });
});

Prisma (optional)

import { PrismaClient } from "@prisma/client";
import { Orveth, createDatabaseHealthRoute, registerPrismaShutdown } from "orveth";

const prisma = new PrismaClient();
registerPrismaShutdown(prisma);

const app = new Orveth();
app.get("/health/db", createDatabaseHealthRoute({ client: prisma }));
await app.listen(3000);

Development

Requirements: Node.js ≥ 20.10, pnpm 9.

pnpm install
pnpm test

pnpm test runs a full workspace build first so Vitest resolves built dist/ entry points consistently.

For full local validation:

pnpm build
pnpm typecheck
pnpm test
pnpm lint
pnpm docs:dev

Publishing

Packages are published from this monorepo with Changesets. Use pnpm publish (or Changesets), not raw npm publish, so workspace:* dependencies resolve to real semver ranges on the registry.

# Validate tarballs (dry-run, resolves workspace deps)
pnpm publish:dry-run

# Release flow
pnpm changeset
pnpm release:version
pnpm release:publish

pnpm release:publish copies LICENSE into each package, builds dist/, and publishes all packages/* modules. Published tarballs include dist/*.js, dist/*.cjs, dist/index.d.ts, README.md, and LICENSE (source maps and duplicate .d.cts files are excluded).

Authenticate with npm (npm login) and ensure the @orveth scope is available for your account.

Contributing

Open an issue or pull request on GitHub. Keep changes focused, match existing package boundaries, and run pnpm build, pnpm test, and pnpm lint before submitting.

Documentation

• Site: https://orveth.vercel.app/
• Vercel: set Root Directory to apps/docs, Framework Preset Next.js, enable workspace root access for pnpm-lock.yaml.

License

MIT — see LICENSE. Orveth by VLODIA.