NestJS MinIO Backend

A powerful and flexible NestJS module for integrating MinIO object storage into your NestJS applications. This package provides a seamless way to interact with MinIO, an open-source object storage service compatible with Amazon S3.

Table of Contents

• Features
• Installation
• Requirements
• Quick Start
• Configuration
• API Reference
• Contributing
• License
• Support

Features

• 🚀 Easy integration with NestJS applications
• 🎯 Powerful decorators for blazing-fast implementation
  • @FileUpload() - Handles multiple file uploads with built-in validation
  • @FileField() - Swagger-ready DTO field decorator
  • @FileSchemaField() - Mongoose schema integration for file fields
• 📁 Complete MinIO operations support (upload, download, delete, etc.)
• 🔧 Configurable module options
• 🎯 TypeScript support
• 📝 Swagger documentation support
• 🔄 RxJS integration

Installation

1npm install nestjs-minio-backend

Requirements

• Node.js >= 20.15.0
• NestJS >= 11.0.0
• MinIO Server (running instance)

Peer Dependencies

This module requires the following peer dependencies:

1{
2  "@nestjs/common": "^11.0.12",
3  "@nestjs/core": "^11.0.12",
4  "minio": "^8.0.5",
5  "rxjs": "^7.8.2",
6  "@nestjs/mongoose": "^11.0.2",
7  "@nestjs/platform-express": "^11.0.12",
8  "@nestjs/swagger": "^11.0.7",
9  "class-validator": "^0.14.1"
10}

Quick Start (Using Decorators)

1. First, set up your MinIO configuration:

Create a config/minio.config.ts file:

1import { registerAs } from '@nestjs/config';
2
3export default registerAs('minio', () => ({
4  endPoint: process.env.MINIO_ENDPOINT || 'localhost',
5  externalEndPoint:
6    process.env.MINIO_EXTERNAL_ENDPOINT ||
7    process.env.MINIO_ENDPOINT ||
8    'localhost',
9  port: parseInt(process.env.MINIO_PORT || '9000', 10),
10  useSSL: process.env.MINIO_USE_HTTPS === 'true',
11  externalUseSSL: process.env.MINIO_EXTERNAL_ENDPOINT_USE_HTTPS === 'true',
12  accessKey: process.env.MINIO_ACCESS_KEY || 'minioadmin',
13  secretKey: process.env.MINIO_SECRET_KEY || 'minioadmin',
14  urlExpiryHours: parseInt(process.env.MINIO_URL_EXPIRY_HOURS || '2', 10),
15  buckets: {
16    private: [
17      process.env.MINIO_MEDIA_FILES_BUCKET || 'media-files-bucket',
18      process.env.MINIO_CHAIN_ICONS_BUCKET || 'chain-icons',
19    ],
20    public: [process.env.MINIO_STATIC_FILES_BUCKET || 'static-files-bucket'],
21  },
22  region: process.env.MINIO_REGION,
23}));

Create a .env file in your project root:

1MINIO_ENDPOINT=your-minio-endpoint
2MINIO_PORT=9000
3MINIO_USE_HTTPS=false
4MINIO_ACCESS_KEY=your-access-key
5MINIO_SECRET_KEY=your-secret-key
6MINIO_MEDIA_FILES_BUCKET=media-files-bucket
7MINIO_STATIC_FILES_BUCKET=static-files-bucket
8MINIO_URL_EXPIRY_HOURS=2

Then, in your app.module.ts:

1import { Module } from '@nestjs/common';
2import { ConfigModule, ConfigService } from '@nestjs/config';
3import { MinioModule } from 'nestjs-minio-backend';
4import minioConfig from './config/minio.config';
5
6@Module({
7  imports: [
8    ConfigModule.forRoot({
9      load: [minioConfig],
10    }),
11    MinioModule.forRootAsync({
12      inject: [ConfigService],
13      useFactory: (configService: ConfigService) => configService.get('minio'),
14    }),
15  ],
16})
17export class AppModule {}

This configuration approach provides:

• 🔐 Environment-based configuration
• 🎯 Type-safe configuration using TypeScript
• 🔄 Default values for local development
• 📁 Organized bucket management
• 🌐 Support for different endpoints (internal/external)

2. Create your DTO with file field:

1import { FileField } from 'nestjs-minio-backend';
2
3export class CreateUserDto {
4  @FileField({
5    bucketName: 'profiles',
6    required: true,
7    description: 'User profile picture'
8  })
9  profilePicture: Express.Multer.File;
10}

3. Use the FileUpload decorator in your controller:

1import { FileUpload } from 'nestjs-minio-backend';
2import { CreateUserDto } from './dto/create-user.dto';
3
4@Controller('users')
5export class UserController {
6  @Post()
7  @FileUpload([
8    { name: 'profilePicture', bucketName: 'profiles', required: true }
9  ])
10  async createUser(@Body() createUserDto: CreateUserDto) {
11    // The file is automatically uploaded to MinIO
12    // You can access the file URL from the DTO
13    return createUserDto;
14  }
15
16  @Post('multiple')
17  @FileUpload([
18    { name: 'documents', bucketName: 'docs', maxCount: 3 }
19  ])
20  async uploadMultiple(@UploadedFiles() files: Array<Express.Multer.File>) {
21    return files; // Files are automatically uploaded to MinIO
22  }
23}

4. (Optional) Add file fields to your Mongoose schema:

