Installation

Install the Package

Install @nestbolt/medialibrary using your preferred package manager:

npm install @nestbolt/medialibrary

yarn add @nestbolt/medialibrary

pnpm add @nestbolt/medialibrary

Peer Dependencies

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

Package	Required Version	Purpose
`@nestjs/common`	`^10.0.0 \|\| ^11.0.0`	NestJS core decorators and utilities
`@nestjs/core`	`^10.0.0 \|\| ^11.0.0`	NestJS application core
`@nestjs/typeorm`	`^10.0.0 \|\| ^11.0.0`	TypeORM integration for NestJS
`typeorm`	`^0.3.0`	ORM used for the `media` table
`reflect-metadata`	`^0.1.13 \|\| ^0.2.0`	Metadata reflection for decorators

Install any missing peer dependencies:

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

Optional Dependencies

These packages are only needed if you use specific features. The library will throw a descriptive error at runtime if a feature is used without its corresponding dependency.

Required if you use @RegisterMediaConversions or call regenerateConversions(). Sharp is the image processing engine behind all conversion operations (resize, crop, format, quality, blur, sharpen, etc.).

npm install sharp

Minimum supported version: >=0.32.0

AWS SDK (S3 Storage)

Required if you configure any disk with driver: "s3". The S3 driver uses AWS SDK v3.

npm install @aws-sdk/client-s3

If you also need presigned temporary URLs (via getTemporaryUrl()):

npm install @aws-sdk/s3-request-presigner

Minimum supported version for both packages: ^3.0.0

Event Emitter (Lifecycle Events)

Required if you want to listen to media lifecycle events such as media.added, media.deleted, or media.conversion-completed.

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 {}

Database Setup

The MediaEntity is a TypeORM entity that maps to a media table. When you configure TypeORM with synchronize: true (development only), the table is created automatically. For production, generate a migration:

npx typeorm migration:generate -n CreateMediaTable

The media table has the following columns:

Column	Type	Description
`id`	`uuid` (PK)	Primary key
`model_type`	`varchar(255)`	Entity type name (e.g., `"Post"`)
`model_id`	`varchar(255)`	Entity ID
`uuid`	`varchar(36)`	Unique identifier
`collection_name`	`varchar(255)`	Collection name (default: `"default"`)
`name`	`varchar(255)`	Display name
`file_name`	`varchar(255)`	Storage file name
`mime_type`	`varchar(255)`	MIME type
`disk`	`varchar(255)`	Storage disk name
`conversions_disk`	`varchar(255)`	Disk for conversions (nullable)
`size`	`bigint`	File size in bytes
`manipulations`	`json`	Applied manipulations
`custom_properties`	`json`	User-defined metadata
`generated_conversions`	`json`	Map of conversion names to completion status
`responsive_images`	`json`	Responsive image data
`order_column`	`int`	Sort order (nullable)
`created_at`	`timestamp`	Creation timestamp
`updated_at`	`timestamp`	Last update timestamp

An index is automatically created on (model_type, model_id) for efficient lookups, and a separate index on order_column.

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 { MediaModule } from "@nestbolt/medialibrary";

@Module({
  imports: [
    TypeOrmModule.forRoot({
      type: "postgres",
      // ... your database config
      synchronize: true, // development only
    }),
    MediaModule.forRoot({
      defaultDisk: "local",
      disks: {
        local: {
          driver: "local",
          root: "./uploads",
          urlBase: "/media",
        },
      },
    }),
  ],
})
export class AppModule {}

If the application starts without errors, the installation is complete. Continue to the Quick Start guide to upload your first file.