The AWS SDK for JavaScript v2 has reached end-of-support. We recommend that you migrate to AWS SDK for JavaScript v3. For additional details and information on how to migrate, please refer to this announcement.

Getting Started in Node.js

This Node.js code example shows:

The Scenario

The example shows how to set up and run a simple Node.js module that creates an Amazon S3 bucket, then adds a text object to it.

Because bucket names in Amazon S3 must be globally unique, this example includes a third-party Node.js module that generates a unique ID value that you can incorporate into the bucket name. This additional module is named uuid.

Prerequisite Tasks

To set up and run this example, you must first complete these tasks:

Step 1: Install the SDK and Dependencies

You install the SDK for JavaScript package using npm (the Node.js package manager).

From the awsnodesample directory in the package, type the following at the command line.

npm install aws-sdk

This command installs the SDK for JavaScript in your project, and updates package.json to list the SDK as a project dependency. You can find information about this package by searching for "aws-sdk" on the npm website.

Next, install the uuid module to the project by typing the following at the command line, which installs the module and updates package.json. For more information about uuid, see the module's page at https://www.npmjs.com/package/uuid.

npm install uuid

These packages and their associated code are installed in the node_modules subdirectory of your project.

For more information on installing Node.js packages, see Downloading and installing packages locally and Creating Node.js Modules on the npm (Node.js package manager) website. For information about downloading and installing the AWS SDK for JavaScript, see Installing the SDK for JavaScript.

Step 2: Configure Your Credentials

You need to provide credentials to AWS so that only your account and its resources are accessed by the SDK. For more information about obtaining your account credentials, see SDK authentication with AWS.

To hold this information, we recommend you create a shared credentials file. To learn how, see Loading Credentials in Node.js from the Shared Credentials File. Your credentials file should resemble the following example.

[default]
aws_access_key_id = YOUR_ACCESS_KEY_ID
aws_secret_access_key = YOUR_SECRET_ACCESS_KEY

You can determine whether you have set your credentials correctly by executing the following code with Node.js:

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

AWS.config.getCredentials(function(err) {
  if (err) console.log(err.stack);
  // credentials not loaded
  else {
    console.log("Access key:", AWS.config.credentials.accessKeyId);
  }
});

Similarly, if you have set your region correctly in your config file, you can display that value by setting the AWS_SDK_LOAD_CONFIG environment variable to any value and using the following code:

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

console.log("Region: ", AWS.config.region);

Step 3: Create the Package JSON for the Project

After you create the awsnodesample project directory, you create and add a package.json file for holding the metadata for your Node.js project. For details about using package.json in a Node.js project, see Creating a package.json file.

In the project directory, create a new file named package.json. Then add this JSON to the file.

{
  "dependencies": {},
  "name": "aws-nodejs-sample",
  "description": "A simple Node.js application illustrating usage of the SDK for JavaScript.",
  "version": "1.0.1",
  "main": "sample.js",
  "devDependencies": {},
  "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1"
  },
  "author": "NAME",
  "license": "ISC"
}

Save the file. As you install the modules you need, the dependencies portion of the file will be completed. You can find a JSON file that shows an example of these dependencies here on GitHub.

Step 4: Write the Node.js Code

Create a new file named sample.js to contain the example code. Begin by adding the require function calls to include the SDK for JavaScript and uuid modules so that they are available for you to use.

Build a unique bucket name that is used to create an Amazon S3 bucket by appending a unique ID value to a recognizable prefix, in this case 'node-sdk-sample-'. You generate the unique ID by calling the uuid module. Then create a name for the Key parameter used to upload an object to the bucket.

Create a promise object to call the createBucket method of the AWS.S3 service object. On a successful response, create the parameters needed to upload text to the newly created bucket. Using another promise, call the putObject method to upload the text object to the bucket.

// Load the SDK and UUID
var AWS = require("aws-sdk");
var uuid = require("uuid");

// Create unique bucket name
var bucketName = "node-sdk-sample-" + uuid.v4();
// Create name for uploaded object key
var keyName = "hello_world.txt";

// Create a promise on S3 service object
var bucketPromise = new AWS.S3({ apiVersion: "2006-03-01" })
  .createBucket({ Bucket: bucketName })
  .promise();

// Handle promise fulfilled/rejected states
bucketPromise
  .then(function (data) {
    // Create params for putObject call
    var objectParams = {
      Bucket: bucketName,
      Key: keyName,
      Body: "Hello World!",
    };
    // Create object upload promise
    var uploadPromise = new AWS.S3({ apiVersion: "2006-03-01" })
      .putObject(objectParams)
      .promise();
    uploadPromise.then(function (data) {
      console.log(
        "Successfully uploaded data to " + bucketName + "/" + keyName
      );
    });
  })
  .catch(function (err) {
    console.error(err, err.stack);
  });

This sample code can be found here on GitHub.

Step 5: Run the Sample

Type the following command to run the sample.

node sample.js

If the upload is successful, you'll see a confirmation message at the command line. You can also find the bucket and the uploaded text object in the Amazon S3 console.