0
# MinIO JavaScript Client Library
1

2
**Package:** `minio`  
3
**Version:** 8.0.5  
4
**Type:** JavaScript/TypeScript library for S3-compatible cloud storage  
5
**License:** Apache 2.0
6

7
The MinIO JavaScript client library provides comprehensive functionality for interacting with MinIO and Amazon S3 compatible cloud storage services. It offers both callback-based and Promise-based APIs, supporting Node.js and browser environments.
8

9
## Installation
10

11
```bash
12
npm install minio
13
```
14

15
## Core Imports
16

17
```javascript
18
// Main client class
19
import { Client } from 'minio'
20

21
// Helper classes for advanced operations
22
import { CopySourceOptions, CopyDestinationOptions } from 'minio'
23

24
// Policy and conditions
25
import { PostPolicy, CopyConditions } from 'minio'
26

27
// Notification system
28
import { NotificationConfig, TopicConfig, QueueConfig, CloudFunctionConfig } from 'minio'
29

30
// Credential providers
31
import { CredentialProvider, AssumeRoleProvider, IamAwsProvider } from 'minio'
32

33
// Error classes
34
import { 
35
  S3Error, 
36
  InvalidArgumentError, 
37
  InvalidBucketNameError,
38
  InvalidObjectNameError 
39
} from 'minio'
40

41
// Types and enums
42
import { 
43
  ENCRYPTION_TYPES, 
44
  LEGAL_HOLD_STATUS, 
45
  RETENTION_MODES,
46
  RETENTION_VALIDITY_UNITS 
47
} from 'minio'
48
```
49

50
## Quick Start
51

52
```javascript { .api }
53
import { Client } from 'minio'
54

55
// Create client instance
56
const minioClient = new Client({
57
  endPoint: 'play.min.io',
58
  port: 9000,
59
  useSSL: true,
60
  accessKey: 'your-access-key',
61
  secretKey: 'your-secret-key'
62
})
63

64
// Basic operations
65
async function basicOperations() {
66
  // Create bucket
67
  await minioClient.makeBucket('test-bucket', 'us-east-1')
68
  
69
  // Upload object
70
  const uploadInfo = await minioClient.putObject(
71
    'test-bucket', 
72
    'test.txt', 
73
    'Hello MinIO!'
74
  )
75
  
76
  // Download object
77
  const stream = await minioClient.getObject('test-bucket', 'test.txt')
78
  
79
  // Get object metadata
80
  const stat = await minioClient.statObject('test-bucket', 'test.txt')
81
  
82
  // List objects
83
  const objectStream = minioClient.listObjects('test-bucket')
84
  objectStream.on('data', obj => console.log(obj))
85
}
86
```
87

88
## Architecture Overview
89

90
The MinIO JavaScript client follows a modular architecture:
91

92
### Core Components
93

94
1. **Client Class** - Main entry point extending TypedClient
95
   - Bucket operations (create, delete, list, policies)
96
   - Object operations (put, get, copy, delete)
97
   - Presigned URL generation
98
   - Notification management
99

100
2. **Credential Management** - Flexible authentication
101
   - Static credentials (access/secret key)
102
   - Credential providers (IAM, STS AssumeRole)
103
   - Session tokens and temporary credentials
104

105
3. **Helper Classes** - Advanced functionality
106
   - Copy operations with conditions and metadata
107
   - Post policy generation for browser uploads
108
   - Notification configuration and polling
109

110
4. **Error Handling** - Comprehensive error types
111
   - S3-specific errors with codes and regions
112
   - Validation errors for parameters
113
   - Network and authentication errors
114

115
### Environment Support
116

117
- **Node.js** - Full functionality with streams and file system access
118
- **Browser** - Core operations with limitations (no file system operations)
119
- **TypeScript** - Complete type definitions and intellisense support
120

121
## Capabilities
122

123
### Bucket Management
124
- Create, delete, and list buckets
125
- Bucket policies and access control
126
- Versioning configuration
127
- Lifecycle management
128
- Encryption settings
129
- Replication configuration
130
- Notification setup
131

132
### Object Operations
133
- Upload/download with streams or files
134
- Metadata and tags management
135
- Server-side encryption support
136
- Object versioning and retention
137
- Legal hold functionality
138
- Multipart upload for large files
139

140
### Advanced Features
141
- Presigned URLs for secure access
142
- S3 Select for querying object content
143
- Event notifications with polling
144
- Copy operations with conditions
145
- Compose multiple objects into one
146

147
### Security Features
148
- Multiple encryption types (SSE-C, KMS)
149
- Access control through policies
150
- Temporary credentials and STS
151
- Request signing and authentication
152

153
## Documentation Structure
154

155
This documentation is organized into focused sections:
156

157
- **[Client Setup](./client-setup.md)** - Client initialization, configuration options, credential providers
158
- **[Bucket Operations](./bucket-operations.md)** - Complete bucket management functionality
159
- **[Object Operations](./object-operations.md)** - Basic object CRUD operations and metadata
160
- **[Advanced Objects](./advanced-objects.md)** - Multipart uploads, composition, retention, S3 Select
161
- **[Presigned Operations](./presigned-operations.md)** - Presigned URLs and POST policies for secure access
162
- **[Notifications](./notifications.md)** - Event notification system and polling mechanisms  
163
- **[Types and Errors](./types-and-errors.md)** - Complete type definitions, error classes, and enums
164

165
## Compatibility
166

167
### S3 Compatibility
168
The client is compatible with:
169
- Amazon S3
170
- MinIO Server
171
- Google Cloud Storage (S3 compatibility mode)
172
- Other S3-compatible storage services
173

174
### API Patterns
175
The library supports both patterns:
176
```javascript { .api }
177
// Promise-based (recommended)
178
const result = await minioClient.listBuckets()
179

180
// Callback-based (legacy support)
181
minioClient.listBuckets((err, buckets) => {
182
  if (err) throw err
183
  console.log(buckets)
184
})
185
```
186

187
## Performance Considerations
188

189
- **Streaming Support** - Efficient handling of large files
190
- **Connection Pooling** - Configurable HTTP agents
191
- **Multipart Uploads** - Automatic handling for large objects
192
- **Presigned URLs** - Offload uploads/downloads to clients
193
- **Request Tracing** - Built-in debugging capabilities
194

195
## Next Steps
196

197
1. Start with [Client Setup](./client-setup.md) to configure your client
198
2. Explore [Bucket Operations](./bucket-operations.md) for bucket management
199
3. Learn [Object Operations](./object-operations.md) for basic file handling
200
4. Check [Advanced Objects](./advanced-objects.md) for complex scenarios
201
5. Review [Types and Errors](./types-and-errors.md) for comprehensive API reference