Registry / http-networking / nestjs-minio-client

nestjs-minio-client

library2.2.0jsnpmunverified

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.

http-networking web-framework aws

npm install nestjs-minio-client

github ↗package ↗

INSTALL

IMPORT

SIG · NESTJS-MINIO-CLIEN

nestjs-minio-client

http-networkingjavascriptv2.2.0

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

MinioModule

✓ import { MinioModule } from 'nestjs-minio-client';

✗ const { MinioModule } = require('nestjs-minio-client');

Used for registering the Minio module in NestJS applications, typically within an `AppModule` or feature module. ESM syntax is standard for NestJS.

MinioService

✓ import { MinioService } from 'nestjs-minio-client';

✗ const { MinioService } = require('nestjs-minio-client');

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.

MinioModule.register

✓ MinioModule.register({ /* options */ })

Synchronous module registration method, suitable for static configurations.

MinioModule.registerAsync

✓ MinioModule.registerAsync({ useFactory: ..., inject: [...] })

Asynchronous module registration method, essential for injecting dynamic configuration (e.g., from `ConfigService`) at runtime.

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.

import { Module } from '@nestjs/common'; import { MinioModule } from 'nestjs-minio-client'; import { ConfigModule, ConfigService } from '@nestjs/config'; import { MinioClientService } from './minio-client.service'; // Assuming you have a service using MinioService @Module({ imports: [ ConfigModule.forRoot(), // Load environment variables MinioModule.registerAsync({ imports: [ConfigModule], inject: [ConfigService], useFactory: (config: ConfigService) => { return { endPoint: config.get<string>('MINIO_ENDPOINT') ?? '127.0.0.1', port: parseInt(config.get<string>('MINIO_PORT') ?? '9000', 10), useSSL: config.get<string>('MINIO_USE_SSL') === 'true', accessKey: config.get<string>('MINIO_ACCESS_KEY') ?? process.env.MINIO_ACCESS_KEY ?? '', secretKey: config.get<string>('MINIO_SECRET_KEY') ?? process.env.MINIO_SECRET_KEY ?? '' }; }, }), ], providers: [MinioClientService], exports: [MinioClientService], }) export class AppModule {} // Example minio-client.service.ts import { Injectable } from '@nestjs/common'; import { MinioService } from 'nestjs-minio-client'; @Injectable() export class MinioClientService { constructor(private readonly minioService: MinioService) {} async listAllBuckets() { return this.minioService.client.listBuckets(); } // Add more methods for Minio operations here async uploadFile(bucketName: string, objectName: string, filepath: string) { // This is an example, actual Minio client usage would vary // For instance, you might use putObject, fPutObject, etc. console.log(`Uploading ${filepath} to ${bucketName}/${objectName}`); // await this.minioService.client.fPutObject(bucketName, objectName, filepath); return { success: true, objectName }; } }

Debug

Known issues

breakingVersion 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.

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.

affects: >=2.0.0

gotchaThe `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.

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.

affects: >=1.2.0

breakingThis 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.

fix

Ensure your NestJS project is running version 9.0.0 or higher. Update your `@nestjs/common` and `@nestjs/core` packages if necessary.

affects: <9.0.0 (NestJS)

gotchaThe `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.

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.

affects: >=1.0.0

Errors

Common errors & fixes

TypeError: MinioModule.register is not a function

Attempting to use `MinioModule.register` or `registerAsync` without correctly importing `MinioModule` or due to module resolution issues.

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`.

Nest can't resolve dependencies of the MinioService (?). Please make sure that the argument ConfigService at index [0] is available in the MinioModule context.

This error typically occurs when `MinioModule.registerAsync` is used with `inject: [ConfigService]` but `ConfigModule` is not imported within the `MinioModule`'s imports array.

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.

Error: Minio configuration missing 'endPoint', 'port', 'accessKey', or 'secretKey'.

The `MinioModule` was registered with incomplete or invalid configuration options.

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.

Upgrade

Version history

2.2.0latest on npm

Audit

Dependencies

@nestjs/commonrequiredPeer dependency for NestJS module functionality.

@nestjs/corerequiredPeer dependency for NestJS core functionalities.

Agent activity

11 hits · last 30 days

node

Amazon

Resources

githubhttps://github.com/djedlajn/nestjs-minio-client ↗

packagehttps://www.npmjs.com/package/nestjs-minio-client ↗