0
# Client Setup
1

2
This document covers client initialization, configuration options, and credential management for the MinIO JavaScript client.
3

4
## Client Class
5

6
The main `Client` class extends `TypedClient` and provides the primary interface for all MinIO operations.
7

8
### Constructor
9

10
```javascript { .api }
11
import { Client } from 'minio'
12

13
const client = new Client(options)
14
```
15

16
### ClientOptions Interface
17

18
```typescript { .api }
19
interface ClientOptions {
20
  // Required
21
  endPoint: string              // MinIO server hostname or IP
22
  
23
  // Authentication (choose one method)
24
  accessKey?: string            // Access key for authentication
25
  secretKey?: string            // Secret key for authentication
26
  credentialsProvider?: CredentialProvider  // Dynamic credential provider
27
  
28
  // Connection settings
29
  useSSL?: boolean             // Use HTTPS (default: true for port 443)
30
  port?: number               // Server port (default: 443 for HTTPS, 80 for HTTP)
31
  region?: string             // AWS region (default: 'us-east-1')
32
  
33
  // Advanced options
34
  sessionToken?: string        // Temporary session token
35
  partSize?: number           // Multipart upload part size (min: 5MB)
36
  pathStyle?: boolean         // Use path-style URLs (default: false)
37
  s3AccelerateEndpoint?: string // S3 transfer acceleration endpoint
38
  transport?: Transport       // Custom HTTP transport
39
  transportAgent?: http.Agent // HTTP agent for connection pooling
40
}
41
```
42

43
## Basic Client Setup
44

45
### Simple Configuration
46

47
```javascript { .api }
48
import { Client } from 'minio'
49

50
// Basic setup with access keys
51
const minioClient = new Client({
52
  endPoint: 'play.min.io',
53
  port: 9000,
54
  useSSL: true,
55
  accessKey: 'Q3AM3UQ867SPQQA43P2F',
56
  secretKey: 'zuf+tfteSlswRu7BJ86wekitnifILbZam1KYY3TG'
57
})
58
```
59

60
### Production Configuration
61

62
```javascript { .api }
63
import { Client } from 'minio'
64
import * as https from 'node:https'
65

66
const minioClient = new Client({
67
  endPoint: 'minio.mycompany.com',
68
  port: 443,
69
  useSSL: true,
70
  accessKey: process.env.MINIO_ACCESS_KEY,
71
  secretKey: process.env.MINIO_SECRET_KEY,
72
  region: 'us-west-2',
73
  partSize: 64 * 1024 * 1024, // 64MB parts for large uploads
74
  
75
  // Connection pooling for better performance
76
  transportAgent: new https.Agent({
77
    keepAlive: true,
78
    maxSockets: 10,
79
    timeout: 60000
80
  })
81
})
82
```
83

84
### Browser Configuration
85

86
```javascript { .api }
87
// Browser environment - no file system operations
88
const minioClient = new Client({
89
  endPoint: 'play.min.io',
90
  port: 9000,
91
  useSSL: true,
92
  accessKey: 'Q3AM3UQ867SPQQA43P2F',
93
  secretKey: 'zuf+tfteSlswRu7BJ86wekitnifILbZam1KYY3TG'
94
})
95

96
// Note: fPutObject and fGetObject are not available in browser
97
```
98

99
## Credential Providers
100

101
The MinIO client supports multiple authentication methods through credential providers.
102

103
### CredentialProvider Base Class
104

105
```typescript { .api }
106
import { CredentialProvider, Credentials } from 'minio'
107

108
class CredentialProvider {
109
  constructor(options: {
110
    accessKey?: string
111
    secretKey?: string  
112
    sessionToken?: string
113
  })
114
  
115
  // Methods
116
  async getCredentials(): Promise<Credentials>
117
  setCredentials(credentials: Credentials): void
118
  setAccessKey(accessKey: string): void
119
  getAccessKey(): string
120
  setSecretKey(secretKey: string): void
121
  getSecretKey(): string
122
  setSessionToken(sessionToken: string): void
123
  getSessionToken(): string
124
}
125
```
126

127
### Credentials Class
128

