What's the Amazon SDK for JavaScript?

Welcome to the Amazon SDK for JavaScript Developer Guide. This guide provides general information about setting up and configuring the Amazon SDK for JavaScript. It also walks you through examples and tutorial of running various Amazon services using the Amazon SDK for JavaScript.

The Amazon SDK for JavaScript v3 API Reference Guide provides a JavaScript API for Amazon services. You can use the JavaScript API to build libraries or applications for Node.js or the browser.

Maintenance and support for SDK major versions

For information about maintenance and support for SDK major versions and their underlying dependencies, see the following in the Amazon SDKs and Tools Reference Guide:

What's new in Version 3

Version 3 of the SDK for JavaScript (V3) contains the following new features.

In addition, the SDK is written in TypeScript, which has many advantages, such as static typing.

Modularized packages

Version 2 of the SDK for JavaScript (V2) required you to use the entire Amazon SDK, as follows.

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

Loading the entire SDK isn’t an issue if your application is using many Amazon services. However, if you need to use only a few Amazon services, it means increasing the size of your application with code you don't need or use.

In V3, you can load and use only the individual Amazon Services you need. This is shown in the following example, which gives you access to Amazon DynamoDB (DynamoDB).

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

Not only can you load and use individual Amazon services, but you can also load and use only the service commands you need. This is shown in the following examples, which gives you access to DynamoDB client and the ListTablesCommand command.

import {
  DynamoDBClient,
  ListTablesCommand
} from "@aws-sdk/client-dynamodb";

import { CognitoIdentity } from "@aws-sdk/client-cognito-identity/CognitoIdentity";

import { CognitoIdentity } from "@aws-sdk/client-cognito-identity";

Comparing code size

In Version 2 (V2), a simple code example that lists all of your Amazon DynamoDB tables in the us-west-2 Region might look like the following.

var AWS = require("aws-sdk");
// Set the Region
AWS.config.update({region: "us-west-2"});
// Create DynamoDB service object
var ddb = new AWS.DynamoDB({ apiVersion: "2012-08-10" });

// Call DynamoDB to retrieve the list of tables
ddb.listTables({ Limit:10 }, function(err, data) {
  if (err) {
    console.log("Error", err.code);
  } else {
    console.log("Tables names are ", data.TableNames);
  }
});

V3 looks like the following.

import {
  DynamoDBClient,
  ListTablesCommand
} from "@aws-sdk/client-dynamodb";
(async function () {
   const dbclient = new DynamoDBClient({ region: 'us-west-2'});
 
  try {
    const results = await dbclient.send(new ListTablesCommand);
    results.TableNames.forEach(function (item, index) {
      console.log(item);
    });
  } catch (err) {
    console.error(err)
  }
})();

The aws-sdk package adds about 40 MB to your application. Replacing var AWS = require("aws-sdk") with import {DynamoDB} from "@aws-sdk/client-dynamodb" reduces that overhead to about 3 MB. Restricting the import to just the DynamoDB client and ListTablesCommand command reduces the overhead to less than 100 KB.

// Load the DynamoDB client and ListTablesCommand command for Node.js
import { 
  DynamoDBClient, 
  ListTablesCommand 
} from "@aws-sdk/client-dynamodb";
const dbclient = new DynamoDBClient({});

Calling commands in V3

You can perform operations in V3 using either V2 or V3 commands. To use V3 commands you import the commands and the required Amazon Services package clients, and run the command using the .send method using the async/await pattern.

To use V2 commands you import the required Amazon Services packages, and run the V2 command directly in the package using either a callback or async/await pattern.

Using V3 commands

V3 provides a set of commands for each Amazon Service package to enable you to perform operations for that Amazon Service. After you install an Amazon Service, you can browse the available commands in your project's node-modules/@aws-sdk/client-PACKAGE_NAME/commands folder.

You must import the commands you want to use. For example, the following code loads the DynamoDB service, and the CreateTableCommand command.

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

To call these commands in the recommended async/await pattern, use the following syntax.

CLIENT.send(new XXXCommand)

For example, the following example creates a DynamoDB table using the recommended async/await pattern.

import { DynamoDB, CreateTableCommand } from "@aws-sdk/client-dynamodb";
const dynamodb = new DynamoDB({region: 'us-west-2'});
var tableParams = {
    Table : TABLE_NAME
};
(async function () => {
      try{
           const data = await dynamodb.send(new CreateTableCommand(tableParams));
           console.log("Success", data);
      } 
      catch (err) {
           console.log("Error", err);
      }
})(); 

Using V2 commands

