BlueLibs Runner

Enterprise Application Runtime for TypeScript

Build apps from tasks and resources with explicit dependencies, predictable lifecycle, and first-class testing

Runner is a TypeScript-first toolkit for building an app out of small, typed building blocks. You can find more details and a visual overview at runner.bluelibs.com.

• Tasks: async business actions with explicit dependencies, middleware, and input/output validation
• Resources: singletons with a four-phase lifecycle: init, ready, cooldown, dispose
• Reliability Middleware: built-in retry, timeout, circuitBreaker, cache, and rateLimit
• Remote Lanes: cross-process execution (the "Distributed Monolith") with zero call-site changes
• Durable Workflows: persistent, crash-recoverable async logic for Node.js
• Events & hooks: typed signals and subscribers for decoupling
• Runtime control: run, observe, test, pause, recover, and dispose your app predictably

The goal is simple: keep dependencies explicit, keep lifecycle predictable, and make your runtime easy to control in production and in tests.

Versioning & Support

Runner follows a simple support policy so teams can plan upgrades without guesswork.

• 6.x: actively maintained. New features, improvements, bug fixes, and documentation updates land here first.
• 5.x: LTS through December 31, 2026. Critical fixes and important maintenance can continue there, but new development is focused on 6.x.

If you are starting a new project, use 6.x. If you are on 5.x, you have a stable upgrade window through the end of 2026.

See Support & Release Policy for the full versioning and support policy.

import { r, run } from "@bluelibs/runner";

const userCreated = r
  .event<{ id: string; email: string }>("userCreated")
  .build();

const userStore = r
  .resource("userStore")
  .init(async () => new Map<string, { id: string; email: string }>())
  .build();

const createUser = r
  .task<{ email: string }>("createUser")
  .dependencies({ userStore, userCreated })
  .run(async (input, { userStore, userCreated }) => {
    const user = { id: "user-1", email: input.email };

    userStore.set(user.id, user);
    await userCreated(user);

    return user;
  })
  .build();

const sendWelcomeEmail = r
  .hook("sendWelcomeEmail")
  .on(userCreated)
  .run(async (event) => {
    console.log(`Welcome ${event.data.email}`);
  })
  .build();

const app = r
  .resource("app")
  .register([userStore, createUser, sendWelcomeEmail])
  .build();

const runtime = await run(app);
await runtime.runTask(createUser, { email: "[email protected]" });
await runtime.dispose();

This example is intentionally runnable with only @bluelibs/runner, typescript, and tsx.

Note: User-defined ids are local ids. Prefer createUser, userStore, and sendWelcomeEmail. Runner composes canonical ids such as app.tasks.createUser at runtime.

| Resource | Type | Description | | ------------------------------------------------------------------------------------------------------------------- | ------- | ----------------------------------- | | Official Website & Documentation | Website | Overview and features | | GitHub Repository | GitHub | Source code, issues, and releases | | Runner Dev Tools | GitHub | Development CLI and tooling | | API Documentation | Docs | TypeDoc-generated reference | | Compact Guide | Docs | Compact summary (<10,000 tokens) | | Full Guide | Docs | Complete documentation (composed) | | Support & Release Policy | Docs | Support windows and deprecation | | Design Documents | Docs | Architecture notes and deep dives | | Example: AWS Lambda Quickstart | Example | API Gateway + Lambda integration | | Example: Express + OpenAPI + SQLite | Example | REST API with OpenAPI specification | | Example: Fastify + MikroORM + PostgreSQL | Example | Full-stack application with ORM |

Community & Policies

• Code of Conduct
• Contributing
• Security

Choose Your Path

• New to Runner: Start with Your First 5 Minutes
• Prefer an end-to-end example: Jump to Quick Start or the Real-World Example
• Need Node-only capabilities: See Durable Workflows
• Need remote execution: See Remote Lanes (expose from Node.js, call from any fetch runtime)
• Care about portability: Read Multi-Platform Architecture
• Planning upgrades: See Support & Release Policy
• Want the complete guide: Read FULL_GUIDE.md
• Want the short version: Read COMPACT_GUIDE.md

Platform Support (Quick Summary)

