Installation

Install @nestbolt/notifications and its required and optional peer dependencies.

Install the Package

Install @nestbolt/notifications using your preferred package manager:

npm install @nestbolt/notifications

yarn add @nestbolt/notifications

pnpm add @nestbolt/notifications

Peer Dependencies

The package requires the following peer dependencies, which are typically already present in a NestJS project:

Package	Version
`@nestjs/common`	`^10.0.0 \|\| ^11.0.0`
`@nestjs/core`	`^10.0.0 \|\| ^11.0.0`
`@nestjs/typeorm`	`^10.0.0 \|\| ^11.0.0`
`typeorm`	`^0.3.0`
`reflect-metadata`	`^0.1.13 \|\| ^0.2.0`

If any of these are missing, install them:

npm install @nestjs/common @nestjs/core @nestjs/typeorm typeorm reflect-metadata

Optional Dependencies

nodemailer (for the mail channel)

If you plan to send email notifications, install nodemailer:

npm install nodemailer

npm install -D @types/nodemailer

The mail channel will throw a clear error at runtime if nodemailer is not installed and you attempt to use it.

@nestjs/event-emitter (for lifecycle events)

If you want to listen to notification lifecycle events (notification.sending, notification.sent, notification.failed, notification.read, notification.all-read), install @nestjs/event-emitter:

npm install @nestjs/event-emitter

Then register the EventEmitterModule in your application:

import { EventEmitterModule } from "@nestjs/event-emitter";

@Module({
  imports: [
    EventEmitterModule.forRoot(),
    // ... other imports
  ],
})
export class AppModule {}

When @nestjs/event-emitter is not installed, the notification system works normally -- events are simply not emitted.

Database Setup

The package uses TypeORM and automatically registers the NotificationEntity when you import the module. TypeORM will create the notifications table based on the entity definition.

If you are using TypeORM's synchronize: true option (common in development), the table is created automatically. For production, you should generate and run a migration:

npx typeorm migration:generate -n CreateNotificationsTable
npx typeorm migration:run

The notifications table has the following schema:

Column	Type	Nullable	Description
`id`	`uuid`	No	Primary key (auto-generated)
`type`	`varchar(255)`	No	Notification class name
`notifiable_type`	`varchar(255)`	No	Entity type (e.g., `"User"`)
`notifiable_id`	`varchar(255)`	No	Entity ID
`channel`	`varchar(255)`	No	Channel name (e.g., `"database"`)
`data`	`simple-json`	No	JSON notification payload
`read_at`	`datetime`	Yes	When marked as read
`created_at`	`datetime`	No	Created timestamp
`updated_at`	`datetime`	No	Updated timestamp

The table includes composite indexes on (notifiable_type, notifiable_id) and (notifiable_type, notifiable_id, read_at) for efficient querying.

Verifying the Installation

After installation, verify that the module can be imported without errors:

import {
  NotificationModule,
  NotificationService,
  Notification,
  MailMessage,
  Notifiable,
  NotifiableMixin,
} from "@nestbolt/notifications";

If this compiles without errors, you are ready to proceed to Quick Start.