Client initialization and configuration options for connecting to Amazon S3 services with authentication, region settings, and advanced networking options.
Creates a new S3 client instance with specified configuration options.
/**
* Creates a new S3 client instance
* @param configuration - Client configuration options
*/
class S3Client {
constructor(configuration: S3ClientConfig);
/** Send a command to S3 and receive the response */
send<InputType, OutputType>(
command: Command<InputType, OutputType, S3ClientResolvedConfig>,
options?: HttpHandlerOptions
): Promise<OutputType>;
/** Clean up client resources */
destroy(): void;
}
interface S3ClientConfig extends Partial<S3ClientResolvedConfig> {
/** AWS region for S3 operations */
region?: string | Provider<string>;
/** AWS credentials for authentication */
credentials?: AwsCredentialIdentityProvider;
/** Custom endpoint URL for S3 operations */
endpoint?: string | EndpointV2 | Provider<EndpointV2>;
/** Maximum retry attempts for failed requests */
maxAttempts?: number | Provider<number>;
/** Retry mode strategy (legacy, standard, adaptive) */
retryMode?: string | Provider<string>;
/** Use path-style URLs instead of virtual-hosted-style */
forcePathStyle?: boolean | Provider<boolean>;
/** Enable S3 Transfer Acceleration */
useAccelerateEndpoint?: boolean | Provider<boolean>;
/** Use dual-stack endpoints (IPv4 and IPv6) */
useDualstackEndpoint?: boolean | Provider<boolean>;
/** Default bucket key enabled for S3 encryption */
bucketEndpoint?: boolean | Provider<boolean>;
/** Service-specific client configurations */
serviceConfigurationOptions?: {
/** Custom user agent prefix */
userAgentPrefix?: string;
};
}Basic Usage:
import { S3Client } from "@aws-sdk/client-s3";
// Minimal configuration
const client = new S3Client({
region: "us-west-2"
});
// With explicit credentials
const client = new S3Client({
region: "us-east-1",
credentials: {
accessKeyId: "AKIAIOSFODNN7EXAMPLE",
secretAccessKey: "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY"
}
});
// Advanced configuration
const client = new S3Client({
region: "eu-west-1",
credentials: {
accessKeyId: process.env.AWS_ACCESS_KEY_ID!,
secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY!,
sessionToken: process.env.AWS_SESSION_TOKEN
},
maxAttempts: 5,
retryMode: "adaptive",
forcePathStyle: false,
useAccelerateEndpoint: true,
endpoint: "https://s3.amazonaws.com"
});Provides convenience methods for common S3 operations without requiring separate command instantiation.
/**
* Aggregated S3 client with convenience methods
*/
class S3 {
constructor(configuration: S3ClientConfig);
/** Upload an object to S3 */
putObject(args: PutObjectCommandInput): Promise<PutObjectCommandOutput>;
/** Download an object from S3 */
getObject(args: GetObjectCommandInput): Promise<GetObjectCommandOutput>;
/** Delete an object from S3 */
deleteObject(args: DeleteObjectCommandInput): Promise<DeleteObjectCommandOutput>;
/** Create a new bucket */
createBucket(args: CreateBucketCommandInput): Promise<CreateBucketCommandOutput>;
/** List objects in a bucket */
listObjectsV2(args: ListObjectsV2CommandInput): Promise<ListObjectsV2CommandOutput>;
/** Check if bucket exists */
headBucket(args: HeadBucketCommandInput): Promise<HeadBucketCommandOutput>;
/** Check if object exists and get metadata */
headObject(args: HeadObjectCommandInput): Promise<HeadObjectCommandOutput>;
// ... includes all 105 command methods
}Usage Example:
import { S3 } from "@aws-sdk/client-s3";
const s3 = new S3({ region: "us-east-1" });
// Direct method calls without command classes
const result = await s3.putObject({
Bucket: "my-bucket",
Key: "example.txt",
Body: "Hello, World!"
});
const object = await s3.getObject({
Bucket: "my-bucket",
Key: "example.txt"
});Different runtime environments require specific configuration adaptations.
// Node.js configuration
interface NodeJsS3ClientConfig extends S3ClientConfig {
/** HTTP handler for Node.js environment */
requestHandler?: NodeHttpHandler;
/** Custom HTTP agent for connection pooling */
httpAgent?: Agent;
/** Request timeout in milliseconds */
requestTimeout?: number;
}
// Browser configuration
interface BrowserS3ClientConfig extends S3ClientConfig {
/** HTTP handler for browser environment */
requestHandler?: FetchHttpHandler;
/** Fetch implementation (defaults to global fetch) */
fetchImplementation?: typeof fetch;
/** Request timeout in milliseconds */
requestTimeout?: number;
}Platform Examples:
// Node.js with custom HTTP agent
import { Agent } from "https";
import { S3Client } from "@aws-sdk/client-s3";
const client = new S3Client({
region: "us-east-1",
requestHandler: new NodeHttpHandler({
httpAgent: new Agent({
keepAlive: true,
maxSockets: 25
})
})
});
// Browser with custom fetch
const client = new S3Client({
region: "us-west-2",
requestHandler: new FetchHttpHandler({
requestTimeout: 10000
})
});Various authentication methods for different deployment scenarios.
// Credential providers
interface AwsCredentialIdentityProvider {
(): Promise<AwsCredentialIdentity>;
}
interface AwsCredentialIdentity {
accessKeyId: string;
secretAccessKey: string;
sessionToken?: string;
expiration?: Date;
}
// Common provider functions
function fromEnv(): AwsCredentialIdentityProvider;
function fromIni(options?: FromIniInit): AwsCredentialIdentityProvider;
function fromInstanceMetadata(options?: RemoteProviderInit): AwsCredentialIdentityProvider;
function fromContainerMetadata(options?: RemoteProviderInit): AwsCredentialIdentityProvider;
function fromWebToken(options: FromWebTokenInit): AwsCredentialIdentityProvider;Authentication Examples:
import {
S3Client,
fromEnv,
fromIni,
fromInstanceMetadata
} from "@aws-sdk/client-s3";
// Environment variables (AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY)
const client1 = new S3Client({
region: "us-east-1",
credentials: fromEnv()
});
// AWS credentials file
const client2 = new S3Client({
region: "us-east-1",
credentials: fromIni({ profile: "dev" })
});
// EC2 instance metadata
const client3 = new S3Client({
region: "us-east-1",
credentials: fromInstanceMetadata()
});
// Explicit credentials
const client4 = new S3Client({
region: "us-east-1",
credentials: {
accessKeyId: "AKIAIOSFODNN7EXAMPLE",
secretAccessKey: "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY"
}
});Built-in retry logic and error handling configuration options.
interface RetryInputConfig {
/** Maximum retry attempts */
maxAttempts?: number | Provider<number>;
/** Retry mode: legacy, standard, adaptive */
retryMode?: string | Provider<string>;
/** Custom retry strategy */
retryStrategy?: RetryStrategy;
}
interface RetryStrategy {
acquireInitialRetryToken(retryTokenScope: string): RetryToken;
refreshRetryTokenForRetry(
token: RetryToken,
errorInfo: RetryErrorInfo
): RetryToken;
recordSuccess(token: RetryToken): void;
}Error Handling Example:
import { S3Client, S3ServiceException } from "@aws-sdk/client-s3";
const client = new S3Client({
region: "us-east-1",
maxAttempts: 3,
retryMode: "adaptive"
});
try {
const result = await client.send(command);
} catch (error) {
if (error instanceof S3ServiceException) {
console.error(`S3 Error: ${error.name}`);
console.error(`Status Code: ${error.$metadata.httpStatusCode}`);
console.error(`Request ID: ${error.$metadata.requestId}`);
} else {
console.error("Unexpected error:", error);
}
}