AWS SDK v3 to v2 Converter for JavaScript

How to convert AWS SDK v3 code to v2

To convert AWS SDK v3 code to v2, paste it into the editor above and press Convert to v2. Each client.send(new SomeCommand(params)) becomes the matching v2 method with .promise(), and the @aws-sdk/* imports become aws-sdk imports. Then make sure aws-sdk is installed or bundled, and test.

1. Add the v3 codePaste it into the AWS SDK v3 (JS/TS) editor, use Paste or Open file (.js, .mjs, .cjs, .jsx, .ts, .tsx or .txt, up to 500 KB), or drop a file on the editor. Sample loads an SQS and DynamoDB order processor.
2. Let the secret check runBefore the code leaves your browser, the page scans it for AWS access keys, secret keys, private keys and common API tokens. If it finds one, it highlights the match so you can replace it with a placeholder.
3. Convert to v2Click Convert to v2 or press Ctrl + Enter. The v2 code streams into the right-hand editor, and Stop cancels it. Up to 60,000 characters fit in one conversion.
4. Check the tricky partsCompare the result with your original, paying attention to paginator loops, error checks and S3 bodies. TODO: comments mark places with no direct v2 equivalent. Copy the code or download it as converted-v2.js.
5. Install or bundle aws-sdk and testAdd aws-sdk to package.json if it isn't there. On Lambda's Node.js 18 and later runtimes, bundle it with your function, because those runtimes don't include v2.

When converting AWS SDK v3 code to v2 still makes sense

Most migrations go the other way, and for new code you should use v3. But some projects can't switch yet: an older service built around shared v2 helpers, a plugin or framework that expects a v2 client object, or a service stuck on an older Node.js version that current v3 releases no longer support. When you find a v3 example in the AWS docs or another repository and need it to fit that code today, rewriting it by hand is slow and easy to get subtly wrong.

This converter does that rewrite for one file or snippet at a time, keeping your function names, structure and comments so the change is easy to review. It's most useful for hotfixes and small additions to a legacy service, where adding a second SDK would complicate the release.

Because v2 no longer gets security fixes, keep a note of every file you convert. When the project is ready, the AWS SDK v2 to v3 converter takes the same code forward again.

How AWS SDK v3 code maps back to v2

In v3, you create a client per service and send it command objects. In v2, one service object exposes a method per API operation, and you call .promise() to get a promise. So await s3.send(new GetObjectCommand(params)) becomes await s3.getObject(params).promise(), with the same parameter names. Separate @aws-sdk/client-* imports become require("aws-sdk") or a per-service import such as aws-sdk/clients/s3.

Helpers that only exist in v3 need more than renaming. Paginators such as paginateListObjectsV2 become loops that pass NextContinuationToken (or NextToken) into the next request. Custom middleware becomes request event listeners. DynamoDBDocumentClient commands like GetCommand become DocumentClient methods like get(). Errors are identified by err.code instead of err.name or exception classes.

What to check when moving code from v3 to v2

Most calls translate one-to-one. These are the places where the v2 version behaves differently and deserves a closer look.

Key features

• Commands become v2 methodsEach client.send(new XCommand(params)) becomes the matching v2 service method with .promise(), keeping the same parameters.
• Paginators rewritten as token loopsv3 paginate* helpers become explicit loops over the continuation token, since most v2 clients have no equivalent.
• DocumentClient mapping@aws-sdk/lib-dynamodb commands such as PutCommand and QueryCommand become DocumentClient methods like put() and query().
• Error checks translatederr.name comparisons and exception classes become err.code checks, which is how v2 reports error types.
• Gaps flagged in the codeWhere v3 behavior has no v2 equivalent, the output carries a TODO: comment explaining what to check.
• Checked for secrets firstAccess keys, secret keys, private keys and common tokens are detected in your browser before any code is sent.
• Free, no signupConvert straight away, then copy or download the result. A free account raises your limits.

Examples: AWS SDK v3 code converted to v2

Three patterns you're likely to meet when backporting. Choose Try this example to load the v3 version into the converter. Your output may be formatted differently.

import { DynamoDBClient } from "@aws-sdk/client-dynamodb";
import { DynamoDBDocumentClient, GetCommand } from "@aws-sdk/lib-dynamodb";

const ddb = DynamoDBDocumentClient.from(new DynamoDBClient({}));

export async function getUser(userId) {
  const { Item } = await ddb.send(
    new GetCommand({ TableName: "users", Key: { userId } })
  );
  return Item;
}

import DynamoDB from "aws-sdk/clients/dynamodb";

const ddb = new DynamoDB.DocumentClient();

export async function getUser(userId) {
  const { Item } = await ddb
    .get({ TableName: "users", Key: { userId } })
    .promise();
  return Item;
}

import { S3Client, paginateListObjectsV2 } from "@aws-sdk/client-s3";

const client = new S3Client({});

export async function listKeys(bucket, prefix) {
  const keys = [];
  for await (const page of paginateListObjectsV2({ client }, { Bucket: bucket, Prefix: prefix })) {
    for (const obj of page.Contents ?? []) keys.push(obj.Key);
  }
  return keys;
}

import S3 from "aws-sdk/clients/s3";

const s3 = new S3();

export async function listKeys(bucket, prefix) {
  const keys = [];
  let token;
  do {
    const page = await s3
      .listObjectsV2({ Bucket: bucket, Prefix: prefix, ContinuationToken: token })
      .promise();
    for (const obj of page.Contents ?? []) keys.push(obj.Key);
    token = page.NextContinuationToken;
  } while (token);
  return keys;
}

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

const s3 = new S3Client({ region: "us-east-1" });

export async function loadConfig(key) {
  try {
    const res = await s3.send(new GetObjectCommand({ Bucket: "app-config", Key: key }));
    return JSON.parse(await res.Body.transformToString());
  } catch (err) {
    if (err.name === "NoSuchKey") return {};
    throw err;
  }
}

import S3 from "aws-sdk/clients/s3";

const s3 = new S3({ region: "us-east-1" });

export async function loadConfig(key) {
  try {
    const res = await s3.getObject({ Bucket: "app-config", Key: key }).promise();
    return JSON.parse(res.Body.toString("utf-8"));
  } catch (err) {
    if (err.code === "NoSuchKey") return {};
    throw err;
  }
}

Tips for better results

• Paste the imports with the code. They show which clients you use, and whether DynamoDB calls go through lib-dynamodb or the low-level client.
• Match the module style of the target file. If the legacy project uses require(), say so in a comment at the top, or adjust the imports after converting.
• Test pagination with more than one page. A token loop that works on a single page can still stop early or loop forever if the token handling is off.
• Re-add TypeScript types if you need them. TypeScript input can come back as plain JavaScript. v2 ships its own typings, such as S3.GetObjectOutput, which replace v3's GetObjectCommandOutput.
• Keep v2 and v3 separate. They can live in one project, but don't pass a v3 client into v2 helpers or the other way round.

Common mistakes when backporting to v2

• Leaving transformToString() on an S3 body. v2 returns a Buffer, which has no such method, so the call throws at runtime.
• Checking err.name or instanceof. v2 errors carry the type in err.code, such as NoSuchKey or ConditionalCheckFailedException.
• Assuming Lambda provides aws-sdk. Node.js 18 and later Lambda runtimes include only SDK v3. Bundle v2 with the function, or the import fails.
• Forgetting .promise(). Without it, await gets a v2 Request object instead of the response.
• Mixing DocumentClient and low-level shapes. The DocumentClient takes plain values like { userId: "42" }. The low-level client expects typed attributes like { userId: { S: "42" } }.

Frequently asked questions

Related tools and next steps

• AWS SDK v2 to v3 converterMove the same code forward to v3 when the project is ready.
• IAM policy from TypeScript codeGet an IAM policy for the S3, DynamoDB or SQS calls your code makes.
• AWS SDK JavaScript to boto3Port the same AWS logic to a Python script or Lambda function.
• All AWS code convertersSDK, infrastructure-as-code and IAM tools in one place.
• How ChatWithCloud worksAsk questions about your live AWS resources in plain English.