{"id":11388,"library":"nestjs-minio-client","title":"NestJS Minio Client","description":"The `nestjs-minio-client` package provides a robust integration of the Minio S3-compatible object storage client into the NestJS framework. It offers a `MinioModule` for streamlined configuration and registration, supporting both synchronous `register()` and asynchronous `registerAsync()` methods, which is particularly useful for injecting configuration from NestJS's `@nestjs/config` package. An injectable `MinioService` then provides direct access to the underlying Minio JS SDK client instance, allowing developers to interact with Minio's API. The current stable version is 2.2.0, with a consistent release cadence focusing on updates to dependencies, NestJS compatibility, and internal refactoring. It serves as a dedicated wrapper, simplifying Minio usage within NestJS applications and abstracting away direct SDK initialization. It requires NestJS version 9 or later.","status":"active","version":"2.2.0","language":"javascript","source_language":"en","source_url":"https://github.com/djedlajn/nestjs-minio-client","tags":["javascript","nestjs","minio","minio-client-sdk","nestjs-minio","nestjs-minio-client","typescript"],"install":[{"cmd":"npm install nestjs-minio-client","lang":"bash","label":"npm"},{"cmd":"yarn add nestjs-minio-client","lang":"bash","label":"yarn"},{"cmd":"pnpm add nestjs-minio-client","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Peer dependency for NestJS module functionality.","package":"@nestjs/common","optional":false},{"reason":"Peer dependency for NestJS core functionalities.","package":"@nestjs/core","optional":false}],"imports":[{"note":"Used for registering the Minio module in NestJS applications, typically within an `AppModule` or feature module. ESM syntax is standard for NestJS.","wrong":"const { MinioModule } = require('nestjs-minio-client');","symbol":"MinioModule","correct":"import { MinioModule } from 'nestjs-minio-client';"},{"note":"The injectable service used to interact with the Minio client, providing access to `minioService.client` for SDK operations. Ensure it is provided and exported by its module.","wrong":"const { MinioService } = require('nestjs-minio-client');","symbol":"MinioService","correct":"import { MinioService } from 'nestjs-minio-client';"},{"note":"Synchronous module registration method, suitable for static configurations.","symbol":"MinioModule.register","correct":"MinioModule.register({ /* options */ })"},{"note":"Asynchronous module registration method, essential for injecting dynamic configuration (e.g., from `ConfigService`) at runtime.","symbol":"MinioModule.registerAsync","correct":"MinioModule.registerAsync({ useFactory: ..., inject: [...] })"}],"quickstart":{"code":"import { Module } from '@nestjs/common';\nimport { MinioModule } from 'nestjs-minio-client';\nimport { ConfigModule, ConfigService } from '@nestjs/config';\nimport { MinioClientService } from './minio-client.service'; // Assuming you have a service using MinioService\n\n@Module({\n  imports: [\n    ConfigModule.forRoot(), // Load environment variables\n    MinioModule.registerAsync({\n      imports: [ConfigModule],\n      inject: [ConfigService],\n      useFactory: (config: ConfigService) => {\n        return {\n          endPoint: config.get<string>('MINIO_ENDPOINT') ?? '127.0.0.1',\n          port: parseInt(config.get<string>('MINIO_PORT') ?? '9000', 10),\n          useSSL: config.get<string>('MINIO_USE_SSL') === 'true',\n          accessKey: config.get<string>('MINIO_ACCESS_KEY') ?? process.env.MINIO_ACCESS_KEY ?? '',\n          secretKey: config.get<string>('MINIO_SECRET_KEY') ?? process.env.MINIO_SECRET_KEY ?? ''\n        };\n      },\n    }),\n  ],\n  providers: [MinioClientService],\n  exports: [MinioClientService],\n})\nexport class AppModule {}\n\n// Example minio-client.service.ts\nimport { Injectable } from '@nestjs/common';\nimport { MinioService } from 'nestjs-minio-client';\n\n@Injectable()\nexport class MinioClientService {\n  constructor(private readonly minioService: MinioService) {}\n\n  async listAllBuckets() {\n    return this.minioService.client.listBuckets();\n  }\n\n  // Add more methods for Minio operations here\n  async uploadFile(bucketName: string, objectName: string, filepath: string) {\n    // This is an example, actual Minio client usage would vary\n    // For instance, you might use putObject, fPutObject, etc.\n    console.log(`Uploading ${filepath} to ${bucketName}/${objectName}`);\n    // await this.minioService.client.fPutObject(bucketName, objectName, filepath);\n    return { success: true, objectName };\n  }\n}\n","lang":"typescript","description":"This quickstart demonstrates registering the `MinioModule` asynchronously using `@nestjs/config` to load Minio credentials from environment variables, and then injecting and using `MinioService` in another service to list buckets and simulate a file upload operation."},"warnings":[{"fix":"Review your module registration code and ensure it aligns with the examples provided in the v2.x documentation, especially if upgrading from v1.x.","message":"Version 2.0.0 introduced a refactoring to utilize NestJS's configurable module builder. While the `register()` and `registerAsync()` methods remain, internal implementation details and possibly configuration interfaces were updated.","severity":"breaking","affected_versions":">=2.0.0"},{"fix":"Carefully consider the implications of using `MinioModule.register({ global: true })`. For better architectural clarity and testability, import `MinioModule` into specific feature modules where its services are consumed.","message":"The `global` option, introduced in v1.2.0, allows registering the `MinioModule` in the global namespace. While convenient for smaller applications, using global modules can obscure dependencies and complicate testing in larger NestJS projects. It's generally recommended to import modules explicitly where needed.","severity":"gotcha","affected_versions":">=1.2.0"},{"fix":"Ensure your NestJS project is running version 9.0.0 or higher. Update your `@nestjs/common` and `@nestjs/core` packages if necessary.","message":"This package has a peer dependency on NestJS version 9.0.0 or later. Using it with older NestJS versions may lead to dependency resolution issues or runtime errors due to API incompatibilities.","severity":"breaking","affected_versions":"<9.0.0 (NestJS)"},{"fix":"Consult the official Minio Javascript SDK documentation for specific API calls (e.g., `putObject`, `getObject`, `listBuckets`) and their expected behaviors, parameters, and potential errors. Wrap SDK calls in `try...catch` blocks where appropriate.","message":"The `MinioService` exposes the raw Minio Javascript SDK client via `minioService.client`. Direct interaction with this client requires familiarity with the underlying Minio SDK's API and error handling mechanisms. Ensure proper error handling and async/await usage when calling SDK methods.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Ensure `import { MinioModule } from 'nestjs-minio-client';` is present at the top of your module file (e.g., `app.module.ts`). Verify `nestjs-minio-client` is correctly installed in `node_modules`.","cause":"Attempting to use `MinioModule.register` or `registerAsync` without correctly importing `MinioModule` or due to module resolution issues.","error":"TypeError: MinioModule.register is not a function"},{"fix":"When using `MinioModule.registerAsync` with `ConfigService`, ensure `imports: [ConfigModule]` is included in the `MinioModule.registerAsync` options object, and `ConfigModule.forRoot()` or `ConfigModule.forFeature()` is set up correctly in your application's root module.","cause":"This error typically occurs when `MinioModule.registerAsync` is used with `inject: [ConfigService]` but `ConfigModule` is not imported within the `MinioModule`'s imports array.","error":"Nest can't resolve dependencies of the MinioService (?). Please make sure that the argument ConfigService at index [0] is available in the MinioModule context."},{"fix":"Review the configuration object passed to `MinioModule.register()` or returned by `useFactory` in `MinioModule.registerAsync()`. Ensure `endPoint`, `port`, `accessKey`, and `secretKey` are all provided and correctly formatted.","cause":"The `MinioModule` was registered with incomplete or invalid configuration options.","error":"Error: Minio configuration missing 'endPoint', 'port', 'accessKey', or 'secretKey'."}],"ecosystem":"npm"}