# AWS SDK for JavaScript v3 Client Configuration: Bare vs Aggregated Clients

> Explore AWS SDK for JavaScript v3 client configuration benefits. Learn about bare vs aggregated clients and choose the best option for your application's bundle size and convenience.

- Repository: [Amazon Web Services/agent-toolkit-for-aws](https://github.com/aws/agent-toolkit-for-aws)
- Tags: deep-dive
- Published: 2026-07-02

---

**The AWS SDK for JavaScript v3 offers two client styles: bare-bones clients that import only specific commands for minimal bundle sizes, and aggregated clients that include all service methods for convenience, with both sharing identical configuration objects and runtime behavior.**

The AWS SDK for JavaScript v3 ships each AWS service as a standalone client package, supporting two distinct usage patterns that trade bundle size against developer convenience. According to the `aws/agent-toolkit-for-aws` source code, you can choose between importing individual command classes or using a full service wrapper, with both approaches utilizing the same underlying configuration model and request pipeline.

## Understanding the Two Client Styles

### Bare-Bones Client (Command-Based)

The bare-bones style imports only the client class and the specific commands you need. Import from the package root using destructured imports:

```javascript
import { S3Client, GetObjectCommand } from "@aws-sdk/client-s3";

```

You instantiate the client with `new S3Client({ region: "us-east-1" })` and execute operations by constructing command objects and passing them to `client.send()`:

```javascript
const client = new S3Client({ region: "us-east-1" });
await client.send(new GetObjectCommand({ Bucket: "b", Key: "k" }));

```

### Aggregated Client (Service-Based)

The aggregated client imports the entire service API surface. Import the class directly:

```javascript
import { S3 } from "@aws-sdk/client-s3";

```

Instantiate with `new S3({ region: "us-east-1" })` and call convenience methods that internally construct and send the corresponding command objects:

```javascript
const client = new S3({ region: "us-east-1" });
await client.getObject({ Bucket: "b", Key: "k" });

```

## Bundle Size and Performance Implications

The primary difference between these AWS SDK for JavaScript v3 client configuration styles lies in bundle composition. The bare-bones approach includes only imported commands, resulting in smaller bundles ideal for Lambda functions and front-end applications. The aggregated client pulls in the complete command set for that service, increasing bundle size but eliminating the need to manage individual command imports.

## Configuration Patterns and Best Practices

Both client styles share identical configuration resolution. According to [`skills/core-skills/aws-sdk-js-v3-usage/SKILL.md`](https://github.com/aws/agent-toolkit-for-aws/blob/main/skills/core-skills/aws-sdk-js-v3-usage/SKILL.md) in the `aws/agent-toolkit-for-aws` repository, the configuration must be passed during instantiation and must include a `region` (or rely on the `AWS_REGION` environment variable).

### Critical Configuration Rules

- **Never mutate `client.config` after construction.** The SDK resolves configuration once during instantiation, and post-construction mutations can cause subtle bugs (see `skills/core-skills/aws-sdk-js-v3-usage/SKILL.md#L52-L53`).
- **Always import from the package root** (e.g., `@aws-sdk/client-s3`) rather than deep-path imports (`skills/core-skills/aws-sdk-js-v3-usage/SKILL.md#L17-L22`).
- **For multi-region scenarios**, extract `credentials` and `requestHandler` from one client instance and pass them to another to avoid redundant credential resolution (`skills/core-skills/aws-sdk-js-v3-usage/SKILL.md#L73-L79`).

## Practical Code Examples

### Bare-Bones Client Implementation

```javascript
import { S3Client, GetObjectCommand } from "@aws-sdk/client-s3";

const s3 = new S3Client({ region: "us-east-1" });
const resp = await s3.send(
  new GetObjectCommand({ Bucket: "my-bucket", Key: "file.txt" })
);
const body = await resp.Body.transformToString();

```

### Aggregated Client Implementation

```javascript
import { S3 } from "@aws-sdk/client-s3";

const s3 = new S3({ region: "us-east-1" });
const resp = await s3.getObject({ Bucket: "my-bucket", Key: "file.txt" });
const body = await resp.Body.transformToString();

```

### Shared Configuration Across Regions

```javascript
import { S3Client } from "@aws-sdk/client-s3";

const east = new S3Client({ region: "us-east-1" });
const { credentials, requestHandler } = east.config;

const west = new S3Client({
  region: "us-west-2",
  credentials,
  requestHandler,
});

```

## Summary

- The AWS SDK for JavaScript v3 provides **bare-bones clients** for minimal bundle sizes and **aggregated clients** for convenience.
- Bare-bones clients require importing and constructing individual command classes; aggregated clients expose methods that wrap these commands internally.
- Both styles use identical configuration objects passed during instantiation, with no global configuration state.
- Never modify `client.config` after creating the client to avoid runtime bugs.
- Extract shared `credentials` and `requestHandler` from existing clients when configuring multiple regions or services.

## Frequently Asked Questions

### What is the difference between S3Client and S3 in AWS SDK for JavaScript v3?

`S3Client` is the bare-bones client requiring explicit command objects, while `S3` is the aggregated client that includes all service methods as convenience functions. Both classes connect to the same AWS endpoints and use identical request pipelines, but `S3Client` enables tree-shaking to remove unused commands from your bundle.

### Does the aggregated client have different retry behavior than the bare-bones client?

No. The aggregated client is a thin wrapper that internally instantiates the corresponding command objects and calls `client.send()`. The underlying retry logic, request signing, and pagination handling remain identical between both styles, as implemented in the `aws/agent-toolkit-for-aws` reference architecture.

### Can I mix bare-bones and aggregated client imports in the same project?

While technically possible, mixing styles is discouraged because it can lead to bundle bloat. If you import the aggregated client (`S3`), you pull in all commands even if you also import specific commands for the bare-bones style. Choose one pattern per service based on your bundle size requirements.

### How do I share configuration between multiple AWS service clients?

Extract the `credentials` and `requestHandler` properties from an existing client's `config` object and pass them to new client instances. This pattern, documented in [`skills/core-skills/aws-sdk-js-v3-usage/SKILL.md`](https://github.com/aws/agent-toolkit-for-aws/blob/main/skills/core-skills/aws-sdk-js-v3-usage/SKILL.md), allows you to reuse credential providers and HTTP handlers across different regions or services without redundant initialization.