Getting started in Node.js - AWS SDK for JavaScript

Help us improve the AWS SDK for JavaScript version 3 (V3) documentation by providing feedback using the Feedback link, or create an issue or pull request on GitHub.

The AWS SDK for JavaScript V3 API Reference Guide describes in detail all the API operations for the AWS SDK for JavaScript version 3 (V3).

Getting started in Node.js

JavaScript code example that applies to Node.js execution

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 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.

Prerequisite tasks

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

  • Install npm.

  • Set up the project environment to run these Node TypeScript examples, and install the required AWS SDK for JavaScript and third-party modules. Follow the instructions on GitHub.

    Note

    The AWS SDK for JavaScript (V3) is written in TypeScript, so for consistency these examples are presented in TypeScript. TypeScript extends JavaScript, so with minor adjustments these examples can also be run in JavaScript. For more information, see this article in the AWS Developer Blog.

  • 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.

Step 1: Install the Amazon S3 package and dependencies

To install the client package and dependencies:

  1. In the src project directory, there is a package.json file for holding the metadata for your Node.js project.

    Note

    For details about using package.json in a Node.js project, see What is the file package.json?.

    { "name": "aws-sdk-v3-iam-examples", "version": "1.0.0", "main": "index.js", "dependencies": { "@aws-sdk/client-s3": "^3.3.0", "@aws-sdk/node-http-handler": "^^3.3.0", "@aws-sdk/types": "^^3.3.0", "ts-node": "^9.0.0" }, "devDependencies": { "@types/node": "^14.0.23", "typescript": "^4.0.2" } }

    The example code is available here on GitHub.

  2. From the nodegetstarted directory containing the package.json enter the following command.

    npm install

    The packages and dependencies are installed.

    Note

    You can add dependencies to the package.json and install them by running npm install. You can also add dependancies directly through the command line. For example, to install the AWS SDK for JavaScript v3 client module for Amazon DynamoDB, enter the command below in the command line.

    npm install @aws-sdk/client-dynamodb

    The package.json dependencies are automatically updated.

Step 4: Write the Node.js code

Create a file named sample.ts to contain the example code. Begin by adding the require function calls to include the Amazon S3 package.

Create an Amazon S3 bucket in the Amazon Console. For more information, see Create an Amazon Amazon S3 bucket.

Then add a name for the Key parameter used to upload an object to the bucket.

Create the PutObjectCommand object to encapsulate the properties of the associated S3 service object requests. Call the send command with the CreateBucketCommand and PutObjectCommand objects to create a new Amazon S3 bucket and upload the object to it.

// Import required AWS SDK clients and commands for Node.js const { S3Client, PutObjectCommand, CreateBucketCommand } = require("@aws-sdk/client-s3"); // Set the AWS region const REGION = "REGION"; // e.g., "us-east-1" // Set the bucket parameters const bucketName = "BUCKET_NAME"; const bucketParams = { Bucket: bucketName }; // Create name for uploaded object key const keyName = "hello_world.txt"; const objectParams = { Bucket: bucketName, Key: keyName, Body: "Hello World!" }; // Create an S3 client service object const s3 = new S3Client({ region: REGION }); const run = async () => { // Create S3 bucket try { const data = await s3.send(new CreateBucketCommand(bucketParams)); console.log("Success. Bucket created."); } catch (err) { console.log("Error", err); } try { const results = await s3.send(new PutObjectCommand(objectParams)); console.log("Successfully uploaded data to " + bucketName + "/" + keyName); } catch (err) { console.log("Error", err); } }; run();

The example code can be found here on GitHub.

Step 5: Run the example

Enter the following command to run the example.

node sample.js

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