AWS SDK for JavaScript v3

Build Status

The AWS SDK for JavaScript v3 is a rewrite of v2 with some great new features. As with version 2, it enables you to easily work with Amazon Web Services, but has a modular architecture with a separate package for each service. It also includes many frequently requested features, such as a first-class TypeScript support and a new middleware stack. For more details, visit blog post on general availability of Modular AWS SDK for JavaScript.

To get started with JavaScript SDK version 3, visit our Developer Guide or API Reference.

If you are starting a new project with AWS SDK for JavaScript v3, then you can refer aws-sdk-js-notes-app which shows examples of calling multiple AWS Services in a note taking application. If you are migrating from v2 to v3, then you can visit our self-guided workshop which builds as basic version of note taking application using AWS SDK for JavaScript v2 and provides step-by-step migration instructions to v3.

To test your universal JavaScript code in Node.js, browser and react-native environments, visit our code samples repo.

Performance is crucial for the AWS SDK for JavaScript because it directly impacts the user experience. Please refer to Performance section to know more.

Getting Started
New Features
High Level Concepts in V3
Working with the SDK in Lambda
Performance
Install from Source
Giving feedback and contributing
Release Cadence
Node.js versions
Stability of Modular Packages
Known Issues
1. Functionality requiring AWS Common Runtime (CRT)

Getting Started

Let’s walk through setting up a project that depends on DynamoDB from the SDK and makes a simple service call. The following steps use yarn as an example. These steps assume you have Node.js and yarn already installed.

Create a new Node.js project.
Inside of the project, run: yarn add @aws-sdk/client-dynamodb. Adding packages results in update in lock file, yarn.lock or package-lock.json. You should commit your lock file along with your code to avoid potential breaking changes.
Create a new file called index.js, create a DynamoDB service client and send a request.

const { DynamoDBClient, ListTablesCommand } = require("@aws-sdk/client-dynamodb");

(async () => {
  const client = new DynamoDBClient({ region: "us-west-2" });
  const command = new ListTablesCommand({});
  try {
    const results = await client.send(command);
    console.log(results.TableNames.join("\n"));
  } catch (err) {
    console.error(err);
  }
})();

If you want to use non-modular (v2-like) interfaces, you can import client with only the service name (e.g DynamoDB), and call the operation name directly from the client:

const { DynamoDB } = require("@aws-sdk/client-dynamodb");

(async () => {
  const client = new DynamoDB({ region: "us-west-2" });
  try {
    const results = await client.listTables({});
    console.log(results.TableNames.join("\n"));
  } catch (err) {
    console.error(err);
  }
})();

If you use tree shaking to reduce bundle size, using non-modular interface will increase the bundle size as compared to using modular interface.

If you are consuming modular AWS SDK for JavaScript on react-native environments, you will need to add and import following polyfills in your react-native application:

import "react-native-get-random-values";
import "react-native-url-polyfill/auto";
import "web-streams-polyfill/dist/polyfill";

import { DynamoDB } from "@aws-sdk/client-dynamodb";

Specifically Metro bundler used by react-native, enable Package Exports Support:

New features

Modularized packages

The SDK is now split up across multiple packages. The 2.x version of the SDK contained support for every service. This made it very easy to use multiple services in a project. Due to the limitations around reducing the size of the SDK when only using a handful of services or operations, many customers requested having separate packages for each service client. We have also split up the core parts of the SDK so that service clients only pull in what they need. For example, a service sends responses in JSON will no longer need to also have an XML parser as a dependency.

For those that were already importing services as sub-modules from the v2 SDK, the import statement doesn’t look too different. Here’s an example of importing the AWS Lambda service in v2 of the SDK, and the v3 SDK:

// import the Lambda client constructor in v2 of the SDK
const Lambda = require("aws-sdk/clients/lambda");

// import the Lambda client constructor in v3 SDK
const { Lambda } = require("@aws-sdk/client-lambda");

It is also possible to import both versions of the Lambda client by changing the variable name the Lambda constructor is stored in.

API changes

We’ve made several public API changes to improve consistency, make the SDK easier to use, and remove deprecated or confusing APIs. The following are some of the big changes included in the new AWS SDK for JavaScript v3.

Configuration

In version 2.x of the SDK, service configuration could be passed to individual client constructors. However, these configurations would first be merged automatically into a copy of the global SDK configuration: AWS.config.

Also, calling AWS.config.update({/* params */}) only updated configuration for service clients instantiated after the update call was made, not any existing clients.

This behavior was a frequent source of confusion, and made it difficult to add configuration to the global object that only affects a subset of service clients in a forward-compatible way. In v3, there is no longer a global configuration managed by the SDK. Configuration must be passed to each service client that is instantiated. It is still possible to share the same configuration across multiple clients but that configuration will not be automatically merged with a global state.

Middleware

Version 2.x of the SDK allows modifying a request throughout multiple stages of a request’s lifecycle by attaching event listeners to a request. Some feedback we received frequently was that it can be difficult to debug what went wrong during a request’s lifecycle. We’ve switched to using a middleware stack to control the lifecycle of an operation call now. This gives us a few benefits. Each middleware in the stack calls the next middleware after making any changes to the request object. This also makes debugging issues in the stack much easier since you can see exactly which middleware have been called leading up to an error. Here’s an example of logging requests using middleware:

const client = new DynamoDB({ region: "us-west-2" });

client.middlewareStack.add(
  (next, context) => async (args) => {
    console.log("AWS SDK context", context.clientName, context.commandName);
    console.log("AWS SDK request input", args.input);
    const result = await next(args);
    console.log("AWS SDK request output:", result.output);
    return result;
  },
  {
    name: "MyMiddleware",
    step: "build",
    override: true,
  }
);

await client.listTables({});

In the above example, we’re adding a middleware to our DynamoDB client’s middleware stack. The first argument is a function that accepts next, the next middleware in the stack to call, and context, an object that contains some information about the operation being called. It returns a function that accepts args, an object that contains the parameters passed to the operation and the request, and returns the result from calling the next middleware with args.

Other Changes

If you are looking for a breakdown of the API changes from AWS SDK for JavaScript v2 to v3, we have them listed in UPGRADING.md.

Working with the SDK in Lambda

General Info

The Lambda provided AWS SDK is set to a specific minor version, and NOT the latest version. To check the minor version used by Lambda, please refer to Lambda runtimes doc page. If you wish to use the latest / different version of the SDK from the one provided by lambda, we recommend that you bundle and minify your project, or upload it as a Lambda layer.

The performance of the AWS SDK for JavaScript v3 on node 18 has improved from v2 as seen in the performance benchmarking

Best practices

When using Lambda we should use a single SDK client per service, per region, and initialize it outside of the handler's codepath. This is done to optimize for Lambda's container reuse.

The API calls themselves should be made from within the handler's codepath. This is done to ensure that API calls are signed at the very last step of Lambda's execution cycle, after the Lambda is "hot" to avoid signing time skew.

Example:

import { STSClient, GetCallerIdentityCommand } from "@aws-sdk/client-sts";

const client = new STSClient({}); // SDK Client initialized outside the handler

export const handler = async (event) => {
  const response = {
    statusCode: 200,
    headers: {
      "Content-Type": "application/json",
    },
  };

  try {
    const results = await client.send(new GetCallerIdentityCommand({})); // API operation made from within the handler
    const responseBody = {
      userId: results.UserId,
    };

    response.body = JSON.stringify(responseBody);
  } catch (err) {
    console.log("Error:", err);
    response.statusCode = 500;
    response.body = JSON.stringify({
      message: "Internal Server Error",
    });
  }

  return response;
};

Performance

Please refer to supplemental docs on performance to know more.

Install from Source

All clients have been published to NPM and can be installed as described above. If you want to play with latest clients, you can build from source as follows:

Clone this repository to local by:

git clone https://github.com/aws/aws-sdk-js-v3.git

Under the repository root directory, run following command to link and build the whole library, the process may take several minutes:
```
yarn && yarn test:all
```
For more information, please refer to contributing guide.
After the repository is successfully built, change directory to the client that you want to install, for example:
```
cd clients/client-dynamodb
```
Pack the client:
```
yarn pack .
```
yarn pack will create an archive file in the client package folder, e.g. aws-sdk-client-dynamodb-v3.0.0.tgz.
Change directory to the project you are working on and move the archive to the location to store the vendor packages:
```
mv path/to/aws-sdk-js-v3/clients/client-dynamodb/aws-sdk-client-dynamodb-v3.0.0.tgz ./path/to/vendors/folder
```

Install the package to your project:

yarn add ./path/to/vendors/folder/aws-sdk-client-dynamodb-v3.0.0.tgz

Giving feedback and contributing

You can provide feedback to us in several ways. Both positive and negative feedback is appreciated. If you do, please feel free to open an issue on our GitHub repository. Our GitHub issues page also includes work we know still needs to be done to reach full feature parity with v2 SDK.

Feedback

GitHub issues. Customers who are comfortable giving public feedback can open a GitHub issue in the new repository. This is the preferred mechanism to give feedback so that other customers can engage in the conversation, +1 issues, etc. Issues you open will be evaluated, and included in our roadmap for the GA launch.

Gitter channel. For informal discussion or general feedback, you may join the Gitter chat. The Gitter channel is also a great place to get help with v3 from other developers. JS SDK team doesn't track the discussion daily, so feel free to open a GitHub issue if your question is not answered there.

Contributing

You can open pull requests for fixes or additions to the new AWS SDK for JavaScript v3. All pull requests must be submitted under the Apache 2.0 license and will be reviewed by an SDK team member prior to merging. Accompanying unit tests are appreciated. See Contributing for more information.

High Level Concepts

This is an introduction to some of the high level concepts behind AWS SDK for JavaScript (v3) which are shared between services and might make your life easier. Please consult the user guide and API reference for service specific details.

Terminology:

Bare-bones clients/commands: This refers to a modular way of consuming individual operations on JS SDK clients. It results in less code being imported and thus more performant. It is otherwise equivalent to the aggregated clients/commands.

// this imports a bare-bones version of S3 that exposes the .send operation
import { S3Client } from "@aws-sdk/client-s3"

// this imports just the getObject operation from S3
import { GetObjectCommand } from "@aws-sdk/client-s3"

//usage
const bareBonesS3 = new S3Client({...});
await bareBonesS3.send(new GetObjectCommand({...}));

Aggregated clients/commands: This refers to a way of consuming clients that contain all operations on them. Under the hood this calls the bare-bones commands. This imports all commands on a particular client and results in more code being imported and thus