129
```typescript { .api }
130
class Credentials {
131
  constructor(options: {
132
    accessKey: string
133
    secretKey: string
134
    sessionToken?: string
135
  })
136
  
137
  // Properties
138
  accessKey: string
139
  secretKey: string
140
  sessionToken?: string
141
  
142
  // Methods
143
  setAccessKey(accessKey: string): void
144
  getAccessKey(): string
145
  setSecretKey(secretKey: string): void
146
  getSecretKey(): string
147
  setSessionToken(sessionToken: string): void
148
  getSessionToken(): string
149
  get(): Credentials
150
}
151
```
152

153
### AssumeRoleProvider
154

155
For AWS STS AssumeRole authentication:
156

157
```typescript { .api }
158
import { AssumeRoleProvider } from 'minio'
159

160
interface AssumeRoleProviderOptions {
161
  stsEndpoint: string           // STS endpoint URL
162
  accessKey: string            // Initial access key
163
  secretKey: string            // Initial secret key
164
  durationSeconds?: number     // Session duration (900-43200 seconds)
165
  sessionToken?: string        // Existing session token
166
  policy?: string             // IAM policy for session
167
  region?: string             // AWS region
168
  roleArn?: string            // Role ARN to assume
169
  roleSessionName?: string    // Session name for the role
170
  externalId?: string         // External ID for role assumption
171
  token?: string              // MFA token
172
  webIdentityToken?: string   // Web identity token
173
  action?: string             // STS action (default: AssumeRole)
174
  transportAgent?: http.Agent // HTTP agent
175
}
176

177
// Usage
178
const assumeRoleProvider = new AssumeRoleProvider({
179
  stsEndpoint: 'https://sts.amazonaws.com',
180
  accessKey: 'your-access-key',
181
  secretKey: 'your-secret-key',
182
  roleArn: 'arn:aws:iam::123456789012:role/MyRole',
183
  roleSessionName: 'MinIOSession',
184
  durationSeconds: 3600
185
})
186

187
const client = new Client({
188
  endPoint: 's3.amazonaws.com',
189
  credentialsProvider: assumeRoleProvider
190
})
191
```
192

193
### IamAwsProvider
194

195
For EC2/ECS IAM role credentials:
196

197
```typescript { .api }
198
import { IamAwsProvider } from 'minio'
199

200
interface IamAwsProviderOptions {
201
  customEndpoint?: string     // Custom metadata endpoint
202
  transportAgent?: http.Agent // HTTP agent
203
}
204

205
// Usage - automatic IAM role detection
206
const iamProvider = new IamAwsProvider()
207

208
const client = new Client({
209
  endPoint: 's3.amazonaws.com', 
210
  credentialsProvider: iamProvider
211
})
212

213
// With custom endpoint (for testing)
214
const customIamProvider = new IamAwsProvider({
215
  customEndpoint: 'http://169.254.169.254'
216
})
217
```
218

219
### Dynamic Credential Updates
220

221
```javascript { .api }
222
// Update credentials at runtime
223
const credentialProvider = new CredentialProvider({
224
  accessKey: 'initial-key',
225
  secretKey: 'initial-secret'
226
})
227

228
const client = new Client({
229
  endPoint: 'play.min.io',
230
  credentialsProvider: credentialProvider
231
})
232

233
// Later, update credentials
234
await client.setCredentialsProvider(new CredentialProvider({
235
  accessKey: 'new-access-key',
236
  secretKey: 'new-secret-key',
237
  sessionToken: 'session-token'
238
}))
239
```
240

241
## Advanced Configuration
242

243
### Custom Transport
244

245
```javascript { .api }
246
import * as https from 'node:https'
247

248
// Custom HTTPS agent with specific settings
249
const customAgent = new https.Agent({
250
  keepAlive: true,
251
  maxSockets: 25,
252
  maxFreeSockets: 10,
253
  timeout: 30000,
254
  freeSocketTimeout: 4000,
255
  // Custom certificate settings if needed
256
  rejectUnauthorized: false // Only for development!
257
})
258

259
const client = new Client({
260
  endPoint: 'minio.internal.com',
261
  port: 9000,
262
  useSSL: true,
263
  accessKey: process.env.MINIO_ACCESS_KEY,
264
  secretKey: process.env.MINIO_SECRET_KEY,
265
  transportAgent: customAgent
266
})
267
```
268

269
### Path-Style URLs
270

271
```javascript { .api }
272
// Force path-style URLs (bucket in path, not subdomain)
273
const client = new Client({
274
  endPoint: 'localhost',
275
  port: 9000,
276
  useSSL: false,
277
  accessKey: 'minioadmin',
278
  secretKey: 'minioadmin',
279
  pathStyle: true // URLs like http://localhost:9000/bucket/object
280
})
281
```
282