1import { FileSchemaField } from 'nestjs-minio-backend';
2
3@Schema()
4export class User {
5  @FileSchemaField({
6    bucketName: 'profiles',
7    required: true
8  })
9  avatar: string; // Automatically stores the MinIO object URL
10}

These decorators provide:

• 🚀 Zero-configuration file uploads
• 📝 Automatic Swagger documentation
• ✅ Built-in validation
• 🔄 Seamless MongoDB integration
• 🎯 Type safety with TypeScript

Configuration

The module accepts the following configuration options:

1interface IMinioModuleOptions {
2  // Required options
3  endPoint: string;          // MinIO server endpoint
4  port: number;             // MinIO server port
5  useSSL: boolean;          // Whether to use SSL for connection
6  accessKey: string;        // MinIO access key
7  secretKey: string;        // MinIO secret key
8  urlExpiryHours: number;   // Expiry time for signed URLs in hours
9
10  // Optional options
11  region?: string;          // MinIO region
12  externalEndPoint?: string; // External endpoint for public access
13  externalUseSSL?: boolean; // Whether to use SSL for external endpoint
14
15  // Bucket configuration
16  buckets: {
17    private: string[];      // Array of private bucket names
18    public: string[];       // Array of public bucket names
19  };
20}

Configuration Example

1const minioConfig: IMinioModuleOptions = {
2  endPoint: 'minio.example.com',
3  port: 9000,
4  useSSL: false,
5  accessKey: 'your-access-key',
6  secretKey: 'your-secret-key',
7  urlExpiryHours: 2,
8  
9  // Optional settings
10  region: 'us-east-1',
11  externalEndPoint: 'public.minio.example.com',
12  externalUseSSL: true,
13  
14  // Bucket configuration
15  buckets: {
16    private: [
17      'media-files-bucket',
18      'user-uploads'
19    ],
20    public: [
21      'static-files-bucket',
22      'public-assets'
23    ]
24  }
25};

Environment Variables Example

1# Required settings
2MINIO_ENDPOINT=minio.example.com
3MINIO_PORT=9000
4MINIO_USE_HTTPS=false
5MINIO_ACCESS_KEY=your-access-key
6MINIO_SECRET_KEY=your-secret-key
7MINIO_URL_EXPIRY_HOURS=2
8
9# Optional settings
10MINIO_REGION=us-east-1
11MINIO_EXTERNAL_ENDPOINT=public.minio.example.com
12MINIO_EXTERNAL_ENDPOINT_USE_HTTPS=true
13
14# Bucket configuration
15MINIO_MEDIA_FILES_BUCKET=media-files-bucket
16MINIO_STATIC_FILES_BUCKET=static-files-bucket

Key Features of the Configuration

• 🔐 Dual Endpoint Support: Configure both internal and external endpoints for flexible access
• 🌐 SSL Configuration: Separate SSL settings for internal and external endpoints
• ⏱️ URL Expiry: Configure signed URL expiration time
• 📁 Bucket Organization: Separate configuration for private and public buckets
• 🔄 Default Values: Sensible defaults for local development
• 🛡️ Type Safety: Full TypeScript support with interface definitions

Manual Implementation (Without Decorators)

If you prefer more control over the file handling process, you can use the MinioService directly:

1import { MinioService } from 'nestjs-minio-backend';
2
3@Injectable()
4export class YourService {
5  constructor(private readonly minioService: MinioService) {}
6
7  async uploadFile(file: Express.Multer.File) {
8    const bucketName = 'your-bucket';
9    const objectName = `${Date.now()}-${file.originalname}`;
10    
11    await this.minioService.upload(bucketName, objectName, file.buffer);
12    return { objectName };
13  }
14}

Manual File Upload Example

1@Post('upload')
2@UseInterceptors(FileInterceptor('file'))
3async uploadFile(@UploadedFile() file: Express.Multer.File) {
4  const bucketName = 'my-bucket';
5  const objectName = `${Date.now()}-${file.originalname}`;
6  
7  await this.minioService.upload(bucketName, objectName, file.buffer);
8  
9  return {
10    message: 'File uploaded successfully',
11    objectName,
12  };
13}

Manual File Download Example

1@Get('download/:objectName')
2async downloadFile(@Param('objectName') objectName: string, @Res() res: Response) {
3  const bucketName = 'my-bucket';
4  const fileBuffer = await this.minioService.download(bucketName, objectName);
5  
6  res.send(fileBuffer);
7}

API Reference

Decorators

@FileUpload()

Handles file uploads with automatic MinIO integration.

1@FileUpload([
2  { 
3    name: string,           // Field name in the request
4    bucketName: string,     // MinIO bucket name
5    required?: boolean,     // Whether the file is required
6    maxCount?: number,      // Maximum number of files
7    maxSize?: number,       // Maximum file size in bytes
8    mimeTypes?: string[]    // Allowed MIME types
9  }
10])

@FileField()

Swagger-ready DTO field decorator for file uploads.

1@FileField({
2  bucketName: string,       // MinIO bucket name
3  required?: boolean,       // Whether the field is required
4  description?: string      // Swagger description
5})

@FileSchemaField()

Mongoose schema integration for file fields.

1@FileSchemaField({
2  bucketName: string,       // MinIO bucket name
3  required?: boolean        // Whether the field is required
4})

Contributing

1. Fork it (https://github.com/UtilKit/nestjs-minio-backend/fork)
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -am 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Create a new Pull Request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Author

Mishhub

Support

• 📫 GitHub Issues
• 💬 Discord Community
• 📧 Email: support@example.com