# Configuration (/integrations/nestjs/reference/configuration)



This page is the configuration lookup for `@kubemq/nestjs-transport` — package and runtime facts,
entry points, and every option interface for the server strategy, named clients, and the CQRS
bridge. For the decorator, context, and export surface see the [API reference](/integrations/nestjs/reference/api); for the
error catalog see [error codes](/integrations/nestjs/reference/error-codes). For task-oriented setup, start with
[Getting Started](/integrations/nestjs/tutorials/getting-started).

## Package & Entry Points [#package--entry-points]

`@kubemq/nestjs-transport` is the KubeMQ transport for [NestJS](https://nestjs.com/) microservices. It wires all five KubeMQ messaging patterns — Commands, Queries, Events, Events Store, and Queues — into the NestJS ecosystem with custom decorators, a dynamic module, health checks, a CQRS bridge, pluggable serialization, and testing utilities. It is built on the native [`kubemq-js`](https://www.npmjs.com/package/kubemq-js) SDK with a TypeScript-first API and an ESM + CJS dual build.

| Property           | Value                                                             |
| ------------------ | ----------------------------------------------------------------- |
| Package            | `@kubemq/nestjs-transport`                                        |
| Runtime            | Node.js `>= 20.11.0`                                              |
| NestJS             | `10.x` or `11.x`                                                  |
| TypeScript         | `5.5+`                                                            |
| Module format      | ESM + CJS dual build (`type: "module"`, `main` CJS, `module` ESM) |
| Runtime dependency | `kubemq-js` `^3.0.1`                                              |
| License            | MIT                                                               |

The package exposes three entry points through its `exports` map:

| Import path                        | Purpose                                                                                     |
| ---------------------------------- | ------------------------------------------------------------------------------------------- |
| `@kubemq/nestjs-transport`         | Main entry — server, client, module, decorators, contexts, errors, serialization, constants |
| `@kubemq/nestjs-transport/testing` | `MockKubeMQClient` and `MockKubeMQServer` for unit tests without a live broker              |
| `@kubemq/nestjs-transport/cqrs`    | `KubeMQCqrsModule` and the `@nestjs/cqrs` bus bridge                                        |

```bash title="install.sh"
# Core transport + runtime SDK
npm install @kubemq/nestjs-transport kubemq-js

# Peer dependencies (most ship with a typical NestJS project)
npm install @nestjs/common @nestjs/core @nestjs/microservices rxjs reflect-metadata

# Optional peers — only for the features that use them
npm install @nestjs/terminus   # health checks
npm install @nestjs/cqrs        # CQRS bridge
```

<Callout type="info">
  `@nestjs/terminus`, `@nestjs/cqrs`, `@msgpack/msgpack`, `protobufjs`, `class-validator`, `class-transformer`, and `@opentelemetry/api` are declared as **optional** peer dependencies. Install only the ones whose features you use — for example, `@msgpack/msgpack` is required by `MessagePackSerializer`, and `class-validator` / `class-transformer` are required by the decorator `validate` option.
</Callout>

The main entry point re-exports the testing mocks for convenience, so `MockKubeMQClient` and `MockKubeMQServer` are importable from either `@kubemq/nestjs-transport` or `@kubemq/nestjs-transport/testing`.

## KubeMQServerOptions [#kubemqserveroptions]

Configuration for the `KubeMQServer` transport strategy you pass to `connectMicroservice`. `KubeMQModuleOptions` is this interface plus an `isGlobal` flag. Only `address` is required.

| Parameter                | Type                                    | Default            | Required | Description                                                         |
| ------------------------ | --------------------------------------- | ------------------ | -------- | ------------------------------------------------------------------- |
| `address`                | `string`                                | —                  | **Yes**  | KubeMQ server address (`host:port`)                                 |
| `clientId`               | `string`                                | Auto-generated     | No       | Unique client identifier                                            |
| `credentials`            | `string`                                | `undefined`        | No       | Authentication token                                                |
| `tls`                    | `TlsOptions \| boolean`                 | `undefined`        | No       | TLS configuration                                                   |
| `group`                  | `string`                                | `undefined`        | No       | Default consumer group for all handlers                             |
| `defaultCommandTimeout`  | `number`                                | `10`               | No       | Default command timeout (seconds)                                   |
| `defaultQueryTimeout`    | `number`                                | `10`               | No       | Default query timeout (seconds)                                     |
| `eventsStore`            | `{ startFrom?, startValue? }`           | `undefined`        | No       | Events store defaults (`startFrom` is an `EventStoreStartPosition`) |
| `queue`                  | `{ maxMessages?, waitTimeoutSeconds? }` | `undefined`        | No       | Queue poll defaults                                                 |
| `serializer`             | `KubeMQSerializer`                      | `JsonSerializer`   | No       | Outbound message serializer                                         |
| `deserializer`           | `KubeMQDeserializer`                    | `JsonDeserializer` | No       | Inbound message deserializer                                        |
| `waitForConnection`      | `boolean`                               | `true`             | No       | Block startup until connected                                       |
| `callbackTimeoutSeconds` | `number`                                | `30`               | No       | Handler callback timeout (seconds)                                  |
| `retry`                  | `RetryPolicy`                           | kubemq-js default  | No       | Retry policy for transient errors                                   |
| `reconnect`              | `ReconnectionPolicy`                    | kubemq-js default  | No       | Reconnection policy                                                 |
| `keepalive`              | `KeepaliveOptions`                      | kubemq-js default  | No       | gRPC keepalive settings                                             |
| `tracerProvider`         | `unknown`                               | `undefined`        | No       | OpenTelemetry tracer provider                                       |
| `meterProvider`          | `unknown`                               | `undefined`        | No       | OpenTelemetry meter provider                                        |
| `verboseErrors`          | `boolean`                               | `false`            | No       | Include raw broker messages in exceptions                           |
| `verboseHealth`          | `boolean`                               | `false`            | No       | Include detailed health data in checks                              |
| `validation`             | `boolean`                               | `true`             | No       | Enable/disable class-validator integration globally                 |

<Callout type="info">
  **Timeout units.** Fields ending in `*Seconds` (such as `callbackTimeoutSeconds` and `waitTimeoutSeconds`) are in **seconds**. The reconnection fields without that suffix (`initialDelayMs`, `maxDelayMs`) are in **milliseconds**.
</Callout>

## KubeMQClientOptions [#kubemqclientoptions]

Configuration for a named `KubeMQClientProxy` created via `register` / `registerAsync`. It mirrors the server options for connection settings, and adds `circuitBreaker`, `defaultQueuePolicy`, and the internal `channelPrefix` set by `forFeature`.

| Parameter                | Type                        | Default            | Required | Description                                                    |
| ------------------------ | --------------------------- | ------------------ | -------- | -------------------------------------------------------------- |
| `address`                | `string`                    | —                  | **Yes**  | KubeMQ server address (`host:port`)                            |
| `clientId`               | `string`                    | Auto-generated     | No       | Unique client identifier                                       |
| `credentials`            | `string`                    | `undefined`        | No       | Authentication token                                           |
| `tls`                    | `TlsOptions \| boolean`     | `undefined`        | No       | TLS configuration                                              |
| `defaultCommandTimeout`  | `number`                    | `10`               | No       | Default command timeout (seconds)                              |
| `defaultQueryTimeout`    | `number`                    | `10`               | No       | Default query timeout (seconds)                                |
| `serializer`             | `KubeMQSerializer`          | `JsonSerializer`   | No       | Outbound message serializer                                    |
| `deserializer`           | `KubeMQDeserializer`        | `JsonDeserializer` | No       | Inbound message deserializer                                   |
| `defaultQueuePolicy`     | `QueueMessagePolicyOptions` | `undefined`        | No       | Default queue message policy                                   |
| `retry`                  | `RetryPolicy`               | kubemq-js default  | No       | Retry policy for transient errors                              |
| `reconnect`              | `ReconnectionPolicy`        | kubemq-js default  | No       | Reconnection policy                                            |
| `keepalive`              | `KeepaliveOptions`          | kubemq-js default  | No       | gRPC keepalive settings                                        |
| `tracerProvider`         | `unknown`                   | `undefined`        | No       | OpenTelemetry tracer provider                                  |
| `meterProvider`          | `unknown`                   | `undefined`        | No       | OpenTelemetry meter provider                                   |
| `callbackTimeoutSeconds` | `number`                    | `30`               | No       | Handler callback timeout (seconds)                             |
| `verboseErrors`          | `boolean`                   | `false`            | No       | Include raw broker messages in exceptions                      |
| `circuitBreaker`         | `CircuitBreakerOptions`     | `undefined`        | No       | Circuit breaker wrapping client operations                     |
| `channelPrefix`          | `string`                    | `undefined`        | No       | Channel prefix prepended to all channels (set by `forFeature`) |

### CircuitBreakerOptions [#circuitbreakeroptions]

<TypeTable
  type="{
  failureThreshold: {
    type: 'number',
    default: '5',
    description: 'Consecutive failures required to open the circuit.',
  },
  resetTimeout: {
    type: 'number',
    default: '30000',
    description: 'Milliseconds to wait before transitioning from open to half-open.',
  },
  halfOpenRequests: {
    type: 'number',
    default: '1',
    description: 'Number of probe requests allowed in the half-open state.',
  },
}"
/>

