# NestJS (/integrations/nestjs)



[`@kubemq/nestjs-transport`](https://www.npmjs.com/package/@kubemq/nestjs-transport) is a
custom [NestJS](https://nestjs.com/) transport that integrates KubeMQ into the NestJS
microservices ecosystem. It surfaces all five KubeMQ messaging patterns — Commands, Queries,
Events, Events Store, and Queues — through idiomatic `@*Handler` decorators and a standard
`ClientProxy`, so a Nest app sends and handles KubeMQ messages with the same DI, modules, and
testing patterns it already uses for HTTP. It is built on the native
[`kubemq-js`](https://www.npmjs.com/package/kubemq-js) SDK and speaks gRPC directly to the broker
on port `50000`.

## Why KubeMQ + NestJS [#why-kubemq--nestjs]

* **Idiomatic decorators** — `@CommandHandler`, `@QueryHandler`, `@EventHandler`,
  `@EventStoreHandler`, and `@QueueHandler` replace manual `@MessagePattern` / `@EventPattern`
  metadata wiring; the right KubeMQ pattern is attached for you.
* **One transport, five patterns** — a single `KubeMQServer` strategy (inbound) and
  `KubeMQClientProxy` (outbound) cover every pattern; the `KubeMQRecord` builder re-targets the
  message type with `.asQuery()`, `.asEventStore()`, or `.asQueue()`.
* **Dynamic-module DI** — `forRoot` / `forRootAsync` / `register` / `registerAsync` /
  `forFeature` / `forTest` register the connection and named clients through NestJS dependency
  injection.
* **Distributed CQRS** — the [CQRS bridge](/integrations/nestjs/how-to/cqrs-bridge) routes `@nestjs/cqrs` `CommandBus`,
  `QueryBus`, and `EventBus` traffic across services over KubeMQ channels.
* **TypeScript-first** — full type safety with an ESM + CJS dual build and per-pattern context
  types.
* **Broker-free tests** — `MockKubeMQClient`, `MockKubeMQServer`, and `KubeMQModule.forTest()`
  exercise services and handlers without a live broker.

## Installation [#installation]

```bash
npm install @kubemq/nestjs-transport kubemq-js
```

Most peer dependencies already ship with a typical NestJS project; install any that are missing:

```bash
npm install @nestjs/common @nestjs/core @nestjs/microservices rxjs reflect-metadata
```

Optional peer dependencies enable specific features — `@nestjs/terminus` for the health-check
indicator and `@nestjs/cqrs` for the [CQRS bridge](/integrations/nestjs/how-to/cqrs-bridge):

```bash
npm install @nestjs/terminus   # health checks
npm install @nestjs/cqrs        # CQRS bridge
```

<Callout type="info">
  **Prerequisites:** Node.js 20.11.0 or later and a running KubeMQ broker (default
  `localhost:50000`). The transport is a native gRPC SDK client — there is **no connector flag to
  enable**; the gRPC API on `50000` is always on. Start a local broker with Docker (gRPC on `50000`,
  the shared HTTP server and dashboard on `9090`):

  <RunKubeMQ ports="[50000, 9090]" />
</Callout>

## Supported versions [#supported-versions]

| Requirement | Supported versions                       |
| ----------- | ---------------------------------------- |
| Language    | TypeScript `5.5+` (ESM + CJS dual build) |
| Runtime     | Node.js `>= 20.11.0`                     |
| NestJS      | `10.x` or `11.x`                         |
| KubeMQ SDK  | `kubemq-js` `^3.0.1`                     |
| Package     | `@kubemq/nestjs-transport` `1.0.0`       |

## Architecture [#architecture]

A KubeMQ-backed NestJS app is a
[hybrid application](https://docs.nestjs.com/faq/hybrid-application): the HTTP app stays as-is
while the KubeMQ transport is attached as a microservice. Inbound handlers run through the
`KubeMQServer` strategy passed to `app.connectMicroservice({ strategy })`; outbound clients are
`KubeMQClientProxy` instances registered with `KubeMQModule`. Both wrap a `kubemq-js` client and
speak gRPC to the broker on port `50000`.

<Mermaid
  chart="`
graph LR
APP[&#x22;NestJS app<br/>(hybrid)&#x22;]
SRV[&#x22;KubeMQServer<br/>strategy (inbound)&#x22;]
CLI[&#x22;KubeMQClientProxy<br/>(outbound)&#x22;]
JS[&#x22;kubemq-js client&#x22;]
BROKER[&#x22;KubeMQ broker<br/>:50000&#x22;]

APP -- &#x22;@*Handler&#x22; --> SRV
APP -- &#x22;send / emit&#x22; --> CLI
SRV --> JS
CLI --> JS
JS -- &#x22;gRPC :50000&#x22; --> BROKER

class APP client
class SRV,CLI connector
class JS data
class BROKER broker
`"
/>

*Decorated handlers and injected client proxies both wrap `kubemq-js` and reach the broker over native gRPC.*

## Capabilities [#capabilities]

The transport plugs into NestJS DI and dispatch. Each capability below documents the
integration's own API surface and links to the underlying KubeMQ concept rather than re-teaching
it.

| Capability         | Surface                                              | KubeMQ concept                      |
| ------------------ | ---------------------------------------------------- | ----------------------------------- |
| Commands / Queries | `@CommandHandler` / `@QueryHandler`, `client.send()` | [RPC](/learn/rpc)                   |
| Events             | `@EventHandler`, `client.emit()`                     | [Events](/learn/events)             |
| Events Store       | `@EventStoreHandler`, `.asEventStore()`              | [Events Store](/learn/events-store) |
| Queues             | `@QueueHandler`, `.asQueue()`, manual ack            | [Queues](/learn/queues)             |
| Module DI          | `forRoot` / `register` / `forFeature` / `forTest`    | —                                   |
| Distributed CQRS   | `KubeMQCqrsModule` over `@nestjs/cqrs` buses         | —                                   |

<Cards>
  <Card title="Usage" href="/integrations/nestjs/how-to/usage" description="The five handler decorators and the KubeMQRecord builder — send and handle every pattern." />

  <Card title="Module configuration" href="/integrations/nestjs/how-to/module-configuration" description="forRoot / forRootAsync, register / registerAsync, forFeature, and multi-broker DI." />

  <Card title="CQRS bridge" href="/integrations/nestjs/how-to/cqrs-bridge" description="Route @nestjs/cqrs CommandBus, QueryBus, and EventBus over KubeMQ channels." />
</Cards>

## Next steps [#next-steps]

<Cards>
  <Card title="Getting started" href="/integrations/nestjs/tutorials/getting-started" description="Stand up a hybrid app, register a handler, and send your first command in minutes." />

  <Card title="Concepts" href="/integrations/nestjs/concepts" description="The transport model, send/emit mapping, contexts, serialization, and connection lifecycle." />

  <Card title="Guides" href="/integrations/nestjs/how-to/configuration-and-resilience" description="Production hardening — TLS/auth, reconnection, DLQ, validation, idempotency, and testing." />

  <Card title="Reference" href="/integrations/nestjs/reference/configuration" description="Configuration options, the full decorator/context API, and the error catalog." />
</Cards>

New to integrations? See [what an integration is](/integrations#what-an-integration-is) for
the mental model, or start with the [KubeMQ Getting Started guide](/deploy) for core
broker concepts. This transport speaks native gRPC on port `50000` — it is a direct SDK client,
not a [connector](/connectors).