getting-started-nodejs.md

Getting Started in Node.js

This Node.js code example shows:

• How to create the package.json manifest for your project.
• How to install and include the modules that your project uses.
• How to create an Amazon Simple Storage Service (Amazon S3) service object from the AWS.S3 client class.
• How to create an Amazon S3 bucket and upload an object to that bucket.

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:

• Create a working directory for developing your Node.js module. Name this directory awsnodesample.
• Install Node.js. For more information, see the Node.js website. You can find downloads of the current and LTS versions of Node.js for a variety of operating systems at https://nodejs.org/en/download/current/.

Contents

• The Scenario
• Prerequisite Tasks
• Step 1: Configure Your Credentials
• Step 2: Create the Package JSON for the Project
• Step 3: Install the SDK and Dependencies
• Step 4: Write the Node.js Code
• Step 5: Run the Sample

Step 1: 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 Getting Your Credentials.

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

Step 2: 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 What is the file package.json? on the docs.nodejitsu.com site.

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

{
  "dependencies": {},
  "name": "awsnodesample",
  "description": "A simple Node.js application showing usage of the AWS SDK for Node.js.",
  "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 the final JSON file here on GitHub.

Step 3: 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.

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 How to Install Local Packages and How to Create Node.js Modules at 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 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 they are available for you to use.

Build a unique bucket name that's 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.