Examples

Every example under examples/ is a complete, runnable app — clone it, pnpm dev, and read the source alongside this list. Start at the learning ladder (L01–L08) for the fundamentals, then the flagship to see a real app structured and deployed, and reach for a gap example when you need something the flagship can't structurally show.

Learn by building

Read the ladder in order — every step assumes the concepts introduced before it — then read the flagship to see the whole framework composed into one real app, and reach for a gap example when you need to see something the flagship can't structurally show.

The learning ladder

A strictly progressive path under examples/ladder/; each step adds exactly one concept. pnpm dev serves L01.

• L01 — Minimal — The smallest end-to-end app: a root module, a feature module with a constructor-injected repository, a typed controller with two GET routes, and one graph-propagated middleware.
• L02 — HTTP + validation — Typed routes, a middleware, request-body validation, and framework errors rendered as RFC 9457 problem+json.
• L03 — Events — Decouple modules with events — a shop module publishes order events, a notifications module reacts, and neither imports the other; the only seam is the EventBus.
• L04 — Database — Persistence with the Drizzle libsql/SQLite dialect — a tasks table behind a full CRUD API on in-memory libsql.
• L05 — CQRS — Split writes from reads: commands on the CommandBus, queries on the QueryBus, each message routed to exactly one handler.
• L06 — DDD — DDD aggregates over a Drizzle entity repository — branded ids, value-object columns, row↔domain mapping, optimistic concurrency, boot migrations, and a seed task.
• L07 — Auth — JWT auth with password hashing behind the PasswordHashingAlgorithm port, a request-scoped AuthContext, the shipped JWTAuthMiddleware, and permission scopes.
• L08 — Queue — The integration-events tier on the in-memory queue: a sign-up endpoint emits an event, a handler consumes it off the queue and sends a templated welcome email; the 201 returns first.

The flagship

examples/flagship/ is an event-ticketing workspace: six @ticketing/* bounded-context packages (shared, catalog, orders, payments, notifications, realtime) composed by thin per-platform deploy apps — a Node monolith plus Cloudflare Workers, Cloudflare + MySQL/Hyperdrive, AWS Lambda, Vercel, and a notifications split.

It is the reference for how a real Heximon app is structured (bounded contexts behind ports, dual SQLite/MySQL dialects), deployed unchanged across hosts, and tested end-to-end — CQRS + DDD, the transactional outbox with cross-service fan-out, a durable saga + a durable workflow, multi-tier caching, security hardening, health probes, OpenTelemetry, OpenAPI + MCP, and DO-backed real-time (a seat-hold WebSocket + SSE feed).

Gap examples

Under examples/gap/ — exactly what the flagship structurally can't show, standalone and thematic.

• alternate-bundlers — The same app compiled by whichever bundler you run through @heximon/build — proving the compile step and generated wiring are bundler-portable.
• cross-service-transports — Five cross-service integration-event fan-out legs for producers with no shared broker — a split per-service queue, a Redis Streams broadcast, AWS SNS→SQS, an Upstash QStash push (for freezing serverless subscribers), and the outbox-composed reliable form.
• edge-platforms — Edge/serverless deploy targets from one source — Deno Deploy, Netlify (Functions cron + an Async Workloads queue), an OpenTelemetry Node trace, and the Vercel/Netlify mixed-runtime (edge + node) splits.
• nitro-presets — The same Heximon app hosted inside Nitro and built across every Nitro deploy preset (a real nitro build per preset — node-server / bun / deno-server / aws-lambda / cloudflare_module / vercel / netlify / netlify-edge / deno-deploy — each output smoked). The flagship uses native strategies, so it can't show the Nitro host or its cross-preset builds.
• notifications — One channel-agnostic Notification fanned across email/SMS/push via the NotificationDispatcher — per-channel templating, fanout/fallback, recipient/device resolution, and bounce suppression.
• nuxt — Heximon modules on the server plus a Vue page on the client, served by one Nitro v3 (Nuxt) server via @heximon/nuxt.
• openapi-mcp — One products Contract served three ways — the HTTP API, an OpenAPI 3.1 doc + Scalar page, and an MCP server whose tool manifest is generated from the same routes; a Zod v4 schema gives both surfaces real JSON Schema, with a forwarded bearer authorizing a scoped tools/call.
• saga-orchestration — A durable saga coordinating three bounded contexts with a process-state aggregate and a one-shot durable payment deadline; both timer paths tested.
• standalone-runtime — One compiled app run as a long-lived server on Node, Bun, and Deno via @heximon/http/serve — no Nitro, no platform wrapper.
• storage-blob-adapters — Three port-driven storage features in one app — multipart upload into a BlobStore, presigned GET/PUT URLs via the SignedUrlBlobStore capability token, and an env-driven Storage KV adapter (memory / Redis / Upstash) — each driver swapped by binding, not code.
• workflow-compensation — Reactive choreography across Orders/Inventory/Payment over the transactional outbox — no central coordinator; happy and compensation paths tested.

Run one

Every example is a standalone workspace package driven by the same plugin you use in your own app:

cd examples/ladder/L01-minimal
pnpm install
pnpm dev    # compile src/ and serve the generated fetch app with hot reload
pnpm test   # run the example's tests

cd examples/ladder/L01-minimal
npm install
npm run dev    # compile src/ and serve the generated fetch app with hot reload
npm run test   # run the example's tests

cd examples/ladder/L01-minimal
yarn install
yarn run dev    # compile src/ and serve the generated fetch app with hot reload
yarn run test   # run the example's tests

cd examples/ladder/L01-minimal
bun install
bun run dev    # compile src/ and serve the generated fetch app with hot reload
bun run test   # run the example's tests

Each ladder step and most gap examples serve a fetch app on a free port; the nitro-presets gap example runs under Nitro instead.

A handful of gap examples — the deploy-target apps under edge-platforms and the multi-service cross-service-transports — are exercised in-process via createTestApp (with platform fakes/simulators) rather than a plain dev port; their READMEs say so.

The flagship's cloudflare and cloudflare-mysql apps run their end-to-end suites on real workerd. The typed-client examples inside flagship drive @heximon/client/sse and @heximon/client/ws against a mock transport, so pnpm test is the entry point there, not pnpm dev.

Each example's README lists the exact curl commands to exercise its endpoints.

Pick a path

Just starting out? These four cover the common early goals:

• Your first app? L01-minimal — a module, a controller, constructor-injected DI.
• Validating requests? L02-http-validation — typed routes, middleware, RFC 9457 errors.
• Persisting data? L04-database — a Drizzle-backed CRUD API.
• Adding auth? L07-auth — JWT verification, scopes, a guard middleware.

For every other goal — events, CQRS, background jobs, real-time, caching, deploying somewhere specific, cross-service fan-out — see the full goal-to-example map on Next Steps.

Next steps

• Quick Start — build the three-file app behind example L01 yourself.
• Core Concepts — modules, providers, and how the wiring fits together.
• Controllers — the two controller modes the examples lean on.
• Packages overview — the package each example pulls in.