Skip to content

NestJS & @cqrs-ddd: Integrating or Migrating

Teams using NestJS have two architectural choices when adopting @cqrs-ddd:

  1. Keep NestJS and add the adapter @cqrs-ddd/nestjs: Keep your existing @nestjs/cqrs handlers, buses, modules, dependency injection, and controllers. The adapter wraps handlers in behavior pipelines, provides global exception filtering, and manages correlation and job context. Nothing is replaced.
  2. Move to framework-free CQRS with @cqrs-ddd/cqrs: Build applications without NestJS on plain Node.js, Fastify, or Express, constructing handlers with new and registering them on createCqrs(). It covers handlers and buses, not every feature of @nestjs/cqrs: see What Is Not Included.

The two are independent. An existing NestJS application takes the first and never needs the second. An application on the @nestjs-pipeline/* 0.4.x packages starts with From @nestjs-pipeline 0.4.x.

Dimension Raw @nestjs/cqrs NestJS + @cqrs-ddd/nestjs Framework-Free @cqrs-ddd/cqrs
Handler Decorators @CommandHandler, @QueryHandler, @EventsHandler Same @nestjs/cqrs decorators + @UsePipeline, @SkipPipeline Same names, from @cqrs-ddd/cqrs + @UsePipeline, @SkipPipeline
Buses CommandBus, QueryBus, EventBus Same @nestjs/cqrs buses Same bus names, from createCqrs()
Pipeline Behaviors None (requires Nest interceptors) Compiles and executes @cqrs-ddd/pipeline around handlers Compiles and executes @cqrs-ddd/pipeline around handlers
DI & Containers NestJS IoC container NestJS IoC container injects behaviors and handlers No container: explicit new in composition root
Exception Handling Manual exception filters Automatic ErrorFilter mapping package errors to HttpException Framework-neutral: HTTP layer maps errors (e.g. domainErrorHttpStatus)
Startup Diagnostics Silent overrides on duplicates Validates singleton scope, provider uniqueness, behavior contracts Fails on duplicate handlers, missing decorators, contract violations
Runtime NestJS NestJS No framework: the buses and the pipelines only

Option 1: Integrating with NestJS via @cqrs-ddd/nestjs

Section titled “Option 1: Integrating with NestJS via @cqrs-ddd/nestjs”

If you are already running on NestJS or want Nest’s dependency injection and controller ecosystem, install @cqrs-ddd/nestjs.

pnpm add @cqrs-ddd/nestjs @cqrs-ddd/pipeline @cqrs-ddd/core @nestjs/cqrs
  • All @Module(), @Injectable(), @Controller() definitions.
  • Official @nestjs/cqrs imports: CqrsModule, CommandBus, QueryBus, EventBus, @CommandHandler, @QueryHandler, @EventsHandler.
  • Handlers implement ICommandHandler, IQueryHandler, IEventHandler.
  • Controllers inject CommandBus and QueryBus as usual.

Minimal Setup is a complete root module with every import and provider, run by a test. The steps below show its parts.

  1. PipelineModule.forRoot() in AppModule:

    @Module({
      imports: [
        CqrsModule.forRoot(),
        PipelineModule.forRoot({
          sources: { tenantId: tenantSource, correlationId: correlationSource },
          globalBehaviors: [{ scope: 'all', before: [logging()] }],
        }),
      ],
      providers: [
        { provide: APP_FILTER, useClass: ErrorFilter },
        { provide: LoggingBehavior, useFactory: () => new LoggingBehavior(new Logger('Pipeline')) },
      ],
    })
    export class AppModule {}
  2. Pipeline declarations on handlers:

    import { CommandHandler, ICommandHandler } from '@nestjs/cqrs';
    import { UsePipeline, SkipPipeline } from '@cqrs-ddd/pipeline';
    import { idempotent } from '@cqrs-ddd/pipeline-idempotency';
    import { validated } from '@cqrs-ddd/pipeline-zod';
    
    @CommandHandler(CreateInvoiceCommand)
    @UsePipeline(validated(CreateInvoiceSchema), idempotent({ keyFactory }))
    export class CreateInvoiceHandler implements ICommandHandler<CreateInvoiceCommand> {
      async execute(command: CreateInvoiceCommand) {
        // Executed inside the pipeline
      }
    }

    Each behavior a handler names is a provider of a module: here ZodValidationBehavior, and IdempotencyBehavior built with its store.

  3. Domain Event publication: Subclass CommandBaseHandler from @cqrs-ddd/core/application and pass the injected @nestjs/cqrs EventBus. When handle(command) returns an AggregateRoot, uncommitted domain events are automatically published through eventBus.publishAll() and uncommitted. Delivery stays what that EventBus provides: the adapter adds no durable messaging and no outbox.


Option 2: Migrating off NestJS to @cqrs-ddd/cqrs

Section titled “Option 2: Migrating off NestJS to @cqrs-ddd/cqrs”

If your goal is to drop NestJS for a framework-free architecture on plain Node.js, Express or Fastify, use @cqrs-ddd/cqrs.

pnpm add @cqrs-ddd/cqrs @cqrs-ddd/pipeline @cqrs-ddd/core

The handler decorators, the handler interfaces and the bus names match @nestjs/cqrs:

@nestjs/cqrs @cqrs-ddd/cqrs
@CommandHandler(Command) @CommandHandler(Command) from @cqrs-ddd/cqrs
@QueryHandler(Query) @QueryHandler(Query) from @cqrs-ddd/cqrs
@EventsHandler(...Events) @EventsHandler(...Events) from @cqrs-ddd/cqrs
ICommandHandler<TCommand> ICommandHandler<TCommand> from @cqrs-ddd/cqrs
IQueryHandler<TQuery> IQueryHandler<TQuery> from @cqrs-ddd/cqrs
IEventHandler<TEvent> IEventHandler<TEvent> from @cqrs-ddd/cqrs
CommandBus, QueryBus, EventBus Returned by createCqrs()

@cqrs-ddd/cqrs does not replace every feature of @nestjs/cqrs. It has no sagas, no ofType RxJS pipes, no AsyncContext and no EventPublisher merge mechanisms; aggregates publish events through CommandBaseHandler. Its EventBus delivers in process: it is not durable messaging and not an outbox. An application that relies on one of these keeps NestJS and takes Option 1.

NestJS Responsibility @cqrs-ddd Equivalent
@Module(), @Injectable(), providers A plain composition function that constructs dependencies with new
NestFactory.create(AppModule) const cqrs = createCqrs(options); cqrs.register(...handlers);
Application shutdown hooks await cqrs.close(), then closing database pools and redis connections
Controllers, guards, interceptors, pipes Native HTTP routes and middleware; see HTTP with Express and Fastify
Request-scoped providers (Scope.REQUEST) AsyncLocalStorage via context sources (tenantId, correlationId)
import {
  CommandHandler,
  createCqrs,
  type ICommandHandler,
} from '@cqrs-ddd/cqrs';
import { UsePipeline, LoggingBehavior } from '@cqrs-ddd/pipeline';
import { AuditBehavior, type AuditSink, audit } from '@cqrs-ddd/pipeline-audit';

class RegisterUserCommand {
  constructor(readonly email: string) {}
}

@CommandHandler(RegisterUserCommand)
@UsePipeline(audit({ action: 'user.registered' }))
class RegisterUserHandler implements ICommandHandler<RegisterUserCommand> {
  constructor(private readonly users: UsersRepository) {}

  async execute(command: RegisterUserCommand): Promise<string> {
    const user = await this.users.create(command.email);
    return user.id;
  }
}

// Composition Root
export function buildApplication(users: UsersRepository, auditSink: AuditSink) {
  const cqrs = createCqrs({
    behaviors: [new AuditBehavior(auditSink)],
    globalBehaviors: { before: [LoggingBehavior] },
  });

  cqrs.register(new RegisterUserHandler(users));

  return cqrs;
}
  • Strict handler registration: Registering a second handler for the same command or query fails immediately in cqrs.register(). NestJS silently overrides earlier handlers with the last one registered.
  • Async missing handler errors: In @cqrs-ddd/cqrs, commandBus.execute() and queryBus.execute() reject asynchronously with CommandHandlerNotFoundException or QueryHandlerNotFoundException. @nestjs/cqrs throws synchronously.
  • Graceful shutdown: cqrs.close() awaits all running asynchronous event handlers before resolving. In NestJS, app.close() does not track background event handler completion.
  • Event error isolation: As in @nestjs/cqrs, an event handler’s failure goes to the UnhandledExceptionBus and the handler keeps receiving later events; @cqrs-ddd/cqrs also logs it, or rethrows it with rethrowUnhandled: true.
  • Choose Option 1 (@cqrs-ddd/nestjs) when working in an existing NestJS codebase, using NestJS microservices or GraphQL, or relying heavily on Nest’s controller ecosystem and DI modules.
  • Choose Option 2 (@cqrs-ddd/cqrs) when building a new service on plain Node.js, Express or Fastify, or when you want explicit construction without a dependency-injection container and none of the features listed under What Is Not Included.