SDK v3 Fundamentals Basics

Seven examples to get you productive with the AWS SDK for JavaScript v3 - five basic and two intermediate.

Every example is pure TypeScript, because v3's command pattern, per-service packages, and credential providers have no boto3 equivalent. This is a tour of the SDK itself, not a cross-language comparison.

Prerequisites

• Node.js 18+ (20+ or 22+ recommended; 16.x support was dropped in January 2025). TypeScript is optional but assumed here.
• Install the client for whichever service you need, for example npm install @aws-sdk/client-s3. There is no single meta-package to install.
• Credentials configured once via aws configure, environment variables, or an IAM role. The default provider chain finds them automatically.
• A region, from AWS_REGION or passed per client as { region: "us-east-1" }.

Basic Examples

1. Install and Import a Client

Each service is its own package, so you install and import exactly the client you need.

// Terminal: npm install @aws-sdk/client-s3
import { S3Client } from "@aws-sdk/client-s3";
 
const s3 = new S3Client({ region: "us-east-1" });
console.log(s3.constructor.name);   // S3Client

• The package name is always @aws-sdk/client-<service>, lowercase, hyphenated.
• Importing the client pulls in only that service, keeping bundles and cold starts small.
• Constructing a client is cheap and does no network call; build it once and reuse it.
• The region can also come from AWS_REGION, so new S3Client({}) works when it is set.

Related: Installing Only the Clients You Need - the per-service packaging model.

2. Send Your First Command

You never call a method named after the operation; you send a command object.

import { S3Client, ListBucketsCommand } from "@aws-sdk/client-s3";
 
const s3 = new S3Client({});
const response = await s3.send(new ListBucketsCommand({}));
for (const bucket of response.Buckets ?? []) {
  console.log(bucket.Name);
}

• Import the command class (ListBucketsCommand) alongside the client.
• client.send(new XCommand(input)) is the universal calling convention in v3.
• The response is a typed object whose keys match the S3 API reference in PascalCase.
• Optional arrays may be undefined, so guard with ?? [] before iterating.

Related: SDK v3's Command Pattern - why every call is a command.

3. Pass Input and Read the Response

Most commands take an input object, and the response is fully typed.

import { S3Client, HeadObjectCommand } from "@aws-sdk/client-s3";
 
const s3 = new S3Client({});
const head = await s3.send(new HeadObjectCommand({
  Bucket: "my-bucket",
  Key: "report.pdf",
}));
console.log(head.ContentLength, head.ContentType);

• Input keys mirror the AWS API contract exactly; TypeScript flags typos at compile time.
• HeadObject returns metadata only, without downloading the object body.
• Response fields are typed as possibly undefined, so the compiler nudges you to handle absence.
• The types come from the client package, so no extra @types install is needed.

4. Handle a Typed Error

AWS calls fail as typed exception classes you can match precisely.

import { S3Client, GetObjectCommand, NoSuchKey } from "@aws-sdk/client-s3";
 
const s3 = new S3Client({});
try {
  await s3.send(new GetObjectCommand({ Bucket: "my-bucket", Key: "missing.txt" }));
} catch (err) {
  if (err instanceof NoSuchKey) console.log("object not found");
  else throw err;
}

• Each client package exports typed exception classes like NoSuchKey.
• Match them with instanceof rather than string-comparing error messages.
• Every error carries err.$metadata.requestId; log it for AWS support cases.
• Rethrow anything you do not specifically handle instead of swallowing it.

Related: SDK v3 Fundamentals Best Practices - error and retry habits.

5. Set Credentials Explicitly

Usually the default chain is enough, but you can pass a provider when you need control.

import { S3Client } from "@aws-sdk/client-s3";
import { fromIni } from "@aws-sdk/credential-providers";
 
const s3 = new S3Client({
  region: "us-east-1",
  credentials: fromIni({ profile: "staging" }),
});

• @aws-sdk/credential-providers is a separate install from the client package.
• fromIni({ profile }) reads a named profile from your shared config files.
• Omit credentials entirely to let the default provider chain resolve them.
• Never hardcode access keys in source; use a provider or an IAM role.

Related: Credential Providers: fromEnv, fromIni, fromNodeProviderChain.

Intermediate Examples

6. Paginate a Large Result Set

List operations return one page at a time; the paginate* helpers walk them for you.

import { S3Client, paginateListObjectsV2 } from "@aws-sdk/client-s3";
 
const s3 = new S3Client({});
const pages = paginateListObjectsV2(
  { client: s3 },
  { Bucket: "my-bucket", Prefix: "logs/" },
);
for await (const page of pages) {
  for (const obj of page.Contents ?? []) console.log(obj.Key, obj.Size);
}

• Import paginate<Operation> from the same client package as an async generator.
• The helper hides the ContinuationToken bookkeeping the raw API requires.
• Each page is a separate HTTPS request, so filter with Prefix to fetch only what you need.
• for await...of consumes the pages lazily, one round trip at a time.

7. Reuse One Client Across Commands and Handlers

A single service client sends every command for that service; reuse it, especially in Lambda.

import { DynamoDBClient, GetItemCommand, PutItemCommand } from "@aws-sdk/client-dynamodb";
 
// Module scope: constructed once, reused by every warm Lambda invocation.
const ddb = new DynamoDBClient({ region: "us-east-1" });
 
export async function handler(id: string) {
  await ddb.send(new PutItemCommand({
    TableName: "Visits",
    Item: { id: { S: id }, count: { N: "1" } },
  }));
  return ddb.send(new GetItemCommand({ TableName: "Visits", Key: { id: { S: id } } }));
}

• One DynamoDBClient sends both PutItemCommand and GetItemCommand.
• Declaring the client at module scope lets warm Lambda invocations reuse it.
• Rebuilding a client per call wastes connection pools and CPU.
• Switching services means a new client package and client, nothing else changes.

Related: SDK v3 Fundamentals Best Practices - client lifecycle rules.

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