Mofajjal Rasul

Posted on Nov 3, 2024 • Edited on Apr 5

Integrating Cloudinary with NestJS for Image Management

#nestjs #cloudinary #imageupload #backend

This technical walkthrough demonstrates the implementation of Cloudinary media management within NestJS applications through structured provider configuration and service decomposition. The implementation emphasizes production-ready error handling, metadata tracking, and resource optimization.

1. Cloudinary Provider Configuration

The foundational CloudinaryProvider establishes secure API connectivity between your NestJS application and Cloudinary services:

import { Provider } from "@nestjs/common";
import { ConfigService } from "@nestjs/config";
import { v2 as CloudinaryAPI } from "cloudinary";

export const CLOUDINARY = "CLOUDINARY";

export const CloudinaryProvider: Provider = {
  provide: CLOUDINARY,
  useFactory: (configService: ConfigService) => {
    return CloudinaryAPI.config({
      cloud_name: configService.get<string>("CLD_CLOUD_NAME"),
      api_key: configService.get<string>("CLD_API_KEY"),
      api_secret: configService.get<string>("CLD_API_SECRET"),
    });
  },
  inject: [ConfigService],
};

Implementation Notes

Securely retrieves Cloudinary credentials from environment variables using NestJS's ConfigService
Exports a reusable provider token (CLOUDINARY) for dependency injection

2. Core Service Architecture

The ImageMetaService scaffold provides infrastructure for media operations:

import {
  BadRequestException,
  HttpException,
  Injectable,
  InternalServerErrorException,
  Logger,
} from "@nestjs/common";
import { ImageMetaRepository } from "./image-meta.repository";

@Injectable()
export class ImageMetaService {
  private readonly logger: Logger = new Logger(ImageMetaService.name);

  constructor(private readonly imageMetaRepository: ImageMetaRepository) {}
}

Structural Components

@Injectable() decorator enables dependency injection across modules
Integrated logger facilitates operational monitoring and debugging

3. Single Image Upload Implementation

The createSingleImage method orchestrates secure file uploads with metadata persistence:

async createSingleImage(singleImageFile: Express.Multer.File, ownerId: string): Promise<ImageMetaDocument> {
  try {
    if (!singleImageFile) {
      throw new BadRequestException("No image file provided");
    }

    const extension = this.getFileExtension(singleImageFile.originalname);
    const uploadResult = await this.uploadImageToCloudinary(singleImageFile);

    const singleImage = await this.imageMetaRepository.create({
      url: uploadResult.secure_url,
      name: uploadResult.public_id,
      extension: extension,
      size: singleImageFile.size,
      mimeType: singleImageFile.mimetype,
      ownerId: ownerId,
    });

    return singleImage;
  } catch (error) {
    this.logger.error(`Error creating single image:`, error);
    if (error instanceof HttpException) {
      throw error;
    } else {
      throw new InternalServerErrorException("Failed to create single image");
    }
  }
}

Operational Workflow

Validates input file existence
Extracts file extension using utility method
Executes Cloudinary upload via dedicated stream handler
Persists metadata including security-enhanced URL and ownership details

4. Batch Image Processing

The createMultipleImages method extends functionality for concurrent uploads:

async createMultipleImages(multipleImageFiles: Express.Multer.File[], ownerId: string): Promise<ImageMetaDocument[]> {
  try {
    if (!multipleImageFiles || multipleImageFiles.length === 0) {
      throw new BadRequestException("No image files provided");
    }

    const multipleImages = await Promise.all(
      multipleImageFiles.map(async (image) => await this.createSingleImage(image, ownerId)),
    );

    return multipleImages;
  } catch (error) {
    this.logger.error(`Error creating multiple images:`, error);
    if (error instanceof HttpException) {
      throw error;
    } else {
      throw new InternalServerErrorException("Failed to create multiple images");
    }
  }
}

Concurrency Management

Leverages Promise.all for parallel processing while maintaining individual transaction integrity
Inherits error handling patterns from single upload implementation

5. Resource Deletion Protocol

The removeImage method ensures coordinated resource removal:

async removeImage(imageId: string, ownerId: string): Promise<ImageMetaDocument | null> {
  try {
    const deletedImage = await this.imageMetaRepository.getOneWhere({
      _id: imageId,
      ownerId: ownerId,
    });

    if (!deletedImage) {
      throw new Error(`Could not find image with id: ${imageId}`);
    }

    await this.deleteImageFromCloudinary(deletedImage.name);
    await this.imageMetaRepository.removeOneById(imageId);

    return deletedImage;
  } catch (error) {
    if (error instanceof HttpException) throw error;

    this.logger.error(`Error deleting image:`, error);
    throw new InternalServerErrorException("Could not delete image");
  }
}

Deletion Sequence

Verification of resource ownership
Atomic deletion from Cloudinary storage
Metadata removal from persistent storage

6. Cloudinary Stream Management

The uploadImageToCloudinary method implements efficient stream-based uploads:

async uploadImageToCloudinary(file: Express.Multer.File): Promise<UploadApiResponse> {
  return new Promise<UploadApiResponse>((resolve, reject) => {
    const uploadStream = CloudinaryAPI.uploader.upload_stream(
      (error: UploadApiErrorResponse | undefined, result: UploadApiResponse | undefined) => {
        if (error) {
          this.logger.error(`Failed to upload image to Cloudinary`, error);
          reject(error);
        } else if (!result) {
          const errorMessage = "Upload result is undefined";
          this.logger.error(`Failed to upload image to Cloudinary: ${errorMessage}`);
          reject(new Error(errorMessage));
        } else {
          resolve(result);
        }
      },
    );

    const stream = toStream(file.buffer);
    stream.pipe(uploadStream);
  });
}

Stream Handling

Implements Promise wrapper for asynchronous operation management
Utilizes Node.js stream piping for memory-efficient uploads

7. Media Module Composition

The ImageMetaModule aggregates service components:

import { Global, Module } from "@nestjs/common";
import { CloudinaryProvider } from "../../utility/provider/cloudinary.provider";
import { ImageMetaService } from "./image-meta.service";

@Global()
@Module({
  imports: [],
  providers: [ImageMetaService, CloudinaryProvider],
  exports: [ImageMetaService],
})
export class ImageMetaModule {}

Architectural Considerations

@Global() decorator enables cross-module service availability
Explicit exports ensure maintainable dependency chains

Conclusion

This implementation demonstrates robust media management capabilities through Cloudinary integration in NestJS, featuring:

Secure credential handling via environment variables
Atomic transaction patterns for upload/delete operations
Comprehensive error logging and handling
Stream-optimized file processing

The modular structure facilitates seamless extension for additional cloud storage providers or enhanced metadata tracking requirements, providing a enterprise-ready foundation for media-intensive applications.

DEV Community