Setting the Amazon Region - Amazon SDK for JavaScript
Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China (PDF).

We announced the upcoming end-of-support for Amazon SDK for JavaScript v2. We recommend that you migrate to Amazon SDK for JavaScript v3. For dates, additional details, and information on how to migrate, please refer to the linked announcement.

Setting the Amazon Region

A Region is a named set of Amazon resources in the same geographical area. An example of a Region is us-east-1, which is the US East (N. Virginia) Region. You specify a Region when configuring the SDK for JavaScript so that the SDK accesses the resources in that Region. Some services are available only in specific Regions.

The SDK for JavaScript doesn't select a Region by default. However, you can set the Region using an environment variable, a shared config file, or the global configuration object.

In a Client Class Constructor

When you instantiate a service object, you can specify the Region for that resource as part of the client class constructor, as shown here.

var s3 = new AWS.S3({apiVersion: '2006-03-01', region: 'us-east-1'});

Using the Global Configuration Object

To set the Region in your JavaScript code, update the AWS.Config global configuration object as shown here.

AWS.config.update({region: 'us-east-1'});

For more information about current Regions and available services in each Region, see Amazon Regions and Endpoints in the Amazon Web Services General Reference.

Using an Environment Variable

You can set the Region using the AWS_REGION environment variable. If you define this variable, the SDK for JavaScript reads it and uses it.

Using a Shared Config File

Much like the shared credentials file lets you store credentials for use by the SDK, you can keep your Region and other configuration settings in a shared file named config that is used by SDKs. If the AWS_SDK_LOAD_CONFIG environment variable has been set to a truthy value, the SDK for JavaScript automatically searches for a config file when it loads. Where you save the config file depends on your operating system:

  • Linux, macOS, or Unix users: ~/.aws/config

  • Windows users: C:\Users\USER_NAME\.aws\config

If you don't already have a shared config file, you can create one in the designated directory. In the following example, the config file sets both the Region and the output format.

[default] region=us-east-1 output=json

For more information about using shared config and credentials files, see Loading Credentials in Node.js from the Shared Credentials File or Configuration and Credential Files in the Amazon Command Line Interface User Guide.

Order of Precedence for Setting the Region

The order of precedence for Region setting is as follows:

  • If a Region is passed to a client class constructor, that Region is used. If not, then...

  • If a Region is set on the global configuration object, that Region is used. If not, then...

  • If the AWS_REGION environment variable is a truthy value, that Region is used. If not, then...

  • If the AMAZON_REGION environment variable is a truthy value, that Region is used. If not, then...

  • If the AWS_SDK_LOAD_CONFIG environment variable is set to a truthy value and the shared credentials file (~/.aws/credentials or the path indicated by AWS_SHARED_CREDENTIALS_FILE) contains a Region for the configured profile, that Region is used. If not, then...

  • If the AWS_SDK_LOAD_CONFIG environment variable is set to a truthy value and the config file (~/.aws/config or the path indicated by AWS_CONFIG_FILE) contains a Region for the configured profile, that Region is used.