| Capability | Node.js | Browser | Edge | Notes | | ------------------------------------------------------ | ------- | ------- | ---- | -------------------------------------------------------------------------------------------- | | Core runtime (tasks/resources/middleware/events/hooks) | Full | Full | Full | Platform adapters hide runtime differences | | Async Context (r.asyncContext) | Full | None | None | Requires AsyncLocalStorage; Bun/Deno may support it via the universal build when available | | Durable workflows (@bluelibs/runner/node) | Full | None | None | Node-only module | | Remote Lanes client (createHttpClient) | Full | Full | Full | Explicit universal client for fetch runtimes | | Remote Lanes server (@bluelibs/runner/node) | Full | None | None | Exposes tasks/events over HTTP |

Prerequisites

Use these minimums before starting:

| Requirement | Minimum | Notes | | --------------- | ----------------------- | -------------------------------------------------------------- | | Node.js | 22.x+ | Enforced by package.json#engines.node | | TypeScript | 5.6+ (recommended) | Required for typed DX and examples in this repository | | Package manager | npm / pnpm / yarn / bun | Examples use npm, but any modern package manager works | | fetch runtime | Built-in or polyfilled | Required for explicit remote lane clients (createHttpClient) |

If you use the Node-only package (@bluelibs/runner/node) for durable workflows or exposure, stay on a supported Node LTS line.

Your First 5 Minutes

This page is the shortest path from "what is Runner?" to "I ran it once and I trust the shape of it."

New to Runner? Here's the absolute minimum you need to know:

1. Tasks are your business logic functions with dependencies, middleware, and validation.
2. Resources are shared services with a four-phase lifecycle: init, ready, cooldown, dispose.
3. You compose everything under an app resource with .register([...]).
4. You run it with run(app) which gives you runTask() and dispose() first, then more runtime helpers as you grow.

Quick Start

This is the fastest way to run the TypeScript example at the top of this README.

1. Confirm prerequisites from Prerequisites (Node 22+, TypeScript 5.6+ recommended).
2. Install dependencies:

npm i @bluelibs/runner
npm i -D typescript tsx

3. Copy the example above into index.ts.
4. Run it:

npx tsx index.ts

What you now have: a working runtime, explicit dependency wiring, and the smallest useful Runner execution path.

Tip: User-defined ids are local ids. Use createUser or userStore, not dotted ids like app.tasks.createUser. Platform Note: Advanced features such as Durable Workflows and server-side Remote Lanes are Node-only.

Local Ids vs Canonical Runtime Ids

You write local ids in definitions:

• task("createUser")
• resource("userStore")
• event("userCreated")

Runner composes canonical runtime ids from ownership:

• app.tasks.createUser
• app.userStore
• app.events.userCreated

Prefer references such as runTask(createUser, input) over string ids whenever you can.

Runner Dev Tools Quick Start

@bluelibs/runner-dev gives you CLI scaffolding and runtime introspection.

1. Install (or run without install):

npm install -g @bluelibs/runner-dev
# or
npx @bluelibs/runner-dev --help

2. Three common commands:

# Scaffold a new Runner project
runner-dev new my-app --install

# Query tasks from a local TypeScript entry file (dry-run mode)
runner-dev query 'query { tasks { id } }' --entry-file ./src/main.ts

# Inspect a running app via GraphQL endpoint
ENDPOINT=http://localhost:1337/graphql runner-dev overview --details 10

For full CLI and Dev UI docs, see Runner Dev Tools.

Real-World Examples

• AWS Lambda Quickstart
• Express + OpenAPI + SQLite
• Fastify + MikroORM + PostgreSQL

Where To Go Next

• Complete guide: Read FULL_GUIDE.md.
• Popular guide sections:
  • Tasks
  • Resources
  • Middleware
  • Testing
  • Observability
• API reference: Browse the TypeDoc documentation.
• Token-friendly overview: Read COMPACT_GUIDE.md.
• Node-only features:
  • Durable Workflows
  • Remote Lanes
• Releases and upgrades:
  • GitHub Releases
  • Support & Release Policy
• Multi-platform architecture: Read MULTI_PLATFORM.md.

License

This project is licensed under the MIT License. See LICENSE.md.