To use V2 commands in the SDK for JavaScript, you import the full Amazon Service packages, as demonstrated in the following code.

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

To call V2 commands in the recommended async/await pattern, use the following syntax.

client.command(parameters)

The following example uses the V2 createTable command to create a DynamoDB table using the recommended async/await pattern.

const {DynamoDB} = require('@aws-sdk/client-dynamodb');
const dymamoDB = new DynamoDB({region: 'us-west-2'});
var tableParams = {
    TableName : TABLE_NAME
};
async function run() => {
      try {
           const data = await dymamoDB.createTable(tableParams);
           console.log("Success", data);
      } 
      catch (err) {
           console.log("Error", err);
      }
};
run(); 

The following example uses the V2 createBucket command to create an Amazon S3 bucket using the callback pattern.

const {S3} = require('@aws-sdk/client-s3');
const s3 = new S3({region: 'us-west-2'});
var bucketParams = {
    Bucket : BUCKET_NAME
};
function run(){
         s3.createBucket(bucketParams, function(err, data) {
         if (err) {
         console.log("Error", err);
         } else {
         console.log("Success", data.Location);
         }
    })
};

New middleware stack

V2 of the SDK enabled you to modify a request throughout the multiple stages of its lifecycle by attaching event listeners to the request. This approach can make it difficult to debug what went wrong during a request’s lifecycle.

In V3, you can use a new middleware stack to control the lifecycle of an operation call. This approach provides a couple of benefits. Each middleware stage in the stack calls the next middleware stage after making any changes to the request object. This also makes debugging issues in the stack much easier, because you can see exactly which middleware stages were called leading up to the error.

The following example adds a custom header to a Amazon DynamoDB client (which we created and showed earlier) using middleware. The first argument is a function that accepts next, which is the next middleware stage in the stack to call, and context, which is an object that contains some information about the operation being called. The function returns a function that accepts args, which is an object that contains the parameters passed to the operation and the request. It returns the result from calling the next middleware with args.

dbclient.middlewareStack.add(
  (next, context) => args => {
    args.request.headers["Custom-Header"] = "value";
    return next(args);
  },
  {
    step: "build"
  }
);  

dbclient.send(new PutObjectCommand(params));

Using the SDK with Node.js

Node.js is a cross-platform runtime for running server-side JavaScript applications. You can set up Node.js on an Amazon Elastic Compute Cloud (Amazon EC2) instance to run on a server. You can also use Node.js to write on-demand Amazon Lambda functions.

Using the SDK for Node.js differs from the way in which you use it for JavaScript in a web browser. The difference comes from the way in which you load the SDK and in how you obtain the credentials needed to access specific web services. When use of particular APIs differs between Node.js and the browser, we call out those differences.

Using the SDK with Amazon Cloud9

You can also develop Node.js applications using the SDK for JavaScript in the Amazon Cloud9 IDE. For more information about using Amazon Cloud9 with the SDK for JavaScript, see Using Amazon Cloud9 with the Amazon SDK for JavaScript.

Using the SDK with Amazon Amplify

For browser-based web, mobile, and hybrid apps, you can also use the Amazon Amplify library on GitHub. It extends the SDK for JavaScript, providing a declarative interface.

Using the SDK with web browsers

All major web browsers support execution of JavaScript. JavaScript code that is running in a web browser is often called client-side JavaScript.

For a list of browsers that are supported by the Amazon SDK for JavaScript, see Supported web browsers.

Using the SDK for JavaScript in a web browser differs from the way in which you use it for Node.js. The difference comes from the way in which you load the SDK and in how you obtain the credentials needed to access specific web services. When use of particular APIs differs between Node.js and the browser, we call out those differences.

Using browsers in V3

V3 enables you to bundle and include in the browser only the SDK for JavaScript files you require, reducing overhead.

To use V3 of the SDK for JavaScript in your HTML pages, you must bundle the required client modules and all required JavaScript functions into a single JavaScript file using Webpack, and add it in a script tag in the <head> of your HTML pages. For example:

<script src="./main.js"></script>

To use V2 of the SDK for JavaScript, you add a script tag that points to the latest version of the V2 SDK instead. For more information, see the sample in the Amazon SDK for JavaScript Developer Guide v2.

Common use cases

Using the SDK for JavaScript in browser scripts makes it possible to realize a number of compelling use cases. Here are several ideas for things you can build in a browser application by using the SDK for JavaScript to access various web services.

About the examples

You can browse the SDK for JavaScript examples in the Amazon Code Example Repository.

Resources

In addition to this guide, the following online resources are available for SDK for JavaScript developers: