minio

The MinIO JavaScript Client SDK provides high-level, promise-based APIs for working with any Amazon S3-compatible object storage server, whether that’s a self-hosted MinIO cluster or S3 itself. It covers the full range of bucket and object operations — creating and listing buckets, streaming uploads/downloads, multipart file transfers, presigned URLs, bucket policies, lifecycle rules, versioning, replication, and encryption — behind a single Minio.Client entry point.

Because it speaks the S3 API rather than a MinIO-only protocol, code written against this SDK is portable across MinIO, AWS S3, and other compatible providers, making it a common choice for Node.js applications that need object storage without committing to a single cloud vendor.

What You Get

• A single Minio.Client class covering bucket operations (create, list, exists, remove, versioning, lifecycle, replication, encryption)
• Streaming object APIs (putObject, getObject, fPutObject, fGetObject) for uploading/downloading without buffering entire files in memory
• Presigned URL generation (presignedGetObject, presignedPutObject, presignedPostPolicy) for delegating temporary access without exposing credentials
• Bucket notification and event-listening support (listenBucketNotification) for reacting to object changes
• Built-in TypeScript type definitions (since 7.1.0) and both CommonJS and ESM builds

Common Use Cases

• Uploading and serving user-generated files (images, documents, videos) from a Node.js backend to a self-hosted MinIO cluster
• Generating presigned URLs so browsers or mobile clients can upload/download directly without routing bytes through the app server
• Migrating storage code between AWS S3 and self-hosted MinIO without rewriting business logic, since both speak the same S3 API
• Managing bucket lifecycle, versioning, and replication policies as part of an infrastructure-as-code or admin tooling workflow

Under The Hood

Architecture - The client is centered on src/internal/client.ts, which builds signed HTTP requests (SigV4, implemented in signing.ts) and parses XML responses (internal/xml-parser.ts) for every S3 operation; minio.ts composes this internal client with higher-level, publicly exported methods, while notification.ts, post-policy.ts, and copy-conditions.ts layer on specific S3 feature areas (bucket notifications, browser-based POST uploads, and conditional copies) on top of the same request pipeline.

Tech Stack - Written in TypeScript, built via a custom build.mjs script into both CommonJS (dist/main) and ESM (dist/esm) outputs with generated type declarations, so the same source ships to Node’s require and import consumers alike; linting is ESLint plus Prettier with Husky/lint-staged pre-commit hooks, and tests run under Mocha, including a separate tests/functional suite that exercises real S3-compatible operations rather than only mocks.

Code Quality - Core S3 protocol concerns (signing, XML parsing, error mapping in errors.ts) are isolated into their own modules under src/internal/, which keeps minio.ts focused on the public API surface; credential handling is further split into pluggable providers (AssumeRoleProvider.ts, IamAwsProvider.ts, CredentialProvider.ts) supporting STS-style role assumption and IAM-based credentials, not just static keys, alongside the standard functional test suite.

API Design - The public API is a single Minio.Client with async methods named directly after the operations they perform (fPutObject, bucketExists, presignedPutObject), which keeps the mental model close to the underlying S3 REST API and lowers the learning curve for anyone already familiar with S3 clients in other languages.