HeronJS is a TypeScript framework for modular server applications on Node.js. It provides modules, decorators, dependency injection, and reactive execution for HTTP APIs, messaging, background services, and agent protocols.
Typed contracts connect controllers, providers, services, and protocol handlers. Each application owns its dependency container and resources, and the framework coordinates their initialization and shutdown.
Version 4.0.0 brings native Fastify HTTP, application-owned dependency injection, worker threads, and agent protocols into the same modular framework. It requires Node.js 24 or later and publishes ESM JavaScript and TypeScript declarations. Both 4.0.0 and 3.7.11 are LTS versions; the 3.7.11 documentation remains available separately.
For the core concepts, read Framework Knowledge. The Knowledge Catalog lists package responsibilities, and the Knowledge Graph shows HeronJS package and submodule relationships.
Architecture
Each application owns its container, registry, services, and resources. Decorators describe components; modules declare which components participate in the application. HeronJS.create({module}) builds a fresh application, and await app.close() waits for its owned resources to shut down.
The diagram shows the framework’s main dependency direction. Core composes the application and protocol extensions; core and the adapters depend on common, and common depends on thread. Thread is independent of the other framework packages.
One application, multiple protocols
REST, GraphQL, tRPC, WebSocket, MCP, and ACP can share one HTTP listener. The package name @heronjs/express is retained, but its HTTP engine is native Fastify 5. Configure Fastify hooks and plugins for HTTP integration.
HTTP is the default transport. MCP and ACP also support explicitly selected stdio transport, with one endpoint owning process stdio. EBS provides Kafka, NATS, and AMQP messaging integrations.
Reactive execution and workers
Protocol handlers support values, Promises, and RxJS Observables. Unary operations consume the first emission; streaming operations own their subscriptions and cancellation. See Reactive Execution for each boundary’s behavior.
@heronjs/thread provides worker pools, dedicated Runnable services, bounded queues, and cancellation. Common supplies the worker DI bridge, and core manages its application lifecycle. Ordinary @Service classes remain on the main thread; use Thread for worker execution.
Third-party frameworks
| Framework or library | Role in HeronJS 4.0.0 |
|---|---|
| Fastify 5 | Provides the native HTTP server, request/reply APIs, hooks, and plugins. |
| Keyv | Provides cache managers for application-owned stores. |
| Knex | Provides SQL connections and query building for datasources. |
| RxJS | Normalizes asynchronous results and drives reactive execution. |
| ws | Provides native WebSocket connections. |
| GraphQL / graphql-http | Provides schema execution and GraphQL over HTTP on Fastify. |
| tRPC | Provides typed procedure endpoints and HTTP/SSE subscriptions. |
| Model Context Protocol SDK | Provides the protocol contracts and transports for MCP tools, resources, and prompts. |
| Agent Client Protocol SDK | Provides agent contracts and transports for ACP, including its experimental HTTP transport. |
Get started
Follow Getting Started to create a 4.0.0 application, or explore examples in the version-switchable playground. Existing applications can use the Migration Guide to review the breaking changes from 3.7.11.
Based on the 4.0.0 release source .