AWS SDK v2 to v3 Converter for JavaScript & TypeScript

How to convert AWS SDK v2 code to v3

To convert AWS SDK v2 code to v3, paste the code into the editor above and press Convert to v3. The converter replaces each aws-sdk service object with a v3 client, turns each method call into client.send(new SomethingCommand(params)) and removes .promise(). Then install the @aws-sdk/* packages the result imports and run your tests.

1. Add your v2 codePaste it into the AWS SDK v2 (JS/TS) editor, use Paste, Open file (.js, .mjs, .cjs, .jsx, .ts, .tsx or .txt, up to 500 KB) or drag a file onto the editor. Sample loads a DynamoDB and S3 example.
2. Let the secret check runBefore anything is sent, the page looks for AWS access keys, secret keys, private keys and common API tokens in your code. If it finds one, it shows you where so you can swap it for a placeholder.
3. Convert to v3Click Convert to v3 or press Ctrl + Enter. The v3 code streams into the right-hand editor, and you can stop it at any time. Each conversion takes up to 60,000 characters, so convert one file or module at a time.
4. Review the resultRead the output side by side with your original. Look for TODO: comments, which mark places without a direct v3 equivalent. Use Wrap for long lines, then Copy or Download it as converted-v3.js.
5. Install the clients and testAdd each package the new imports use, for example npm install @aws-sdk/client-s3, then run your tests before you remove aws-sdk from package.json.

How this converter helps with your SDK v3 migration

AWS SDK for JavaScript v2 no longer gets updates or security fixes, and AWS Lambda's Node.js runtimes from nodejs18.x onward include SDK v3 but not v2. A function that imports aws-sdk fails on those runtimes unless you bundle v2 yourself. Moving to v3 is usually the simpler fix.

The migration is mostly mechanical, but there's a lot of it: every import, every client, every call. This converter does that rewrite for one file at a time, so you can spend your time on the parts that need judgment, such as S3 streams, pagination and error handling. It's useful when you're upgrading a Lambda runtime, maintaining an older Node.js service, reviewing a migration pull request, or just want to see what the v3 version of a snippet looks like.

For a large codebase, pair it with AWS's aws-sdk-js-codemod: run the codemod for bulk changes, then use this page for the files it can't convert cleanly.

What changes between AWS SDK v2 and v3

Version 3 of the AWS SDK for JavaScript splits the single aws-sdk package into one package per service, such as @aws-sdk/client-s3. Instead of calling s3.getObject(params).promise(), you create a client and send it a command: client.send(new GetObjectCommand(params)). The converter makes these changes for you: imports, client construction, command classes and the removal of .promise().

A few differences need more than a find-and-replace. DynamoDB's DocumentClient becomes DynamoDBDocumentClient from @aws-sdk/lib-dynamodb. S3 object bodies arrive as streams instead of Buffers, so you read them with Body.transformToString() or transformToByteArray(). Pagination moves to built-in helpers such as paginateListObjectsV2. Check each of these in the converted code. AWS's official migration guide covers the full list.

AWS SDK v2 vs v3: quick reference

The most common v2 patterns and what they become in v3. The converter applies these for you. The rows from DynamoDB down are the ones most worth checking by hand.

Key features

• Imports, clients and calls rewrittenaws-sdk imports become @aws-sdk/client-* imports, service objects become v3 clients, and method calls become commands sent with client.send().
• Your code stays recognizableVariable names, function structure and comments are kept wherever they still apply, so the diff is easy to review.
• Gaps are flagged, not hiddenWhen something has no direct v3 equivalent, the output includes a TODO: comment that says what to check.
• JavaScript and TypeScriptWorks with .js, .mjs, .cjs, .jsx, .ts and .tsx code. TypeScript input comes back as TypeScript.
• Secret check before sendingAWS access keys, secret keys, private keys and common API tokens are detected in your browser before any code leaves it.
• Streaming outputThe v3 code appears as it's written. Stop the conversion at any point if you pasted the wrong file.
• Copy or downloadCopy the result, or download it as converted-v3.js. Wrap long lines to read them without scrolling.
• Free, with no signupConvert straight away. A free account raises your limits and keeps a list of your recent conversions.

Examples: AWS SDK v2 code converted to v3

Three patterns that need more than renaming. Each shows v2 code and the v3 code it should become. Choose Try this example to load the v2 version into the converter. Your output may be formatted differently.

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

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

export function getUploadUrl(key) {
  return s3.getSignedUrlPromise("putObject", {
    Bucket: "uploads",
    Key: key,
    ContentType: "image/png",
    Expires: 900,
  });
}

import { S3Client, PutObjectCommand } from "@aws-sdk/client-s3";
import { getSignedUrl } from "@aws-sdk/s3-request-presigner";

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

export function getUploadUrl(key) {
  const command = new PutObjectCommand({
    Bucket: "uploads",
    Key: key,
    ContentType: "image/png",
  });
  return getSignedUrl(client, command, { expiresIn: 900 });
}

import S3 from "aws-sdk/clients/s3";
import fs from "node:fs";

const s3 = new S3();

export async function uploadBackup(path) {
  const result = await s3
    .upload({
      Bucket: "backups",
      Key: "db/latest.sql.gz",
      Body: fs.createReadStream(path),
    })
    .promise();

  return result.Location;
}

import { S3Client } from "@aws-sdk/client-s3";
import { Upload } from "@aws-sdk/lib-storage";
import fs from "node:fs";

const client = new S3Client({});

export async function uploadBackup(path) {
  const upload = new Upload({
    client,
    params: {
      Bucket: "backups",
      Key: "db/latest.sql.gz",
      Body: fs.createReadStream(path),
    },
  });

  const result = await upload.done();
  return result.Location;
}

import Lambda from "aws-sdk/clients/lambda";

const lambda = new Lambda();

export async function resizeImage(key) {
  const res = await lambda
    .invoke({
      FunctionName: "resize-image",
      Payload: JSON.stringify({ key }),
    })
    .promise();

  return JSON.parse(res.Payload);
}

import { LambdaClient, InvokeCommand } from "@aws-sdk/client-lambda";

const client = new LambdaClient({});

export async function resizeImage(key) {
  const res = await client.send(
    new InvokeCommand({
      FunctionName: "resize-image",
      Payload: new TextEncoder().encode(JSON.stringify({ key })),
    })
  );

  return JSON.parse(new TextDecoder().decode(res.Payload));
}

Tips for better results

• Convert one module at a time. A single file with its imports converts more reliably than a whole project pasted at once.
• Keep the import lines. They tell the converter which services and client styles you use, such as DocumentClient versus the low-level DynamoDB client.
• Include the helper functions a call depends on. If a function builds the params or handles the response, paste it too so both sides change together.
• Search the output for TODO comments. Lines starting with TODO: mark the spots the converter couldn't map one-to-one.
• Run your tests. Mock libraries change too: aws-sdk-client-mock replaces most v2 mocking approaches.

Common mistakes to avoid

• Treating an S3 Body as a Buffer. In v3 it's a stream. Call await Body.transformToString() or transformToByteArray() before you parse it.
• Checking err.code. v3 errors use err.name, such as NoSuchKey, and the HTTP status is in err.$metadata.httpStatusCode.
• Relying on AWS.config. There's no global config in v3. Pass the region and credentials to each client, or set AWS_REGION in the environment.
• Creating a client inside every Lambda invocation. Create v3 clients once, outside the handler, so they're reused across invocations.
• Sending undefined values to DynamoDB. @aws-sdk/lib-dynamodb throws on them by default. Remove them, or set marshallOptions: { removeUndefinedValues: true }.
• Forgetting a package. Every @aws-sdk/* import in the converted code, including lib-dynamodb, lib-storage and s3-request-presigner, is a separate npm install.

Frequently asked questions

Related tools and next steps

• AWS SDK v3 to v2 converterGo the other way when you need to match an older codebase or runtime.
• Boto3 to AWS SDK v3 converterPort Python boto3 scripts straight to JavaScript v3 clients.
• IAM policy from TypeScript codePaste your converted v3 code to get a least-privilege IAM policy for the calls it makes.
• All AWS code convertersSDKs, infrastructure as code and IAM policy generators in one place.
• Practical AWS examplesWorked examples of everyday AWS tasks.
• How ChatWithCloud worksAsk questions about your live AWS account in plain English from your terminal.
• Upload a file to S3 with SDK v3A complete S3Client example, including large files with lib-storage.
• Invoke Lambda with SDK v3InvokeCommand with payload encoding, async invokes and error handling.