### QueueMessagePolicyOptions [#queuemessagepolicyoptions]

<TypeTable
  type="{
  expirationSeconds: {
    type: 'number',
    description: 'Message TTL in seconds.',
  },
  delaySeconds: {
    type: 'number',
    description: 'Delivery delay in seconds.',
  },
  maxReceiveCount: {
    type: 'number',
    description: 'Max delivery attempts before the message is routed to the dead-letter queue.',
  },
  maxReceiveQueue: {
    type: 'string',
    description: 'Dead-letter queue channel that exhausted messages are routed to.',
  },
}"
/>

## KubeMQCqrsOptions [#kubemqcqrsoptions]

Configuration for `KubeMQCqrsModule.forRoot` from `@kubemq/nestjs-transport/cqrs`. The bridge routes `@nestjs/cqrs` `CommandBus`, `QueryBus`, and `EventBus` traffic through KubeMQ channels named `{prefix}.{MessageName}`.

| Parameter              | Type                          | Default                    | Description                                           |
| ---------------------- | ----------------------------- | -------------------------- | ----------------------------------------------------- |
| `commandChannelPrefix` | `string`                      | `'cqrs.commands'`          | Channel prefix for commands                           |
| `queryChannelPrefix`   | `string`                      | `'cqrs.queries'`           | Channel prefix for queries                            |
| `eventChannelPrefix`   | `string`                      | `'cqrs.events'`            | Channel prefix for events                             |
| `persistEvents`        | `boolean`                     | `false`                    | Use Events Store instead of Events for the `EventBus` |
| `commandTimeout`       | `number`                      | `10`                       | Command timeout (seconds)                             |
| `queryTimeout`         | `number`                      | `10`                       | Query timeout (seconds)                               |
| `drainTimeoutSeconds`  | `number`                      | `5`                        | Drain timeout on module destroy (seconds)             |
| `channelResolver`      | `(message: object) => string` | `message.constructor.name` | Resolves the channel segment after the prefix         |
| `serializer`           | `KubeMQSerializer`            | `JsonSerializer`           | Outbound message serializer                           |
| `deserializer`         | `KubeMQDeserializer`          | `JsonDeserializer`         | Inbound response deserializer                         |

