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

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:

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():

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:

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:

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 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

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

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

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, allows you to reuse credential providers and HTTP handlers across different regions or services without redundant initialization.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}