nestjs-pubnub

An injectable PubNub client for NestJS. PubNubService extends the SDK client, so publishing and subscription APIs remain available.

Install it in your NestJS application:

pnpm add nestjs-pubnub pubnub

Requires Node.js 24 or newer, NestJS 12 and PubNub 13.0.3 or a later 13.x release. Both ESM and CommonJS are supported, including strict consumers that set skipLibCheck: false.

Register

import { Module } from "@nestjs/common";
import { PubNubModule } from "nestjs-pubnub";

@Module({
  imports: [
    PubNubModule.register({
      userId: "notification-service",
      subscribeKey: process.env.PUBNUB_SUBSCRIBE_KEY!,
      publishKey: process.env.PUBNUB_PUBLISH_KEY!,
    }),
  ],
})
export class NotificationsModule {}

Set both key environment variables before starting the application. Use a stable userId appropriate to the identity of your application.

Configure asynchronously

With @nestjs/config installed, place this in your module's imports:

import { ConfigModule, ConfigService } from "@nestjs/config";
import { PubNubModule } from "nestjs-pubnub";

PubNubModule.registerAsync({
  imports: [ConfigModule.forRoot()],
  inject: [ConfigService],
  useFactory: (config: ConfigService) => ({
    userId: config.getOrThrow<string>("PUBNUB_USER_ID"),
    subscribeKey: config.getOrThrow<string>("PUBNUB_SUBSCRIBE_KEY"),
    publishKey: config.getOrThrow<string>("PUBNUB_PUBLISH_KEY"),
  }),
});

Multiple clients

Give each registration a unique alias and inject the matching client. alias and global are Nest module settings: place them beside useFactory for async registration, not inside its returned PubNub SDK configuration. For synchronous registration, include them alongside the SDK options in the same object.

import { Inject, Injectable, Module } from "@nestjs/common";
import {
  getPubNubClientToken,
  PubNubModule,
  PubNubService,
} from "nestjs-pubnub";

@Injectable()
class AccountNotifications {
  constructor(
    @Inject(getPubNubClientToken("primary")) readonly primary: PubNubService,
    @Inject(getPubNubClientToken("secondary"))
    readonly secondary: PubNubService,
  ) {}
}

@Module({
  imports: [
    PubNubModule.register({
      alias: "primary",
      userId: "primary-notifications",
      subscribeKey: process.env.PRIMARY_SUBSCRIBE_KEY!,
      publishKey: process.env.PRIMARY_PUBLISH_KEY!,
    }),
    PubNubModule.registerAsync({
      alias: "secondary",
      useFactory: () => ({
        userId: "secondary-notifications",
        subscribeKey: process.env.SECONDARY_SUBSCRIBE_KEY!,
        publishKey: process.env.SECONDARY_PUBLISH_KEY!,
      }),
    }),
  ],
  providers: [AccountNotifications],
})
export class MultiAccountModule {}

Each registration owns its SDK configuration, client and shutdown hook. SDK options such as origin remain available per registration. getPubNubClientToken(alias) supports custom provider factories and testing. Named registrations export only their named token; omit alias (or use "" or the reserved "default" alias) to retain ordinary PubNubService injection. Other aliases are exact, opaque names; use a unique name for each registration. The module stays local unless global: true is requested.

Major release note

Package-specific injection decorators have been removed; use Nest's @Inject(getPubNubClientToken(alias)). Existing single-client PubNubService injection continues to work. Applications registering multiple clients should assign distinct aliases and use @Inject(getPubNubClientToken(alias)) instead of relying on import order to select a class provider.

Publish a message

Register this service in the module that imports PubNubModule:

import { Injectable } from "@nestjs/common";
import { PubNubService } from "nestjs-pubnub";

@Injectable()
export class NotificationsService {
  constructor(private readonly pubnub: PubNubService) {}

  notify(channel: string, text: string) {
    return this.pubnub.publish({ channel, message: { text } });
  }
}

The module closes its SDK client on destruction. Call app.enableShutdownHooks() during Nest bootstrap if shutdown signals should trigger that lifecycle hook.

Module options token

getPubNubOptionsToken() returns the module-local configuration token for custom providers inside a registration. It takes no alias: each registration owns its options provider. The options provider is not exported to parent or importing modules; use this helper only for providers added inside that registration or for registration-local tests. The generated builder token is private and is not exported from the package entry point.

Contributing