btravstack

btravstack

A backend framework for Node.js and TypeScript — dependency injection the compiler proves, errors as values instead of exceptions, and a process that shuts down the way Kubernetes expects.

Documentation · Get Started · Why btravstack?

btravstack is the layer between your business logic and the process it runs in. You build an application out of ports and providers, and the compiler checks that everything one needs, another supplies. A starter then brings the transport — an HTTP server, a Temporal worker, an AMQP consumer — and the framework owns boot, readiness and shutdown.

It is not a full-stack framework: no ORM, no templating, no frontend. What it replaces is the main.ts every backend writes by hand and gets subtly wrong.

What you get

Why btravstack?

Every backend process gets the same things wrong on its own: it stops accepting the instant SIGTERM lands and rejects the traffic Kubernetes is still routing to it; its readiness probe answers from a transport rather than from its state; a failed finaliser is logged and forgotten; a crash exits 0. btravstack gets them right once, as defaults.

• 🧩 Business code only. A composition root is a HttpModule("OrdersApi")({ router, imports, exports, needs }) and a main.ts is await runMain(OrdersApi). Configuration is bound from the environment inside the graph; there is no process.env, no app.listen, no signal handler to write.
• 🛂 Wiring proven at compile time. A module missing a provider, a composition root exporting no runtime, a runtime naming a port the graph does not carry — each is a type error at the call site, not a crash at boot.
• 🚦 A drain that survives Kubernetes. Readiness flips first, the kernel waits out the eventually-consistent endpoint removal, then in-flight work gets its deadline; whatever is still open is aborted and reported abandoned.
• 🎯 Nothing throws. Every async surface is an unthrown AsyncResult; the kernel never calls process.exit, and runMain is the one place a process's fate becomes an exit code — 0, 1, 2, 70 or 78, each meaning one thing.

How it compares

Every framework in that table manages its lifecycle, and so do Spring Boot (graceful shutdown on by default), the .NET Generic Host and Effect's runMain. The difference is narrower. The compiler checks the composition (module visibility, scopes and transitive needs, not only a constructor's arguments), and what it cannot see is a defect before any factory runs. The pre-drain delay, the drain's deadlines and its unit accounting are defaults rather than deployment work. The AdonisJS row is from its v6 lifecycle and service providers pages.

NestJS has far more packages, integrations and hiring pool, and decorators are more concise to write. If that trade matters more than compile-time certainty, Nest is the better tool — the Coming from NestJS page says so in detail, including what Nest does better.

btravstack is for teams that already chose TypeScript for the type safety and want the framework to honour that choice rather than opt out of it. See Why btravstack? for the design argument and what it is not.

The entity guide shows how to model the domain used by the examples. It is usable without the process framework.

Install

pnpm add @btravstack/core @btravstack/config @btravstack/di unthrown

For an HTTP API add the starter and its peers:

pnpm add @btravstack/http-server @btravstack/orpc-server @btravstack/htmx-server @orpc/server@2.0.0-beta.44 @orpc/contract@2.0.0-beta.44 @orpc/openapi@2.0.0-beta.44 @orpc/json-schema@2.0.0-beta.44 @orpc/client@2.0.0-beta.44 @unthrown/orpc@^0.4.2

Everything is a peer dependency — the application holds one copy of each, which is what keeps port identity and isResult honest across packages. The kernel and @btravstack/config depend on node: builtins only. They require Node >=22; the HTTP starter above requires >=22.12.

Every package shares one version, pre-1.0 minors may break, and security fixes land on the latest release only — read Support and upgrades before adopting. Each release's notes, migration steps included, are on its release pull request.

Working with a coding agent? Install the framework's agent skill: npx skills add btravstack/btravstack --skill btravstack.

Quick example

An HTTP API is a contract, a router that implements it from the use cases it declares, and a composition root. This is examples/order-api's orders slice, served on its own and condensed to one procedure — the example itself composes that slice and a customers one into a single router through controllers:

contract.ts — declared before any implementation exists; a client needs only this file.

import { oc, type } from "@orpc/contract";

export const ordersContract = {
  place: oc
    .input(type<{ readonly id: string; readonly quantity: number }>())
    .output(type<{ readonly id: string; readonly quantity: number }>())
    .errors({
      INVALID_QUANTITY: { data: type<{ readonly id: string }>() },
      BAD_REQUEST: { data: type<{ readonly id: string }>() },
      CONFLICT: { data: type<{ readonly id: string }>() },
    }),
};

