Installation

Install the Package

Install @nestbolt/settings using your preferred package manager:

npm install @nestbolt/settings

yarn add @nestbolt/settings

pnpm add @nestbolt/settings

Peer Dependencies

The following packages are required peer dependencies. In a typical NestJS project, most of these are already installed:

Install any missing peer dependencies:

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

Database Setup

@nestbolt/settings ships a single TypeORM entity, SettingEntity, that backs the key-value store. Register it with your TypeORM connection so the table is created (or included in your migration generator):

import { TypeOrmModule } from "@nestjs/typeorm";
import { SettingEntity } from "@nestbolt/settings";

TypeOrmModule.forRoot({
  type: "postgres",
  // ... your database config
  entities: [SettingEntity /* , ...your other entities */],
  synchronize: true, // development only
});

Or, when using autoLoadEntities, the SettingsModule registers SettingEntity via TypeOrmModule.forFeature([SettingEntity]) automatically, so it's picked up without extra wiring:

TypeOrmModule.forRoot({
  type: "postgres",
  // ... your database config
  autoLoadEntities: true,
});

The schema:

The key column has a UNIQUE constraint, which is what makes set() race-safe: concurrent setters with the same key collapse into a single upsert via INSERT ... ON CONFLICT(key) DO UPDATE.

Optional Dependencies

Event Emitter (Lifecycle Events)

Required if you want to listen to settings.created, settings.updated, and settings.deleted.

npm install @nestjs/event-emitter

Supported versions: ^2.0.0 || ^3.0.0

You also need to register the EventEmitterModule in your application:

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

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

If @nestjs/event-emitter is not installed or EventEmitterModule is not registered, the package works normally but no events are emitted. The event emitter is resolved as an optional dependency.

Verifying the Installation

After installing, verify everything is wired correctly by importing the module in your root AppModule:

import { Module } from "@nestjs/common";
import { TypeOrmModule } from "@nestjs/typeorm";
import { SettingsModule } from "@nestbolt/settings";

@Module({
  imports: [
    TypeOrmModule.forRoot({
      type: "postgres",
      // ... your database config
      autoLoadEntities: true,
      synchronize: true, // development only
    }),
    SettingsModule.forRoot(),
  ],
})
export class AppModule {}

If the application starts without errors and you see SettingsService initialized in the logs, the installation is complete. Continue to the Quick Start guide to write and read your first setting.