SDK v3 Fundamentals Best Practices

These are the habits that make AWS SDK for JavaScript v3 code small, typed, and cheap to run.

They are specific to v3's design: the command pattern, per-service packages, and the middleware stack all reward a particular discipline. Walk the list once, then use it as a review checklist before shipping.

How to Use This List

• Each item is a rule stated positively, with a one-line rationale.
• Groups run roughly in order of impact: imports and clients first, then typing, errors, credentials, and config.
• Check the boxes against your own code as a quick audit.
• Revisit when you add a new service client or target a new runtime (browser, Deno, Bun, Lambda).

A - Imports & Tree-Shaking

• Import only the commands you use. Named imports like import { GetObjectCommand } from "@aws-sdk/client-s3" let the bundler drop every command you never reference.
• Never import * as AWS. A namespace import defeats tree-shaking by pulling the whole client surface into the bundle.
• Install one package per service. Add @aws-sdk/client-<service> per service rather than reaching for a monolith - there is no v3 monolith anyway.
• Do not start new work on v2 aws-sdk. It is in maintenance mode and cannot tree-shake; use the modular @aws-sdk/* packages.

Named command imports are what make v3 bundles small.

// Good: only ListBucketsCommand is reachable and bundled.
import { S3Client, ListBucketsCommand } from "@aws-sdk/client-s3";
 
const s3 = new S3Client({ region: "us-east-1" });
await s3.send(new ListBucketsCommand({}));

B - Client Lifecycle

• Create clients once and reuse them. Client construction sets up connection pools and config; rebuilding per call wastes CPU and sockets.
• One client per service. Make an S3Client and a DynamoDBClient separately; do not try to share one across services.
• Initialize at module scope in Lambda. Declaring the client outside the handler lets warm invocations reuse it across requests.
• Pass shared config once. Build region and credentials into the client rather than repeating them per command.

import { DynamoDBClient } from "@aws-sdk/client-dynamodb";
 
// Module scope: constructed once, reused by every warm invocation.
const ddb = new DynamoDBClient({ region: "us-east-1" });
 
export async function handler(/* ... */) {
  // reuse ddb here
}

C - Typed Inputs & Outputs

• Let TypeScript check command inputs. Construct commands with object literals so the compiler flags missing or misspelled fields against the API contract.
• Use the generated input/output types. Import GetObjectCommandInput/Output when you build inputs in helpers, instead of any.
• Guard optional response fields. Response arrays and fields are typed as possibly undefined; use ?? [] and optional chaining.
• Avoid casting away the types. A stray as any on a command input hides real mistakes the compiler would catch.

import { GetObjectCommand, type GetObjectCommandInput } from "@aws-sdk/client-s3";
 
function buildGet(input: GetObjectCommandInput) {
  return new GetObjectCommand(input);   // typo in a key is a compile error
}

D - Errors & Retries

• Catch typed exception classes. Match instanceof NoSuchKey (and friends) rather than string-comparing messages.
• Log $metadata.requestId on failure. It is the id AWS support needs to trace a specific call.
• Rely on built-in retries. v3 retries throttling and transient network errors with backoff by default; do not reimplement it.
• Tune, do not replace, retry behavior. Set maxAttempts and the retry mode in client config for bursty workloads instead of hand-rolling loops.

import { GetObjectCommand, NoSuchKey } from "@aws-sdk/client-s3";
 
try {
  await s3.send(new GetObjectCommand({ Bucket: "b", Key: "missing" }));
} catch (err) {
  if (err instanceof NoSuchKey) return null;
  console.error((err as { $metadata?: { requestId?: string } }).$metadata?.requestId);
  throw err;
}

E - Credentials & Security

• Never inline access keys. Resolve credentials via a provider or an IAM role, keeping secrets out of source and bundles.
• Prefer IAM roles in production. On EC2, ECS, and Lambda, the default chain picks up rotating temporary credentials automatically.
• Use scoped, temporary credentials in the browser. Reach for fromCognitoIdentityPool, never static keys a user can read from the bundle.
• Pick a provider explicitly when it matters. Use fromEnv/fromIni to pin the source in CI or multi-account local setups.

F - Config, Versions & Middleware

• Set the region explicitly. Pin region (or AWS_REGION) so calls do not depend on ambient defaults.
• Keep all @aws-sdk/* on one version. Mismatched versions can duplicate shared internals and cause subtle breakage.
• Add middleware sparingly and by name. Only hook the Smithy stack for logging, headers, or tracing, and always pass a name so you can remove it.
• Prefer presigned URLs over shipping the SDK to clients. For uploads and downloads, mint a URL server-side and let the browser fetch it.

FAQs

Related

• SDK v3 Fundamentals Basics - the calls these habits apply to.
• Installing Only the Clients You Need - the import and version rules in groups A and F.
• Credential Providers: fromEnv, fromIni, fromNodeProviderChain - the credential rules in group E.
• The Smithy Middleware Stack - adding middleware safely, from group F.

Stack versions: This page was written for the AWS SDK for JavaScript v3 on Node.js 18+ (and boto3 1.43.x / Python 3.10+ where contrasted).

3730363230327c343231316f6967637c6f692e73656469756765646f63