AWS SDK for JavaScript (S3 Client)

@aws-sdk/client-s3 is the officially maintained Amazon S3 client from the AWS SDK for JavaScript v3, published from the aws/aws-sdk-js-v3 monorepo. It replaces the monolithic v2 SDK with a modular, per-service package model, so applications only bundle the S3 surface area they actually use instead of the entire AWS API surface.

The package exposes both a low-level S3Client paired with one command class per operation (GetObjectCommand, PutObjectCommand, ListBucketsCommand, and over a hundred others), and a higher-level aggregated S3 class that exposes every operation as a plain method for developers migrating from v2-style code. It ships first-class TypeScript types, a pluggable middleware stack for request/response processing, built-in credential resolution, and streaming-aware request/response bodies for large object transfer.

What You Get

• A modular S3Client plus one typed Command class per S3 operation (over 110 commands covering buckets, objects, multipart uploads, replication, lifecycle rules, and more)
• An aggregated S3 client class exposing every operation as a callable method, for a more v2-SDK-like ergonomic style
• First-class TypeScript types for every request/response shape, generated directly from AWS’s service models
• A configurable middleware stack (@smithy/core) for retries, checksums, signing (SigV4/SigV4A), endpoint resolution, and custom request/response interceptors
• Built-in credential providers (environment, shared config, IAM role, SSO, container/EC2 instance metadata) via @aws-sdk/credential-provider-node
• Streaming-aware request and response bodies for efficient large-object upload/download, plus built-in waiters for eventual-consistency operations like waitForBucketExists

Common Use Cases

• Uploading and downloading objects (including multipart uploads for large files) from application backends or serverless functions
• Managing bucket configuration programmatically: lifecycle rules, versioning, replication, encryption, CORS, and access controls
• Generating presigned URLs for direct browser upload/download without proxying data through your own servers
• Building data pipelines and backup/ETL jobs that read from or write to S3 as a durable object store

Under The Hood

Architecture — The client is generated code sitting on top of AWS’s shared “Smithy” TypeScript runtime (@smithy/core). S3Client (in src/S3Client.ts) assembles its behavior from composable middleware plugins layered onto a base Client class: host-header, user-agent, retry, endpoint resolution, region redirect, checksum (SigV4/flexible checksums), and S3-specific plugins like bucket-name validation and S3 Express support are each registered as independent, individually testable units. Every operation is a thin Command subclass (e.g. GetObjectCommand) built via a shared commandBuilder factory that wires the command to its generated request/response schema; the aggregated S3 class (src/S3.ts, ~2,700 lines) is a mechanically generated facade that forwards each method call to the corresponding Command/send() pair, so the two API styles share one code path rather than duplicating logic.

Tech Stack — Written entirely in TypeScript (~96% of the monorepo by bytes) and built with a Lerna/Turborepo-managed Yarn workspace of 400+ interdependent packages. Runtime dependencies are kept intentionally thin and internal: @aws-sdk/core, @aws-sdk/credential-provider-node, @aws-sdk/middleware-sdk-s3, and @smithy/* packages, with environment-specific entry points (runtimeConfig.browser.ts, runtimeConfig.native.ts) swapped in via package.json browser/react-native fields so the same source targets Node, browsers, and React Native without conditional runtime checks in application code.

Code Quality — Testing is fixture-heavy rather than hand-written per command: test/snapshots/ contains 240+ request/response snapshot fixtures used by a shared snapshot-testing harness (@smithy/snapshot-testing) that validates every generated command against AWS’s service model, supplemented by targeted unit specs (e.g. dotSegmentInUriLabel.spec.ts for URL-encoding edge cases), integration specs under test/integ/, and browser/e2e suites under test/e2e/. Because the client code itself is generated from AWS’s Smithy models rather than hand-authored, correctness is enforced structurally (schema-driven serialization/deserialization) rather than through business-logic-style unit tests, which is an appropriate tradeoff for this kind of generated SDK.

API Design — Ergonomics are deliberately layered: S3Client + Commands gives tree-shakable, explicit control (client.send(new GetObjectCommand(params))) at the cost of more boilerplate per call, while the aggregated S3 class trades some bundle size for a flatter, v2-SDK-familiar method-call surface (client.getObject(params)). Every command ships JSDoc with the full parameter/permission/error documentation pulled from AWS’s API reference, and errors carry a consistent $metadata (requestId, cfId) shape across all commands, so error handling patterns are uniform regardless of which of the 110+ operations you call.