Installation

Install @nestbolt/audit-log and configure peer dependencies for your NestJS application.

Install the Package

Install @nestbolt/audit-log using your preferred package manager:

npm install @nestbolt/audit-log

Or with yarn:

yarn add @nestbolt/audit-log

Or with pnpm:

pnpm add @nestbolt/audit-log

Peer Dependencies

The package requires the following peer dependencies, which are typically already present in a NestJS + TypeORM 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

Event Emitter

If you want the module to emit events after each audit log entry is created, 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 present, every audit log write will emit an audit.logged event. See the Events page for details.

The module stores audit logs in a database table called audit_logs. TypeORM must be configured to recognize the AuditLogEntity. The module handles this automatically when you call AuditLogModule.forRoot() -- it internally registers TypeOrmModule.forFeature([AuditLogEntity]).

However, your TypeORM connection must be configured to synchronize or run migrations so the audit_logs table is created. There are two approaches:

Option 1: Synchronize (Development)

Enable synchronize in your TypeORM configuration so the table is created automatically:

TypeOrmModule.forRoot({
  type: "postgres",
  host: "localhost",
  port: 5432,
  database: "myapp",
  username: "postgres",
  password: "postgres",
  autoLoadEntities: true,
  synchronize: true, // Creates tables automatically -- do NOT use in production
});

Option 2: Migrations (Production)

For production, generate and run a migration that creates the audit_logs table. The table schema is:

CREATE TABLE audit_logs (
  id UUID PRIMARY KEY DEFAULT uuid_generate_v4(),
  action VARCHAR(50) NOT NULL,
  entity_type VARCHAR(255) NOT NULL,
  entity_id VARCHAR(255) NOT NULL,
  actor_type VARCHAR(255),
  actor_id VARCHAR(255),
  old_values JSON,
  new_values JSON,
  metadata JSON,
  ip_address VARCHAR(45),
  user_agent VARCHAR(512),
  created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

CREATE INDEX idx_audit_logs_entity ON audit_logs (entity_type, entity_id);
CREATE INDEX idx_audit_logs_actor ON audit_logs (actor_type, actor_id);
CREATE INDEX idx_audit_logs_action ON audit_logs (action);
CREATE INDEX idx_audit_logs_created_at ON audit_logs (created_at);

Alternatively, use TypeORM's migration generation with autoLoadEntities: true to generate the migration automatically:

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

Verify Installation

After installing and configuring, import AuditLogModule in your root module to verify everything is wired up:

import { Module } from "@nestjs/common";
import { TypeOrmModule } from "@nestjs/typeorm";
import { AuditLogModule } from "@nestbolt/audit-log";

@Module({
  imports: [
    TypeOrmModule.forRoot({
      // ... your database config
      autoLoadEntities: true,
    }),
    AuditLogModule.forRoot(),
  ],
})
export class AppModule {}

If the application starts without errors, the module is correctly installed and the audit_logs table will be created (when using synchronize: true) or is expected to exist (when using migrations).

Next Steps

Quick Start -- set up your first auditable entity and see audit logs in action.