Introduction
Learn the one idea behind okengine — then the eight elements and ten exports.
OKE is a Bun-first TypeScript backend. You do not learn a pile of unrelated tools (router + queue + cron + websockets). You learn one sentence, and everything else follows from it.
The one law
Every backend behavior is a Flow:
on(Trigger) → Effects
There are no separate species called endpoints, handlers, consumers, jobs, subscribers, or workflows. There is one species — the Flow — and triggers are typed values:
on(http.post("/bookings"), createBooking); // "an API endpoint"
on(every("10m"), expireStale); // "a cron job"
on(orderPlaced, sendReceipt); // "a queue consumer"
on(db.table(users).changed("email"), reverify); // "a CDC trigger"Same shape every time: a trigger, a flow body, and effects inferred from what that body touches through fx.
Why this lowers the learning curve
One law → one mental model → one documentation path → one trace shape → one thing for an AI agent to learn.
Learning OKE is learning one sentence.
What you get
You write TypeScript. At build time OKE extracts a Manifest — a machine-readable description of your system. From that Manifest the rest is derived, not configured by hand:
- Typed client (no separate codegen step to maintain)
- OpenAPI / docs surfaces
- Architecture diagram that is the effect graph
- Console panels, traces, and explorers
- MCP surface for agents (
:6535) - Least-privilege capability matrix and cache invalidation keys
Ten exports
The entire public vocabulary fits in one import:
import { on, flow, signal, store, clock, gate, vault, channel, ai, plugin } from "okengine";| Export | Role |
|---|---|
on | Bind a trigger to a flow |
flow | Define behavior + contracts |
signal | Data in motion (queue / pub-sub / live) |
store | Data at rest (sql · kv · files · index) |
clock | Time (cron, delay, sleep, TTL) |
gate | Permission to act (auth, ABAC, limits) |
vault | Secrets and config |
channel | Reach humans (email, SMS, …) |
ai | Reach models / agents |
plugin | Extend the runtime without a ninth element |
Everything else in the docs is derived from these ten names.
The eight elements
Everything a backend has ever needed reduces to eight typed elements. An element earns its place only if it has irreducible physics. New infrastructure becomes a new driver for an existing element — never a ninth element.
- 01
Flowbehavior
Endpoints, jobs, consumers, and workflows — one species.
on(http.post) → writes - 02
Signaldata in motion
Queues, pub/sub, and streams — delivery is a property.
oncebroadcastlive - 03
Storedata at rest
SQL, KV, files, and search index as one store surface.
sqlkvfilesindex - 04
Clocktime
Cron, delays, timeouts, and durable sleep.
every("10m") - 05
Gatepermission to act
Auth, ABAC, rate limits, and feature flags at the trigger.
.gate(member) - 06
Vaultprotected knowledge
Secrets and config with typed contracts.
fp:••••a7c3 - 07
Channelreaching humans
Email, SMS, WhatsApp, push — consent and locale built in.
emailSMSpush - 08
AIreaching machine intelligence
Models, prompts, agents, and RAG with cost and PII rules.
allowPii: denied
What each element replaces
| Element | Replaces the zoo of |
|---|---|
| Flow | endpoint · handler · consumer · job · workflow · webhook |
| Signal | queue · pub/sub · stream · websocket · SSE · event bus |
| Store | database · cache · KV · file storage · search index |
| Clock | cron · delay · timeout · durable sleep · TTL |
| Gate | auth · session · ABAC · rate limit · quota · feature flag |
| Vault | secrets · config · environment |
| Channel | email · SMS · WhatsApp · push |
| AI | model calls · prompts · embeddings · agents · RAG |
The fx rule
All world access goes through fx. A Flow that imports node:fs (or any other side-channel I/O) is a defect.
That single rule is why cache invalidation, live queries, least privilege, deterministic tests, and Manifest Diff can be inferred instead of annotated by hand. You will see fx in every example from here on.
Where to go next
Read in this order if you are new:
- Comparison — when OKE fits (and when it doesn't)
- Installation — scaffold an app in minutes
- Basic Usage — first flows, client, and tests
- Notes — full teaching path
Comparison
Positioning matrix against Hono, Elysia, Encore.ts, and iii.
Installation
Install okengine and scaffold with create-oke.
Basic Usage
Flows, typed client, and tests from the Notes example.
AI resources
AGENTS.md and MCP (:6535) expose the Manifest, schemas, effects, traces, and the Console's safe runtime actions. See AI Resources for the agent contract and machine-readable docs (/llms.txt, /llms-full.txt).