Modular AWS SDK for JavaScript is now generally available

We are happy to announce the General Availability (GA) of AWS SDK for JavaScript, version 3 (v3). This release follows the Release Candidate of the JavaScript SDK and 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.

You can download modular AWS SDK for Javascript from npm today, and we support Node.js v 10.0.0+, browsers compatible with ECMAScript version 5 (ES5) and React Native 0.59+.

What’s New

Modular Packages

AWS SDK for Javascript v2 publishes a single npm package that supports all the AWS services. This makes it easy to use multiple services in a project at the cost of a large dependency when only using a handful of services or operations. In resource constrained environment such as mobile devices, having separate packages for each service client allows optimizing the dependency. The AWS SDK for Javascript v3 provides such modular packages. 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 that sends responses in JSON will no longer need to also have an XML parser as a dependency.

Here’s a quick example comparing v2 and v3 of the AWS SDK for Javascript. In v2, the S3 client can be created using single monolithic package:

const AWS = require("aws-sdk");

const s3Client = new AWS.S3({});
await s3Client.createBucket(params).promise();

In v3, the service clients are prefixed with client- followed by service name. So you can create the modular S3 client by importing @aws-sdk/client-s3:

const { S3 } = require("@aws-sdk/client-s3");

const s3Client = new S3({});
await s3Client.createBucket(params);

The blog post on modular packages in AWS SDK for JavaScript provides details on other modular packages in the SDK and shows an example of performance improvement due to bundle size reduction.

Middleware Stack

Version 2 of the SDK allows modifying a request throughout multiple stages of a request’s lifecycle by attaching event listeners to a request. It can be difficult to debug what went wrong during a request’s lifecycle using event listeners.

In version 3, we’ve switched to using a middleware stack to control the lifecycle of an operation call. This gives us several benefits: each middleware in the stack calls the next middleware after making any changes to the request object. This makes debugging issues in the stack much easier since you can see exactly which middleware was called leading up to an error.

Here’s an example of adding a custom header using middleware:

const { S3 } = require("@aws-sdk/client-s3");
const client = new S3({ region: "us-west-2" });

client.middlewareStack.add(
  (next, context) => async (args) => {
    args.request.headers["x-amz-meta-foo"] = "bar";
    const result = next(args);
    // result.response contains data returned from next middleware.
    return result;
  },
  {
    step: "build",
    name: "addFooMetadataMiddleware",
    tags: ["METADATA", "FOO"],
  }
);

await client.putObject(params);

The blog post on Middleware Stack in Modular AWS SDK for JavaScript does a deep dive on writing middleware and plugins.

First-class TypeScript support

Version 2 of the SDK is written in vanilla JavaScript. Typescript definition files were added in late 2016, when our customers requested type support after Angular 2 started recommending TypeScript as a primary language for application development. The internal components of the SDK are still written in vanilla JavaScript, and type definitions can go out of date.

The TypeScript programming language extends JavaScript by adding types, and saves you time catching errors and providing fixes before you run your code. We used TypeScript in the JavaScript SDK to benefit from its static type definitions, latest ECMAScript features, IDE support like Intellisense and improved documentation support. The blog post on first-class TypeScript support covers the benefits of TypeScript in the SDK in detail. Although the SDK is written in TypeScript, you can use vanilla JavaScript in your code.

Additional features

We also added many other features, which we are planning to cover in detail in future blog posts:

New retry behavior with congestion control to accommodate throttling responses, and retry quotas to limit the number of failed retries.
Pagination using async generators.
Extensive logging support to record API input/output and corresponding metadata.
Utility functions to operate with JavaScript objects in DynamoDB.
Higher order operation for multipart upload.
Bi-directional transcribe streaming over WebSockets.
Support for HTTP/2.
AbortController interface to abort requests as and when desired.
Keep Node.js HTTP connections alive by default.

Platform Support

The modular AWS SDK for JavaScript officially supports Node.js, browser and React Native environments.

Minimum supported version for Node.js is 10.x

On December 31st, 2019 Node.js 8.x reached End of Life (EOL). We have therefore updated the minimum requirements for AWS SDK for JavaScript version 3 to Node.js 10.x. If you are currently using earlier versions of Node.js, please upgrade and refer to the Node.js 10.x release announcement for notable changes.

Minimum supported version for browsers is ECMAScript version 5 (ES5)

We continue to support ECMAScript version 5 (ES5) on browsers, including these minimum versions.

Browser	Version
Internet Explorer	10+
Microsoft Edge	12+
Mozilla Firefox	21+
Google Chrome	23+
Apple Safari	6+
Opera	15+
Android browser	4.4+

Minimum supported version for React Native is 0.59.0

The React Native support in the SDK is added to assist AWS Amplify – a high level library built on top of the SDK. We support React Native versions 0.59.0 and above.

What’s missing in v3

The following features are not available in version 3 yet, we are working to add support for them::

Contact us

We value your feedback, so please tell us what you like and don’t like by opening an issue on GitHub. If you have ideas for version 3 or future versions, do create a Discussion on GitHub or upvote existing ideas.