router.ts — one Result-returning function per procedure, typed by the contract.

Three names in the fences below are yours, not this framework's, and nothing here declares them for you: PlaceOrder is a di Port carrying your use case and its modeled errors (InvalidQuantity, InvalidOrderId, DuplicateOrder); OrderApplicationModule provides it; OrderPersistenceModule holds the adapters behind it. Together they are about twenty lines of ordinary TypeScript — the tutorial writes every one from an empty directory.

import { defineHttp } from "@btravstack/orpc-server";
import { P } from "unthrown";

// One call mints every marker-typed HTTP entity; a public API declares no
// security scheme, so it takes no argument.
const api = defineHttp();

export const ordersRouter = api.OrpcRouter(ordersContract)({
  inject: { place: PlaceOrder },
  sync: ({ place }) => ({
    place: ({ errors }, input) =>
      place
        .execute(input.id, input.quantity)
        .map((order) => ({ id: order.id, quantity: order.quantity }))
        // The one place a domain error becomes a transport one — exhaustive,
        // so a new domain error is a compile error here.
        .mapErrCases((matcher) =>
          matcher
            .with(P.tag("InvalidQuantity"), (error) =>
              errors.INVALID_QUANTITY({
                message: error.message,
                data: { id: error.id },
              }),
            )
            // A malformed id is the caller's mistake, so 400 — not the
            // 409 a duplicate gets.
            .with(P.tag("InvalidOrderId"), (error) =>
              errors.BAD_REQUEST({
                message: error.message,
                data: { id: error.id },
              }),
            )
            .with(P.tag("DuplicateOrder"), (error) =>
              errors.CONFLICT({
                message: error.message,
                data: { id: error.id },
              }),
            ),
        ),
  }),
});

main.ts — the composition root and the entry point; this is the whole process.

import { runMain } from "@btravstack/core";
import { HttpModule } from "@btravstack/orpc-server";

const OrdersApi = HttpModule("OrdersApi")({
  router: ordersRouter,
  imports: [OrderApplicationModule, OrderPersistenceModule],
});

await runMain(OrdersApi);

HttpModule is sugar over the same primitives: it imports the starter (PORT and HOST bound from the environment, the router mounted under /rpc), provides the router and exports the runtime port, and returns exactly the di module a hand-written Module("OrdersApi")({...}) would have. runMain builds the graph, serves it, drains it on SIGTERM in three beats, and sets the exit code. Boot the same OrderApplicationModule under TemporalModule or AmqpModule and you have the worker and the consumer — one application, three deployments.

Packages

Examples

Ten small packages under ./examples model one clean-architecture order application — domain, application, infrastructure, three contracts — booted under three runtimes: order-api answers over HTTP, order-temporal-worker orchestrates, order-amqp-worker broadcasts every committed write from a transactional outbox — and the same DuplicateOrder becomes a typed CONFLICT on the first and a non-retryable contract error on the second, with no mapping anywhere near the kernel. Plus the container's own di-hexagonal, which never calls start. Each is compiled, linted and tested by CI like a package. See the annotated walkthroughs.

Contributing

This is a pnpm + turbo monorepo. The gate — every change keeps all six green, and CI runs the same set:

pnpm install
pnpm format --check   # oxfmt (run without --check to auto-fix)
pnpm lint             # oxlint, incl. every @unthrown/oxlint rule
pnpm typecheck        # tsc, incl. the type-level *.test-d.ts files
pnpm knip             # dead code / unused deps
pnpm test             # vitest + v8 coverage (100% lines/functions on packages)
pnpm build            # tsdown CJS/ESM + d.ts (Temporal worker: ESM only)

The gate needs a running Docker daemon. Every workspace that boots a real dependency — a broker, a workflow platform, a database, a cache, an SMTP server, an object store — attaches to a container started once per machine and shared, rather than starting one of its own (internal/test-infra, which owns the list). Isolation is the boundary each system already has, minted in setup and never cleaned up: a vhost per test, a namespace per spec file, a tenant per test, a Redis key prefix per test, a recipient per test, and an object-store key prefix per test. Remove the containers with docker rm -f $(docker ps -aq --filter label=com.btravstack.test-infra).

Commits follow Conventional Commits; user-facing changes carry a changeset. AGENTS.md is the authoritative spec — the theses, the public surface and the conventions, with the reasoning behind each.

License

MIT © Benoit TRAVERS