```typescript title="cqrs.module.ts"
import { Module } from '@nestjs/common';
import { CqrsModule } from '@nestjs/cqrs';
import { KubeMQModule } from '@kubemq/nestjs-transport';
import { KubeMQCqrsModule } from '@kubemq/nestjs-transport/cqrs';

@Module({
  imports: [
    KubeMQModule.forRoot({ address: 'localhost:50000' }),
    CqrsModule,
    KubeMQCqrsModule.forRoot({
      commandChannelPrefix: 'myapp.commands',
      queryChannelPrefix: 'myapp.queries',
      eventChannelPrefix: 'myapp.events',
      persistEvents: true,
      commandTimeout: 10,
      queryTimeout: 10,
    }),
  ],
})
export class AppModule {}
```

<Callout type="warn">
  Import order matters: register `KubeMQCqrsModule.forRoot()` **after** both `CqrsModule` and `KubeMQModule.forRoot()`. The CQRS bridge relies on the connection that `KubeMQModule.forRoot()` provides.
</Callout>

## See Also [#see-also]

<Cards>
  <Card title="API reference" href="/integrations/nestjs/reference/api" description="Module methods, decorators, decorator options, contexts, codecs, constants, and enums." />

  <Card title="Error codes" href="/integrations/nestjs/reference/error-codes" description="The exported error types and the troubleshooting / FAQ table." />

  <Card title="Module configuration" href="/integrations/nestjs/how-to/module-configuration" description="forRoot / register / forFeature wiring with worked examples." />
</Cards>