283
### S3 Transfer Acceleration
284

285
```javascript { .api }
286
const client = new Client({
287
  endPoint: 's3.amazonaws.com',
288
  useSSL: true,
289
  accessKey: process.env.AWS_ACCESS_KEY_ID,
290
  secretKey: process.env.AWS_SECRET_ACCESS_KEY,
291
  s3AccelerateEndpoint: 's3-accelerate.amazonaws.com'
292
})
293

294
// Or set it after client creation
295
client.setS3TransferAccelerate('s3-accelerate.amazonaws.com')
296
```
297

298
## Client Utility Methods
299

300
### Application Information
301

302
```javascript { .api }
303
// Set application info for user agent
304
client.setAppInfo('MyApp', '1.2.3')
305
```
306

307
### Request Options
308

309
```javascript { .api }
310
import * as https from 'node:https'
311

312
// Set global request options
313
client.setRequestOptions({
314
  timeout: 30000,
315
  headers: {
316
    'X-Custom-Header': 'custom-value'
317
  }
318
})
319
```
320

321
### Debugging and Tracing
322

323
```javascript { .api }
324
import * as fs from 'node:fs'
325

326
// Enable request/response tracing to console
327
client.traceOn()
328

329
// Enable tracing to file
330
const logStream = fs.createWriteStream('minio-trace.log')
331
client.traceOn(logStream)
332

333
// Disable tracing
334
client.traceOff()
335
```
336

337
### MinIO Extensions
338

339
The client provides access to MinIO-specific extensions that are not part of standard S3:
340

341
```javascript { .api }
342
// Access MinIO-specific extensions
343
const extensions = client.extensions
344

345
// MinIO extensions provide additional functionality
346
// not available in standard S3 implementations
347
console.log('MinIO Extensions available:', extensions)
348
```
349

350
## Environment Variables
351

352
Common environment variables for configuration:
353

354
```bash
355
# Basic authentication
356
export MINIO_ACCESS_KEY=your-access-key
357
export MINIO_SECRET_KEY=your-secret-key
358

359
# AWS credentials (for S3)
360
export AWS_ACCESS_KEY_ID=your-aws-key
361
export AWS_SECRET_ACCESS_KEY=your-aws-secret
362
export AWS_SESSION_TOKEN=your-session-token
363
export AWS_REGION=us-east-1
364

365
# MinIO server settings  
366
export MINIO_ENDPOINT=play.min.io
367
export MINIO_PORT=9000
368
export MINIO_USE_SSL=true
369
```
370

371
## Error Handling
372

373
```javascript { .api }
374
import { 
375
  Client, 
376
  S3Error, 
377
  InvalidArgumentError,
378
  InvalidBucketNameError 
379
} from 'minio'
380

381
try {
382
  const client = new Client({
383
    endPoint: 'invalid-endpoint',
384
    accessKey: 'test',
385
    secretKey: 'test'
386
  })
387
} catch (error) {
388
  if (error instanceof InvalidArgumentError) {
389
    console.error('Invalid client configuration:', error.message)
390
  }
391
}
392

393
// Runtime operation errors
394
try {
395
  await client.listBuckets()
396
} catch (error) {
397
  if (error instanceof S3Error) {
398
    console.error('S3 Error:', error.code, error.message)
399
    console.error('Region:', error.region)
400
  }
401
}
402
```
403

404
## Best Practices
405

406
### 1. Credential Security
407
- Never hardcode credentials in source code
408
- Use environment variables or credential providers
409
- Rotate credentials regularly
410
- Use IAM roles when possible (EC2/ECS)
411

412
### 2. Performance Optimization
413
- Configure appropriate connection pooling
414
- Use multipart uploads for large files (set `partSize`)
415
- Enable keep-alive connections
416
- Consider S3 Transfer Acceleration for global applications
417

418
### 3. Error Handling
419
- Always handle credential expiration
420
- Implement retry logic for network errors
421
- Validate bucket and object names before operations
422
- Log errors appropriately for debugging
423

424
### 4. Resource Management
425
- Close streams properly
426
- Handle backpressure in streaming operations
427
- Use appropriate timeouts
428
- Monitor connection pool usage
429

430
---
431

432
**Next:** [Bucket Operations](./bucket-operations.md) - Learn about bucket management and configuration